Alfresco SDK 3.0 Beta User Guide

Document created by alfresco Employee on May 5, 2017
Version 1Show Document
  • View in full screen mode

Alfresco SDK 3.0 Beta - User Guide

Author: Martin Bergljung

 

Introduction

Alfresco Maven Plugin

Support for different versioning of Platform and Share UI

Maven Profiles

From AMPs to JARs

From Spring Loaded to JRebel or HotSwap

The end of Tomcat Virtual Webapp Context

Support for multiple Alfresco Versions

All-In-One (AIO) Project change

Prerequisites

Java

Maven

Hot Reloading

JRebel

HotSwap

Working with SDK Projects

All-In-One (AIO)

Generating from Maven Archetype

Running

Using an Enterprise version

Using Enterprise Libraries

Using the Platform REST API Explorer

Logging

Platform application logging

Share application logging

Hot reloading

Prerequisites

JRebel

HotSwap

Hot reloading of Platform extensions

Basic Platform Web Script hot reloading

Reloading Web Resources (JRebel only)

Spring Context Reloading (JRebel only)

Hot reloading of Share extensions

Testing

Overriding Web Resources and Adding 3rd party Libraries (Using AMPs)

Using a custom context path for the Share webapp

Adding Custom Webapps when running

Adding Custom System Properties when running

Using Standalone Databases

Using a MySQL Database

Using a PostgreSQL Database

Using an Enterprise Database

Custom WAR artifacts

Using older Alfresco versions

Using Alfresco 5.1

Using Alfresco 5.0

Using Alfresco 4.2

Platform JAR Modules

Generating from Maven Archetype

Running

Using an Enterprise version

Using Enterprise Libraries

Using the REST API Explorer

Logging

Hot reloading

Overriding Web Resources and Adding 3rd party Libraries (Using AMPs)

Adding Custom Webapps when running

Adding Custom System Properties when running

Testing

Using Standalone Databases

Custom WAR artifact

Using older Alfresco versions

Using Alfresco 5.1

Using Alfresco 5.0

Using Alfresco 4.2

Share JAR Modules

Generating from Maven Archetype

Running

Using an Enterprise version

Logging

Hot reloading

Overriding Web Resources and Adding 3rd party Libraries (Using AMPs)

Using a custom context path for the Share webapp

Adding Custom Webapps when running

Adding Custom System Properties when running

Testing

Custom WAR artifacts

Using older Alfresco versions

Using Alfresco 5.1

Using Alfresco 5.0

Using Alfresco 4.2

Activiti JAR Modules

Generating from Maven Archetype

Applying a license file

Running

Updating the HelloWorld application

Logging

Hot reloading

Testing

Using Standalone Databases

Custom WAR artifact

Upgrading previous SDK 2.2 projects to SDK 3

Introduction

Alfresco SDK 3 is a major overhaul of the SDK and provides several improvements on   previous SDKs.

Alfresco Maven Plugin

The most significant change is that we now keep most of the build logic, run logic, and project configuration inside the Alfresco Maven Plugin. This means that the POMs will be a lot slimmer and they will also not depend on a parent SDK POM. This will make upgrades easier and you can now use your own Maven parent POM.

 

The plug-in now builds the project web applications as follows:

Alfresco Maven Plugin - Build Logic - SDK 3.png

There are a couple of things we need to feed the plugin with, such as what version of the different WAR artifacts we want to use, database configuration, location of alf_data etc. This is still all done in the project POM properties section:

 

<properties>

   <!-- Alfresco Maven Plugin version to use -->

   <alfresco.sdk.version>3.0.0-SNAPSHOT</alfresco.sdk.version>

 

   <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>

 

   <!-- Alfresco Data directory, which will contain:

         Content Store (i.e. the files we upload)

         Database (i.e. the metadata for the uploaded files)

         Search index (i.e. the indexed content and metadata)

        Configured in alfresco-global.properties with the 'dir.root' property.

         -->

   <alfresco.data.location>${session.executionRootDirectory}/alf_data_dev

</alfresco.data.location>

 

   <!-- Duplicated with alfresco.solrHome in the plugin,

