ohej

Working with Alfresco SDK 3: AMPs

Blog Post created by ohej Employee on Apr 14, 2017

Since the release of Alfresco SDK 3, we have gotten a ton of great feedback. While we are working on official documentation for SDK3, I am writing a series of posts that help you get started and get the most out of this release. In this post we will focus on working with AMPs in your project.

 

As mentioned in the release announcement, the SDK now produces JAR files by default. AMPs are still available, but works as an assembly.

 

The Maven Assembly Plugin allows you to take control over the final artifacts that Maven builds. You add the plugin configuration and point it to an XML file that contains the full configuration on the artifact we want to produce.

 

Building AMPs with Alfresco SDK 3

To build AMPs the SDK ships a default assembly XML file that will tell the assembly plugin how to produce an AMP file. You will find this file in "src/main/assembly/amp.xml". The plugin configuration is already present in your pom.xml file and looks like this:

            <plugin>
                <artifactId>maven-assembly-plugin</artifactId>
                <version>2.6</version>
                <executions>
                    <execution>
                        <id>build-amp-file</id>
                        <phase>package</phase>
                        <goals>
                            <goal>single</goal>
                        </goals>
                        <configuration>
                            <appendAssemblyId>false</appendAssemblyId>
                            <descriptor>src/main/assembly/amp.xml</descriptor>
                        </configuration>
                    </execution>
                </executions>
                <dependencies>
                    <dependency>
                        <groupId>org.alfresco.maven.plugin</groupId>
                        <artifactId>alfresco-maven-plugin</artifactId>
                        <version>${alfresco.sdk.version}</version>
                    </dependency>
                </dependencies>
            </plugin>

This section will be commented out by default, so the only thing you need to do in order to produce both a JAR file and an AMP you simple remove the comments, run "mvn package" and you'll see something like this in the output:

[INFO] 
[INFO] --- maven-jar-plugin:2.4:jar (default-jar) @ aio-amp-example-platform-jar ---
[INFO] Building jar: /Users/ohejlskov/work/sdk/tutorials/aio-amp-example/aio-amp-example-platform-jar/target/aio-amp-example-platform-jar-1.0-SNAPSHOT.jar
[INFO]
[INFO] --- maven-assembly-plugin:2.6:single (build-amp-file) @ aio-amp-example-platform-jar ---
[INFO] Building amp: /Users/ohejlskov/work/sdk/tutorials/aio-amp-example/aio-amp-example-platform-jar/target/aio-amp-example-platform-jar-1.0-SNAPSHOT.amp

 

Now you have full control over how your AMPs are built. If you want to change the content of the AMP, you can simply change the assembly "amp.xml" and tailor it to your needs.

 

Installing AMPs with the SDK

When you run your project using the SDK, the Alfresco Maven Plugin will always default to load the JAR version of your module into your project. But now that you're also building an AMP what if you want to tell the Alfresco Maven Plugin to install that AMP using MMT?

 

