Migration of All-In-One project to SDK 3.0

[ycoulon]

This article provides information on how to migrate a project using the Alfresco Maven SDK version 2.2.0 to the new version 3.0.

Before starting I recommend to read the official SDK 3.0 documentation : http://docs.alfresco.com/5.2/concepts/sdk-getting-started.html, the Alfresco Beta User guide is also a good reference : https://community.alfresco.com/docs/DOC-6855-alfresco-sdk-30-beta-user-guide

Why upgrade to new SDK

The SDK version 3 get rid of the compatibility matrix and supports the following Alfresco version :

• 4.2.X
• 5.0.X
• 5.1.X
• 5.2.X

The SDK also supports the community release.

The targeted version is set by a property (alfresco.platform.version and alfresco.share.version) so it's easy to switch target version.

Upgrading to newest version of the SDK is easier than before since the version is set using the property : alfresco.sdk.version

The SDK 3 now produce JAR file by default, but can also produce AMPs if you need. All the archetype have been revamped to follow standard folder structure.

Hot reloading is available using HotSwapAgent or Jrebel (you need license for this one). Both allow to reload classes and web-resources. But Jrebel is more powerful and allows to reload spring context file.

For more information about HotReloading and how to setup please refer to the official documentation : http://docs.alfresco.com/5.2/concepts/sdk-hot-reloading.html

The new version of SDK is highly configurable. The Alfresco Maven plugin that handle running and testing your module offer 40 configurable parameters. The execution is controlled by the maven command: "mvn install alfresco:run"

Migrating your project

The SDK 3.0 revamped project structure introduces a major change since the version 2.2.0 so it's no longer compatible. The recommended approach is to create a new project based on the version 3.0 and migrate your project file to this new project.

Generate and configure your new project

The maven archetype are up to date and can be used to generate a new project compatible to the new version with the command "mvn archetype:generate -Dfilter=org.alfresco:"

Since we are talking about an old All-In-One project we will use the all-in-one archetype (org.alfresco.maven.archetype:alfresco-allinone-archetype) in the version 3.0.1.

Maven will take care of generating the folder structure and the default configuration.

By default generated project are configured to use the following community version:

• Platform : 5.2.e
• Share: 5.2.f

You can adjust the version by updating the properties :

• alfresco.platform.version
• alfrescco.share.version

If you want to use enterprise version you will need to update the properties "maven.alfresco.edition" replacing "community" with "enterprise". You also need valid credential for the alfresco-private repository to retrieve archetype.

If you need to test your extension with external dependency (such as RM), you can configure the Alfresco Maven Plugin to install those module on your platform or your share when running locally.

In order to achieve this you will need to add the module to the "platformModules" and "shareModules" in the configuration section for "alfresco-maven-plugin".

For example if you want to add Record Management Community version 2.6.0 to your platform and share you need to add:

• In the platformModules section:

<moduleDependency>

<groupId>org.alfresco</groupId>

<artifactId>alfresco-rm-community-repo</artifactId>

<version>2.6.c</version>

<type>amp</type>

</moduleDependency>

• In the shareModules section:

<moduleDependency>

<groupId>org.alfresco</groupId>

<artifactId>alfresco-rm-community-share</artifactId>

<version>2.6.c</version>

<type>amp</type>

</moduleDependency>

You can find those information on Alfresco Nexus repository.

You can start alfresco locally using the Alfresco Maven plugin to test your configuration.

Move your project to SDK 3.0 project

In the following section I will use an OOTB SDK 2.2.0 project generated with maven :

$ mvn archetype:generate -Dfilter=org.alfresco.maven.archetype:

With the following parameter:

Archetype version: 2.2.0

Define value for property 'groupId': com.example

Define value for property 'artifactId': aio

[INFO] Using property: version = 1.0-SNAPSHOT

Define value for property 'package' com.example: :

The target project will be generated from maven too with the same command and the following parameters :

Archetype version: 3.0.1

Define value for property 'groupId': com.example

Define value for property 'artifactId': aio30