we need them out here to do filtering -->

   <solr.home>${alfresco.data.location}/solr</solr.home>

   <solr.model.dir>${solr.home}/alfrescoModels</solr.model.dir>

   <solr.content.dir>${solr.home}/index</solr.content.dir>

 

   <!-- Properties used in dependency declarations, you don't need to change these -->

   <alfresco.groupId>org.alfresco</alfresco.groupId>

   <alfresco.share.war.artifactId>share</alfresco.share.war.artifactId>

   <!-- Platform WAR artifact, change to 'alfresco-enterprise' if using Enterprise Edition -->

   <alfresco.platform.war.artifactId>alfresco-platform</alfresco.platform.war.artifactId>

 

   <!-- Alfresco Platform and Share webapp versions,

these are the original Alfresco webapps that will be

        customized and then deployed and run by the tomcat maven plugin when

        executing for example $ mvn clean install alfresco:run -->

   <alfresco.platform.version>5.2.b-EA</alfresco.platform.version>

   <alfresco.share.version>5.2.a-EA</alfresco.share.version>

 

   <!-- Alfresco Surf version, if you change Share version you

might need to change Surf version -->

   <alfresco.surf.version>6.6</alfresco.surf.version>

 

   <!-- Aikau framework version, it is released separately, so it can be useful to be able

        to bring in newer versions with bug fixes etc -->

   <aikau.version>1.0.85</aikau.version>

 

   <!-- JRebel Hot reloading of classpath stuff and web resource stuff -->

   <jrebel.version>1.1.6</jrebel.version>

 

   <!-- Environment to use, Alfresco Maven Plugin will

copy alfresco-global-*.properties files from this directory -->

   <env>local</env>

 

   <!-- Compile with Java 7, default is 5 -->

   <maven.compiler.source>1.7</maven.compiler.source>

   <maven.compiler.target>1.7</maven.compiler.target>

</properties>

 

 

Note that the Platform (alfresco.war) and Share (share.war) artifacts are now released with their own individual version numbers. And the artifactId for the alfresco.war artifact has changed to alfresco-platform from version 5.2.

 

We control what modules (AMPs and JARs) that should be applied to each WAR and what webapps we want to run via Alfresco Maven plugin configuration:

 

<plugin>

   <groupId>org.alfresco.maven.plugin</groupId>

   <artifactId>alfresco-maven-plugin</artifactId>

   <version>${alfresco.sdk.version}</version>

   <configuration>

       <!-- Default is to run with a Community edition,

change to 'enterprise' if using Enterprise edition -->

       <alfrescoEdition>community</alfrescoEdition>

 

       <!-- 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>

 

       <!--

           JARs and AMPs that should be overlayed/applied to the Platform/Repository WAR

           (i.e. alfresco.war)

       -->

       <platformModules>

           <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-platform-jar</artifactId>

               <version>${project.version}</version>

           </moduleDependency>

       </platformModules>

 

       <!--

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

       -->

       <shareModules>

           <moduleDependency>

               <!-- Bring in a newer version, can coexist with older versions

                    in the WAR disttribution, newest version is picked -->

               <groupId>${alfresco.groupId}</groupId>

               <artifactId>aikau</artifactId>

               <version>${aikau.version}</version>

           </moduleDependency>

 

           <!-- Bring in custom Modules -->

           <moduleDependency>

               <groupId>${project.groupId}</groupId>

               <artifactId>aio-share-jar</artifactId>

               <version>${project.version}</version>

           </moduleDependency>

       </shareModules>

   </configuration>

</plugin>

Support for different versioning of Platform and Share UI

The Alfresco product is no longer released under one common version, such as 5.1.e. The Platform (i.e. alfresco.war) and the Share UI (share.war) are now released with individual version numbers, such as Platform 5.2.a-EA and Share 5.1.g. SDK 3 supports specifying different versions for these artifacts.

Maven Profiles

Profiles are no longer used for running the project or for enabling Enterprise editions. The runner logic is built into the Alfresco Maven Plugin and to use an Enterprise version you will specify its version in the properties section, and bring in relevant specific Enterprise dependencies.

 