Well luckily this is easy, let's review the the Alfresco Maven Plugin configuration in your pom.xml. By default it looks something like this (using an all-in-one example but it is the same for platform-jar and share-jar based projects):

            <plugin>
                <groupId>org.alfresco.maven.plugin</groupId>
                <artifactId>alfresco-maven-plugin</artifactId>
                <version>${alfresco.sdk.version}</version>
                <configuration>

                    <!-- We need the flat file H2 database to run the Repo -->
                    <enableH2>true</enableH2>
                    <!-- We always need the Platform/Repo webapp - alfresco.war -->
                    <enablePlatform>true</enablePlatform>
                    <!-- Enable Solr webapp so we can use search -->
                    <enableSolr>true</enableSolr>
                    <!-- We need Share webapp, so we got a UI for working with the Repo -->
                    <enableShare>true</enableShare>
                    <!-- Enable the REST API Explorer -->
                    <enableApiExplorer>true</enableApiExplorer>

                    <!--
                        JARs and AMPs that should be overlayed/applied to the Platform/Repository WAR
                        (i.e. alfresco.war)
                    -->

                    <platformModules>
                        <!-- Share Services will be ignored if you are on Platform earlier than 5.1 -->
                        <moduleDependency>
                            <groupId>${alfresco.groupId}</groupId>
                            <artifactId>alfresco-share-services</artifactId>
                            <version>${alfresco.share.version}</version>
                            <type>amp</type>
                        </moduleDependency>

                        <!-- Bring in custom Modules -->
                        <moduleDependency>
                            <groupId>${project.groupId}</groupId>
                            <artifactId>aio-amp-example-platform-jar</artifactId>
                            <version>${project.version}</version>
                        </moduleDependency>

                        <!-- Bring in the integration tests -->
                        <moduleDependency>
                            <groupId>${project.groupId}</groupId>
                            <artifactId>integration-tests</artifactId>
                            <version>${project.version}</version>
                            <classifier>tests</classifier>
                        </moduleDependency>

                    </platformModules>

                    <!--
                        JARs and AMPs that should be overlayed/applied to the Share WAR (i.e. share.war)
                    -->

                    <shareModules>
                        <!-- Bring in custom Modules -->
                        <moduleDependency>
                            <groupId>${project.groupId}</groupId>
                            <artifactId>aio-amp-example-share-jar</artifactId>
                            <version>${project.version}</version>
                        </moduleDependency>
                    </shareModules>
                </configuration>
            </plugin>

 

Let's assume that we want to use the AMP version of our platform module, in order to do so, we have to look at the <platformModules/> section. By default it will install the Alfresco Share Services, notice that this dependency has <type>amp</type>. Our platform-jar does not have a type specificed so the SDK will assume a JAR by default.
Since we have the assembly plugin enabled now, we know there is an AMP version of this artifact available so the only thing we need to do is to add <type>amp</type> to the module, like this:

<moduleDependency>
    <groupId>${project.groupId}</groupId>
    <artifactId>aio-amp-example-platform-jar</artifactId>
    <version>${project.version}</version>
    <type>amp</type>
</moduleDependency>



When we run the project we can see the following in the output:

[INFO] Configured Artifact: org.alfresco:alfresco-share-services:5.2.d:amp
[INFO] Configured Artifact: dk.ohej.tutorial:aio-amp-example-platform-jar:1.0-SNAPSHOT:amp
[INFO] Copying alfresco-share-services-5.2.d.amp to /Users/ohejlskov/work/sdk/tutorials/aio-amp-example/target/modules/platform/amps/alfresco-share-services-5.2.d.amp
[INFO] Copying aio-amp-example-platform-jar-1.0-SNAPSHOT.amp to /Users/ohejlskov/work/sdk/tutorials/aio-amp-example/target/modules/platform/amps/aio-amp-example-platform-jar-1.0-SNAPSHOT.amp
[info] Installing all AMPs from directory /Users/ohejlskov/work/sdk/tutorials/aio-amp-example/target/modules/platform/amps into WAR/exploded webapp at /Users/ohejlskov/work/sdk/tutorials/aio-amp-example/target/platform-war


This means that the Alfresco Maven Plugin has successfully grabbed the alfresco-share-services.amp, the platform amp module and installed them using MMT.

 