[INFO] Using property: version = 1.0-SNAPSHOT

Define value for property 'package' com.example: :

So our project to migrate holds 2 extensions sub-module :

• aio-repo-amp : I will refer to the root of this sub-module as AIO_REPO_ROOT
• aio-share-amp  : I will refer to the root of this sub-module as AIO_SHARE_ROOT

And the new project also holds 2 extensions:

• aio30-platform-jar:  : I will refer to the root of this sub-module as AIO30_PLATFORM_ROOT
• aio30-share-jar : I will refer to the root of this sub-module as AIO30_SHARE_ROOT

Java Code

Java code is the easy part since the location of java class is standard in maven projects:

• Copy AIO_REPO_ROOT/src/main/java/* to AIO30_PLATFORM_ROOT/src/main/java
• Copy AIO_SHARE_ROOT/src/main/java/* to AIO30_SHARE_ROOT/src/main/java

Config folder (PROJECT_ROOT/src/main/amps/config)

When installing an AMP into an alfresco.war (or share.war) the content of this folder is expanded into <ROOT>/WEB-INF/classes.  In the new SDK,  such content goes into the resources folder since the resources folder is equivalent to the classpath root.

• Copy the content of AIO_REPO_ROOT/src/main/amps/config/* to AIO30_PLATFORM_ROOT/src/main/resources
• Copy the content of AIO_SHARE_ROOT/src/main/amps/config/* to AIO30_SHARE_ROOT/src/main/resources

Web folder (PROJECT_ROOT/src/main/amps/web)

This folder is used to hold web resources (CSS, JS….). In the new SDK those kind of files can go into 2 location:

• PROJECT_ROOT/src/main/resources/META-INF/resources
• PROJECT_ROOT/src/main/assembly/web

The first option is compatible with delivering a JAR file or an AMP file. The second can only be used if you plan to deliver AMP file. With the first option, your files will be compressed into the jar file and could not be overridden by other module or someone with access to the filesystem. The second option is the opposite, the file will be expanded in your war file and can be overridden by other module or someone with access to the filesystem.

Since only option one is compatible in all cases, I highly recommend to use that solution:

• Copy the content of AIO_REPO_ROOT/src/main/amps/web/* to AIO30_PLATFORM_ROOT/src/main/resources/META-INF/resources
• Copy the content of AIO_SHARE_ROOT/src/main/amps/web/* to AIO30_SHARE_ROOT/src/main/resources/META-INF/resources

Module.properties file

In SDK 2.2.0 the module.properties file is located in "amps" folder (PROJECT_ROOT/src/main/amps). In the SDK 3.0 these file goes into the module/<module_name> folder.

• Copy the file AIO_REPO_ROOT/src/main/amps/config/module.properties to AIO30_PLATFORM_ROOT/src/main/resources/alfresco/module/<module_name>

Fixing path

In spring context file some path might be depending on the artifactId. You need to fix those path before testing your migration.

There is 2 way to fix this:

• Change the artifactId to reflect your old artifactId
• Rename the folder with the new artifactId

Summary

In order to migrate our project from SDK 2.2.0 to SDK 3.0 we have to:

• Copy AIO_REPO_ROOT/src/main/java/* to AIO30_PLATFORM_ROOT/src/main/java
• Copy AIO_SHARE_ROOT/src/main/java/* to AIO30_SHARE_ROOT/src/main/java
• Copy the content of AIO_REPO_ROOT/src/main/amps/config/* to AIO30_PLATFORM_ROOT/src/main/resources
• Copy the content of AIO_SHARE_ROOT/src/main/amps/config/* to AIO30_SHARE_ROOT/src/main/resources
• Copy the content of AIO_REPO_ROOT/src/main/amps/web/* to AIO30_PLATFORM_ROOT/src/main/resources/META-INF/resources
• Copy the content of AIO_SHARE_ROOT/src/main/amps/web/* to AIO30_SHARE_ROOT/src/main/resources/META-INF/resources
• Fix path dependant from the artifactId