This means that the artifacts that are produced are always the same and not affected by what profile(s) that have been activated.

From AMPs to JARs

Next big change is that we have moved from AMPs to JAR modules as default project and artifact structure. AMPs are still produced via the Maven Assembly plugin, but the main module type we are working with is simple JAR modules.

 

JARs are the default artifact type that Maven works with, so using simple JAR modules solves a lot of problems. For example, by using simple JAR modules we solve the long standing problem of depending on modules and using classes in them. This was not possible with AMPs but is now easy to do with a standard Maven <dependency> declaration. Also, most IDEs and build tools are familiar with JARs.

 

We also avoid overwrite problems that can occur quite easily with AMPs, see the following picture:

AMP Modules - Overview Share (1).png

It is also not trivial to uninstall an AMP as the files in the /config and /web directories are copied into the WAR. Looking at the same example using JAR modules:

 

JAR Modules - Overview Share.png

 

We can see that things have improved, you still got possible JAR conflicts but at least you would be aware of them.

 

To summarize, JAR Modules have some advantages over AMPs:

 

  1. They can be easily installed and uninstalled
  2. They don’t accidentally overwrite files from the product or other extensions
  3. Maven likes and knows about JARs
  4. Development Environments knows about JARs
  5. Developers knows about JARs

From Spring Loaded to JRebel or HotSwap

Another change is that we no longer use Spring Loaded for hot reloading. Instead we use JRebel or the open source alternative HotSwap, which works a lot better and gives hot reloading of Spring context (only JRebel), classes, web resources, property files etc. in both the alfresco.war and the share.war. So now you can for example add a property to your Java backed Web Script controller bean and it is hot reloaded. You can even define new beans and they are hot reloaded. As you might know, in the latest SDK release 2.2.0 you could no longer use Spring Loaded for hot reloading of stuff in alfresco.war.

The end of Tomcat Virtual Webapp Context

By using JRebel we could also remove the use of Tomcat Virtual Webapp contexts, which has been a bit confusing. The Virtual Webapp contexts were used to define where in the project structure the Tomcat server should look for web resources (e.g. scripts and images) and classes for a specific web application.

 

When you generated an AIO project the Virtual webapp contexts were set up correctly for the included Repository AMP and Share AMP, so it worked nicely as long as you did not add more AMPs, then you had to remember to update the virtual webapp context with these AMPs’ web resources and classes, which could be a bit confusing and error prone.

 

For the virtual webapp context solution to work, we had to exclude the web resources from the produced AMPs, otherwise they would not be picked up from the project structure when they were updated. This led to more confusion as if you took an AMP file that you had just tested in your AIO project (using mvn clean install -Prun) and installed it into a standard Alfresco installation, it would not work as it would be missing the /web folder.

 

With SDK 3 there is no longer the need to configure and use virtual webapp context files and the JARs and AMPs that are produced are always complete and ready to deploy into a stand-alone Alfresco installation.

Support for multiple Alfresco Versions

With SDK 3 we also wanted to be able to support multiple versions of Alfresco to simplify upgrades and avoid a complicated compatibility matrix. The SDK 3 projects are by default generated with Platform version set to 5.2.a-EA and Share UI version set to 5.1.g.

 

However, you can also use SDK 3 with Alfresco version 4.2, 5.0, and 5.1. This is possible by having most of the build and run logic inside the Alfresco Maven Plugin.

All-In-One (AIO) Project change

The AIO project has been simplified as a result of build logic, run logic, and project configuration being moved into the Alfresco Maven Plugin. For more information about the new AIO project see this section.

Prerequisites

In order to use the Alfresco SDK you will need a Java Development Kit (JDK) version 8 installed and a Maven version 3.3 installed. Optionally you will need JRebel for hot reloading of web resources, configuration, and classes.

Java

Download JDK 8 from this site, and install by running installer.

 

Verify installation, both JDK and JRE:

 

$ javac -version

javac 1.8.0_91

$ java -version

java version "1.8.0_91"

Java(TM) SE Runtime Environment (build 1.8.0_91-b14)

Java HotSpot(TM) 64-Bit Server VM (build 25.91-b14, mixed mode)

 