Installing 3rd party AMPs
Looking at the example above we already have the recipie to install 3rd party AMPs, Alfresco Share Services is an AMP that is downloaded and installed by Maven. Still not convinced? Here is an example on how to install Florian Maul's Javascript Console:

            <plugin>
                <groupId>org.alfresco.maven.plugin</groupId>
                <artifactId>alfresco-maven-plugin</artifactId>
                <version>${alfresco.sdk.version}</version>
                <configuration>

                    <!-- We need the flat file H2 database to run the Repo -->
                    <enableH2>true</enableH2>
                    <!-- We always need the Platform/Repo webapp - alfresco.war -->
                    <enablePlatform>true</enablePlatform>
                    <!-- Enable Solr webapp so we can use search -->
                    <enableSolr>true</enableSolr>
                    <!-- We need Share webapp, so we got a UI for working with the Repo -->
                    <enableShare>true</enableShare>
                    <!-- Enable the REST API Explorer -->
                    <enableApiExplorer>true</enableApiExplorer>

                    <!--
                        JARs and AMPs that should be overlayed/applied to the Platform/Repository WAR
                        (i.e. alfresco.war)
                    -->

                    <platformModules>
                        <!-- Share Services will be ignored if you are on Platform earlier than 5.1 -->
                        <moduleDependency>
                            <groupId>${alfresco.groupId}</groupId>
                            <artifactId>alfresco-share-services</artifactId>
                            <version>${alfresco.share.version}</version>
                            <type>amp</type>
                        </moduleDependency>

                        <!-- Bring in custom Modules -->
                        <moduleDependency>
                            <groupId>${project.groupId}</groupId>
                            <artifactId>aio-amp-example-platform-jar</artifactId>
                            <version>${project.version}</version>
                            <type>amp</type>
                        </moduleDependency>

                        <!-- Install Javascript Console -->
                        <moduleDependency>
                            <groupId>de.fmaul</groupId>
                            <artifactId>javascript-console-repo</artifactId>
                            <version>0.6</version>
                            <type>amp</type>
                        </moduleDependency>
                        <!-- Bring in the integration tests -->
                        <moduleDependency>
                            <groupId>${project.groupId}</groupId>
                            <artifactId>integration-tests</artifactId>
                            <version>${project.version}</version>
                            <classifier>tests</classifier>
                        </moduleDependency>

                    </platformModules>

                    <!--
                        JARs and AMPs that should be overlayed/applied to the Share WAR (i.e. share.war)
                    -->

                    <shareModules>
                        <!-- Bring in custom Modules -->
                        <moduleDependency>
                            <groupId>${project.groupId}</groupId>
                            <artifactId>aio-amp-example-share-jar</artifactId>
                            <version>${project.version}</version>
                        </moduleDependency>

                        <!-- Install Javascript Console -->
                        <moduleDependency>
                            <groupId>de.fmaul</groupId>
                            <artifactId>javascript-console-share</artifactId>
                            <version>0.6</version>
                            <type>amp</type>
                        </moduleDependency>
                    </shareModules>
                </configuration>
            </plugin>



Fire up the app with ./run.sh - or mvn install alfresco:run. You'll now see this in the output:

[INFO] Configured Artifact: org.alfresco:alfresco-share-services:5.2.d:amp
[INFO] Configured Artifact: dk.ohej.tutorial:aio-amp-example-platform-jar:1.0-SNAPSHOT:amp
[INFO] Configured Artifact: de.fmaul:javascript-console-repo:0.6:amp
[INFO] Copying alfresco-share-services-5.2.d.amp to /Users/ohejlskov/work/sdk/tutorials/aio-amp-example/target/modules/platform/amps/alfresco-share-services-5.2.d.amp
[INFO] Copying aio-amp-example-platform-jar-1.0-SNAPSHOT.amp to /Users/ohejlskov/work/sdk/tutorials/aio-amp-example/target/modules/platform/amps/aio-amp-example-platform-jar-1.0-SNAPSHOT.amp
[INFO] Copying javascript-console-repo-0.6.amp to /Users/ohejlskov/work/sdk/tutorials/aio-amp-example/target/modules/platform/amps/javascript-console-repo-0.6.amp
[info] Installing all AMPs from directory /Users/ohejlskov/work/sdk/tutorials/aio-amp-example/target/modules/platform/amps into WAR/exploded webapp at /Users/ohejlskov/work/sdk/tutorials/aio-amp-example/target/platform-war
[INFO] Copying javascript-console-share-0.6.amp to /Users/ohejlskov/work/sdk/tutorials/aio-amp-example/target/modules/share/amps/javascript-console-share-0.6.amp
[info] Installing all AMPs from directory /Users/ohejlskov/work/sdk/tutorials/aio-amp-example/target/modules/share/amps into WAR/exploded webapp at /Users/ohejlskov/work/sdk/tutorials/aio-amp-example/target/share-war


Here's the result:

 

I have created a GitHub repository to keep track of the different examples, you can find the complete project here: https://github.com/ohej/alfresco-sdk-tutorials/tree/master/aio-amp-example

Outcomes