Make sure JAVA_HOME is setup correctly, so other tools like Maven will use correct version:

 

$ env|grep JAVA_HOME

JAVA_HOME=/usr/lib/jvm/java-8-oracle

Maven

Download Apache Maven from this site, and install.

 

Verify installation:

 

$ mvn -v

Apache Maven 3.3.3 (7994120775791599e205a5524ec3e0dfe41d4a06; 2015-04-22T12:57:37+01:00)

Maven home: /home/martin/apps/apache-maven-3.3.3

Java version: 1.8.0_91, vendor: Oracle Corporation

Java home: /usr/lib/jvm/java-8-oracle/jre

Default locale: en_GB, platform encoding: UTF-8

OS name: "linux", version: "4.2.0-38-generic", arch: "amd64", family: "unix"

 

Make sure MAVEN_OPTS and M2_HOME is setup correctly:

 

$ env|grep M2

M2_HOME=/home/martin/apps/apache-maven-3.3.3

 

$ env|grep MAV

MAVEN_OPTS=-Xms256m -Xmx1G

 

Hot Reloading

For hot reloading of classes and web resources the JRebel and HotSwap Java Agents can be used. JRebel is a commercial product while HotSwap is open source. Both products can reload classes and web resources. However, JRebel is more powerful than HotSwap and can for example also reload changes to the Spring XML context files.

JRebel

You can try out JRebel using a trial license. Download JRebel from this site, and install (download the nightly build to get the latest features with Spring Context reload etc):

 

Update the MAVEN_OPTS config to look something like this:

 

MAVEN_OPTS=-Xms256m -Xmx1G -agentpath:/home/martin/apps/jrebel/lib/libjrebel64.so

HotSwap

Download HotSwap JVM and Java Agent from this site, and install (download the nightly build to get the latest features).

 

martin@gravitonian:~/Downloads/HotSwap$ sudo java -jar DCEVM-light-8u92-installer.jar

 

  1. Choose what JVM to replace by Dynamic Code Evolution VM (DCEVM).
  2. Install DCEVM as altvm

 

Verify DCEVM:

 

martin@gravitonian:~/Downloads/HotSwap$ java -version

java version "1.8.0_91"

Java(TM) SE Runtime Environment (build 1.8.0_91-b14)

Dynamic Code Evolution 64-Bit Server VM (build 25.71-b01-dcevmlight-1, mixed mode)

 

Update the MAVEN_OPTS config to look something like this:

 

export MAVEN_OPTS="-Xms256m -Xmx1G -XXaltjvm=dcevm -javaagent:/home/martin/apps/hotswap/hotswap-agent.jar"

Working with SDK Projects

The SDK 3 comes with three project archetypes: All-In-One, Platform JAR, and Share JAR. This is similar to previous SDKs. This section will go through how to use each one of these project Maven archetypes (i.e. project templates).

All-In-One (AIO)

This section covers how to use the new SDK 3 All-in-One project.

Generating from Maven Archetype

To generate a project based on the AIO Maven archetype do the following (make sure Maven environment is setup properly):

 

martin@gravitonian:~$ mvn archetype:generate -DarchetypeCatalog=https://artifacts.alfresco.com/nexus/content/groups/public/archetype-catalog.xml -Dfilter=org.alfresco.maven.archetype:

[INFO] Scanning for projects...

...

Choose archetype:

1: https://artifacts.alfresco.com/nexus/content/groups/public/archetype-catalog.xml -> org.alfresco.maven.archetype:alfresco-amp-archetype (Sample project with full support for lifecycle and rapid development of AMPs (Alfresco Module Packages))

2: https://artifacts.alfresco.com/nexus/content/groups/public/archetype-catalog.xml -> org.alfresco.maven.archetype:alfresco-allinone-archetype (Sample multi-module project for All-in-One development on the Alfresco plaftorm. Includes modules for: Repository WAR overlay, Repository AMP, Share WAR overlay, Solr configuration, and embedded Tomcat runner)

3: https://artifacts.alfresco.com/nexus/content/groups/public/archetype-catalog.xml -> org.alfresco.maven.archetype:share-amp-archetype (Share project with full support for lifecycle and rapid development of AMPs (Alfresco Module

        Packages))

4: https://artifacts.alfresco.com/nexus/content/groups/public/archetype-catalog.xml -> org.alfresco.maven.archetype:alfresco-platform-jar-archetype (Sample project with full support for lifecycle and rapid development of Platform/Repository JARs and AMPs (Alfresco Module Packages))

5: https://artifacts.alfresco.com/nexus/content/groups/public/archetype-catalog.xml -> org.alfresco.maven.archetype:alfresco-share-jar-archetype (Share project with full support for lifecycle and rapid development of JARs and AMPs (Alfresco Module

        Packages))

6: https://artifacts.alfresco.com/nexus/content/groups/public/archetype-catalog.xml -> org.alfresco.maven.archetype:activiti-jar-archetype (Sample project with full support for lifecycle and rapid development of Activiti JARs)

Choose a number or apply filter (format: [groupId:]artifactId, case sensitive contains): : 2

Choose org.alfresco.maven.archetype:alfresco-allinone-archetype version:

1: 1.0

2: 1.0.1

3: 1.0.2

4: 1.1.0

5: 1.1.1

6: 3.0.0-beta-4

7: 3.0.0-beta-5

Choose a number: 7: <hit enter>

Define value for property 'groupId': : org.alfresco.test

Define value for property 'artifactId': : aio

[INFO] Using property: version = 1.0-SNAPSHOT

Define value for property 'package':  org.alfresco.test: : <hit enter>

Confirm properties configuration:

groupId: org.alfresco.test

artifactId: aio

version: 1.0-SNAPSHOT

package: org.alfresco.test

 Y: : <hit enter>

 

 

Here we choose the second archetype (2) called alfresco-allinone-archetype. Then we specify Maven groupId and artifactId for the new project, this can be whatever you like. We use the same Java package path as groupId.

 

This generates a project structure as follows:

 

.

└── aio

    ├── aio-platform-jar

    │   ├── pom.xml

    │   └── src

    │       ├── main

    │       │   ├── assembly

    │       │   │   ├── amp.xml

    │       │   │   ├── file-mapping.properties

    │       │   │   ├── lib

    │       │   │   │   └── README.md

    │       │   │   └── web

    │       │   │       └── README.md

    │       │   ├── java

    │       │   │   └── org

    │       │   │       └── alfresco

    │       │   │           └── test

    │       │   │               └── platformsample

    │       │   │                   ├── DemoComponent.java

    │       │   │                   ├── Demo.java

    │       │   │                   └── HelloWorldWebScript.java

    │       │   └── resources

    │       │       ├── alfresco

    │       │       │   ├── extension

    │       │       │   │   └── templates

    │       │       │   │       └── webscripts

    │       │       │   │           └── alfresco

    │       │       │   │               └── tutorials

    │       │       │   │                   ├── helloworld.get.desc.xml

    │       │       │   │                   ├── helloworld.get.html.ftl

    │       │       │   │                   └── helloworld.get.js

    │       │       │   └── module

    │       │       │       └── aio-platform-jar

    │       │       │           ├── alfresco-global.properties

    │       │       │           ├── context

    │       │       │           │   ├── bootstrap-context.xml

    │       │       │           │   ├── service-context.xml

    │       │       │           │   └── webscript-context.xml

    │       │       │           ├── messages

    │       │       │           │   └── content-model.properties

    │       │       │           ├── model

    │       │       │           │   ├── content-model.xml

    │       │       │           │   └── workflow-model.xml

    │       │       │           ├── module-context.xml

    │       │       │           ├── module.properties

    │       │       │           └── workflow

    │       │       │               └── sample-process.bpmn20.xml

    │       │       └── META-INF

    │       │           └── resources

    │       │               └── test.html

    │       └── test

    │           └── java

    │               └── org

    │                   └── alfresco

    │                       └── test

    ├── aio-share-jar

    │   ├── pom.xml

    │   └── src

    │       ├── main

    │       │   ├── assembly

    │       │   │   ├── amp.xml

    │       │   │   ├── file-mapping.properties

    │       │   │   ├── lib

    │       │   │   │   └── README.md

    │       │   │   └── web

    │       │   │       └── README.md

    │       │   ├── java

    │       │   │   └── org

    │       │   │       └── alfresco

    │       │   │           └── test

    │       │   └── resources

    │       │       ├── alfresco

    │       │       │   ├── module

    │       │       │   │   └── aio-share-jar

    │       │       │   │       └── module.properties

    │       │       │   └── web-extension

    │       │       │       ├── aio-share-jar-slingshot-application-context.xml

    │       │       │       ├── messages

    │       │       │       │   └── aio-share-jar.properties

    │       │       │       ├── site-data

    │       │       │       │   └── extensions

    │       │       │       │       └── aio-share-jar-example-widgets.xml

    │       │       │       └── site-webscripts

    │       │       │           ├── com

    │       │       │           │   └── example

    │       │       │           │       └── pages

    │       │       │           │           ├── simple-page.get.desc.xml

    │       │       │           │           ├── simple-page.get.html.ftl

    │       │       │           │           └── simple-page.get.js

    │       │       │           └── org

    │       │       │               └── alfresco

    │       │       │                   └── README.md

    │       │       └── META-INF

    │       │           ├── resources

    │       │           │   └── aio-share-jar

    │       │           │       └── js

    │       │           │           └── tutorials

    │       │           │               └── widgets

    │       │           │                   ├── css

    │       │           │                   │   └── TemplateWidget.css

    │       │           │                   ├── i18n

    │       │           │                   │   └── TemplateWidget.properties

    │       │           │                   ├── templates

    │       │           │                   │   └── TemplateWidget.html

    │       │           │                   └── TemplateWidget.js

    │       │           └── share-config-custom.xml

    │       └── test

    │           └── java

    │               └── org

    │                   └── alfresco

    │                       └── test

    ├── debug.bat

    ├── debug.sh

    ├── pom.xml

    ├── README.md

    ├── run.bat

    ├── run.sh

    └── src

        └── test

            ├── license

            │   └── README.md

            ├── properties

            │   └── local

            │       ├── alfresco-global-enterprise.properties

            │       ├── alfresco-global-h2.properties

            │       ├── alfresco-global-mysql.properties

            │       └── alfresco-global-postgresql.properties

            └── resources

                ├── alfresco

                │   └── extension

                │       ├── dev-log4j.properties

                │       └── disable-webscript-caching-context.xml

                └── tomcat

                    └── context-solr.xml

 

 

As you can see, there are no longer any WAR projects, Runner project, or Solr Config project, just the two JAR module projects. All the webapp assembly and runner logic is now handled by the Alfresco Maven Plugin. So you are probably thinking, if there are no WAR projects, how do I configure what JARs and AMPs that should be applied to the standard alfresco.war and share.war?

 

The Alfresco Maven Plugin now provides extra configuration sections <platformModules> and <shareModules> where you can specify what modules should be applied to each WAR file:

 

<plugin>

   <groupId>org.alfresco.maven.plugin</groupId>

   <artifactId>alfresco-maven-plugin</artifactId>

   <version>${alfresco.sdk.version}</version>

   <configuration>

       <!-- Default is to run with a Community edition,

change to 'enterprise' if using Enterprise edition -->

       <alfrescoEdition>community</alfrescoEdition>

 

       <!-- 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>

 

       <!--

           JARs and AMPs that should be overlayed/applied to the Platform/Repository WAR

           (i.e. alfresco.war)

       -->

       <platformModules>

           <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-platform-jar</artifactId>

               <version>${project.version}</version>

           </moduleDependency>

       </platformModules>

 

       <!--

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

       -->

       <shareModules>

           <moduleDependency>

               <!-- Bring in a newer version, can coexist with older versions

                    in the WAR disttribution, newest version is picked -->

               <groupId>${alfresco.groupId}</groupId>

               <artifactId>aikau</artifactId>

               <version>${aikau.version}</version>

           </moduleDependency>

 

           <!-- Bring in custom Modules -->

           <moduleDependency>

               <groupId>${project.groupId}</groupId>

               <artifactId>aio-share-jar</artifactId>

               <version>${project.version}</version>

           </moduleDependency>

       </shareModules>

   </configuration>

</plugin>

Running

To run the new AIO project with the JAR modules applied to respective WAR, step into the AIO directory and execute the following command:

 

$ cd aio/

aio$ mvn clean install alfresco:run

 

Note the new way of running the project via the alfresco plugin instead of via a Maven profile.

 

Access the webapps as usual:

 

http://localhost:8080/share:

 

 

http://localhost:8080/alfresco:

 

 

The generated AIO project comes with sample code such as Platform Web Script and Share Aikau page.

 

Try out the Web Script as follows (http://localhost:8080/alfresco/service/sample/helloworld):

 

It uses both a Java and JavaScript controller.

 

The Aikau page can be accessed as follows (http://localhost:8080/share/page/user/admin/dashboard):

 

 

The Aikau page also includes a sample Aikau widget.

Using an Enterprise version

If you would like to work with the Alfresco Enterprise Edition, then this requires just a few property changes and a license installation. You also need to have access to the private Alfresco Nexus repos. To configure access to private repos see these docs.

 

Install an enterprise license, otherwise the server will be in read-only mode. It goes into the following location in main resources (you will have to create directories):

 

└── src

    └── main

        └── resources

            ├── alfresco

            │   └── extension

            │       └── license

            │           └── Ent5.1-AllEnabled-Exp01012017.lic

 

The license will be injected into the platform war before it is deployed to Tomcat.

 

Configure Enterprise version in aio/pom.xml, let’s use Platform version 5.1.1 and Share version 5.1.1 (the surf version is slightly older than the default one in SDK 3), also the platform artifactId changes for Enterprise edition:

 

<alfresco.platform.war.artifactId>alfresco-enterprise</alfresco.platform.war.artifactId>

<alfresco.platform.version>5.1.1</alfresco.platform.version>

<alfresco.share.version>5.1.1</alfresco.share.version>

<alfresco.surf.version>6.3</alfresco.surf.version>

 

If you are unclear of what Surf version that is used, then install the Alfresco version you will be using and do a search in WEB-INF/lib as follows:

 

martin@gravitonian:/opt/alfresco511/tomcat/webapps/share/WEB-INF/lib$ ls -l *surf*

-rw-rw-r-- 1 martin martin 870024 Jul 13 10:49 spring-surf-6.3.jar

-rw-rw-r-- 1 martin martin  38968 Jul 13 10:51 spring-surf-api-6.3.jar

 

Change the Alfresco Edition property in the Alfresco Maven plugin configuration to enterprise, this is also done in aio/pom.xml:

 

<plugin>

   <groupId>org.alfresco.maven.plugin</groupId>

   <artifactId>alfresco-maven-plugin</artifactId>

   <version>${alfresco.sdk.version}</version>

   <configuration>

       <!-- Default is to run with a Community edition,

            change to 'enterprise' if using Enterprise edition -->

       <alfrescoEdition>enterprise</alfrescoEdition>

. . .

 

Changing this to enterprise helps the Alfresco Maven plugin to pick up the correct database H2 scripts.

 

Note. there is no longer a need to update any of the run.* scripts to use an Enterprise edition. This was previously necessary when the Enterprise edition was enabled via a profile.

 

Now delete the alf_data_dev directory and restart:

 

aio$ rm -rf alf_data_dev/

aio$ mvn clean install alfresco:run

 

You should see evidence in the logs that your are running Enterprise edition and that license is found:

 

 2016-08-18 18:41:33,583  INFO  [service.descriptor.DescriptorService] [localhost-startStop-1] Alfresco license: Mode ENTERPRISE, cluster:enabled granted to ness51team limited to 486 days expiring Sun Jan 01 00:00:00 GMT 2017 (136 days remaining).

 2016-08-18 18:41:33,583  INFO  [service.descriptor.DescriptorService] [localhost-startStop-1] Server Mode :UNKNOWN

 2016-08-18 18:41:33,591  INFO  [service.descriptor.DescriptorService] [localhost-startStop-1] Alfresco started (Enterprise). Current version: 5.1.1 (r125847-b80) schema 9,029. Originally installed version: 5.1.1 (r125847-b80) schema 9,029.

 

Access the webapps as usual (username: admin, pwd: admin):

 

http://localhost:8080/share 

http://localhost:8080/alfresco

 

 

The generated AIO project comes with sample code such as Platform Web Script and Share Aikau page. Try out the Web Script as follows (http://localhost:8080/alfresco/service/sample/helloworld):

 

It uses both a Java and JavaScript controller.

 

The Aikau page can be accessed as follows (http://localhost:8080/share/page/hdp/ws/simple-page):

 

It shows how to create an Aikau page with a custom Aikau widget on it.

 

So, changing Alfresco version and running was very easy, basically just updating a few properties.

Using Enterprise Libraries

When you enabled the Enterprise edition via a profile in previous versions of the SDK some extra Enterprise libraries were brought in. Such as the following in the platform AMP:

 

<profile>

   <id>enterprise</id>

   <dependencies>

       <dependency>

           <groupId>${alfresco.groupId}</groupId>

           <artifactId>alfresco-enterprise-repository</artifactId>

           <version>${alfresco.version}</version>

           <scope>provided</scope>

       </dependency>

   </dependencies>

</profile>

 

You will now have to add these manually in the Platform Jar Module (i.e. in aio/aio-platform-jar/pom.xml):

 

<dependencies>

   <!-- The main Alfresco Repo dependency for compiling Java code in src/main/java -->

   <dependency>

       <groupId>${alfresco.groupId}</groupId>

       <artifactId>alfresco-repository</artifactId>

   </dependency>

 

   <dependency>

       <groupId>${alfresco.groupId}</groupId>

       <artifactId>alfresco-enterprise-repository</artifactId>

       <version>${alfresco.platform.version}</version>

       <scope>provided</scope>

   </dependency>

</dependencies>

Using the Platform REST API Explorer

The AIO project has the REST API Explorer version 1.2 deployed when you are running the project. Access it via the http://localhost:8080/api-explorer URL:

 

 

With the API Explorer you can try out all the different APIs that are available to manage and manipulate the content in the repository.

Logging

Logging happens for each of the web applications. So when building customizations for the Platform application, logging levels for custom code will be configured in a Log4J config file for that application. And when building customizations for the Share application, logging levels for custom code will be configured in a Log4J file for that application.

Platform application logging

When building customizations for the Platform/Repository it is likely that there will be a requirement to support logging at different levels. There are two samples where you can see how logging works. One is in the DemoComponent class where the following snippet of code logs some stuff:

 

protected void executeInternal() throws Throwable {

   System.out.println("DemoComponent has been executed");

   logger.debug("Test debug logging. Congratulation your JAR Module is working");

   logger.info("This is only for information purpose. Better remove me from the log in Production");

}

 

Both the debug log and the info log will be printed when the Alfresco server is started, the aio/alfresco.log file contains the logging:

 

 2016-09-19 13:49:22,474  INFO  [repo.module.ModuleServiceImpl] [localhost-startStop-1] Installing module 'aio-platform-jar2' version 1.0-SNAPSHOT.

 DemoComponent has been executed

2016-09-19 13:49:22,483  DEBUG [test.platformsample.DemoComponent] [localhost-startStop-1] Test debug logging. Congratulation your JAR Module is working

 2016-09-19 13:49:22,483  INFO  [test.platformsample.DemoComponent] [localhost-startStop-1] This is only for information purpose. Better remove me from the log in Production

 

Note. the above logging will only happen the first time you start the server with this component/module installed. It only executes once. To see the log again, you would have to remove the alf_data_dev directory and restart.

 

There is also logging happening every time you call the Hello World Web Script. The Java controller in the HelloWorldWebScript class does the following logging:

 

protected Map<String, Object> executeImpl(

       WebScriptRequest req, Status status, Cache cache) {

   Map<String, Object> model = new HashMap<String, Object>();

   model.put("fromJava", "HelloFromJava");

 

   logger.debug("Your 'Hello World' Web Script was called!");

 

   return model;

}

 

Executing the Web Script at the