Alfresco Maven SDK

Many times when we want to customize Alfresco, we tend to take the easy route and make changes to the core Alfresco .js and .xml files that are in the alfresco or share folders.  While this may be a quick fix and easy to work with, it is not advisable to do so and not recommended by Alfresco as well. The reasons are as follows.

  1. RollBack – Adding new functionality by editing the ‘system’ files does not lend the system to roll back in case of errors or failures.
  2. Maintenance – While adding functionality this way seems to be quick and easy, it could become a maintenance issue over time with new additions.
  3. Portability – It would be tedious and error prone to make the same set of changes in a multi node/clustered environment on all servers
For the reason mentions above, it is always recommended to use modules and amps for adding any customization or features to Alfresco.

Types

There are two main types of modules that are supported by Alfresco. They are amp and java modules
AMP – Alfresco Module Project – These are jar files that could be used to add customization’s for the Alfresco Repo and Share components. They support the following types, namely
     – All in one Amp containing both the repo and share amps,
     – Repo Amp &
     – Share Amp
Java Modules  – These are standard jar file modules that could be used to override and also add features to an Alfresco installation.
Lets look at creating an all in one amp module using Alfresco Maven SDK and also how to run it locally with an in memory h2 db on your local machine.

Requisites

   – Maven 3.0
   – Java JDK 8
   – Eclipse /IntelliJ
   – Alfresco 5.x community edition

Steps

Open a command window and cd to the folder where you would like to create the amp project
In the sample below i am creating my amp project under C:\Java\projects\alfmodule
Enter the following commands in a command window.
mvn archetype:generate -Dfilter=org.alfresco:
 
Lets step through the options and create an all in one amp using the command line.
C:\Java\projects\alfmodule>mvn archetype:generate -Dfilter=org.alfresco:
[INFO] Scanning for projects…
[INFO]
[INFO] ————————————————————————
[INFO] Building Maven Stub Project (No POM) 1
[INFO] ————————————————————————
[INFO]
[INFO] >>> maven-archetype-plugin:2.4:generate (default-cli) > generate-sources
@ standalone-pom >>>
[INFO]
[INFO] <<< maven-archetype-plugin:2.4:generate (default-cli) < generate-sources
@ standalone-pom <<<
[INFO]
[INFO] — maven-archetype-plugin:2.4:generate (default-cli) @ standalone-pom —
[INFO] Generating project in Interactive mode
[INFO] No archetype defined. Using maven-archetype-quickstart (org.apache.maven.
archetypes:maven-archetype-quickstart:1.0)
Choose archetype:
1: remote -> org.alfresco.maven.archetype:alfresco-allinone-archetype (Sample mu
lti-module project for All-in-One development on the Alfresco plaftorm. Includes
 modules for: Repository WAR overlay, Repository AMP, Share WAR overlay, Solr co
nfiguration, and embedded Tomcat runner)
2: remote -> org.alfresco.maven.archetype:alfresco-amp-archetype (Sample project
 with full support for lifecycle and rapid development of Repository AMPs (Alfre
sco Module Packages))
3: remote -> org.alfresco.maven.archetype:share-amp-archetype (Share project wit
h full support for lifecycle and rapid development of AMPs (Alfresco Module
        Packages))
Choose a number or apply filter (format: [groupId:]artifactId, case sensitive co
ntains): :
You would be prompted to enter a number for the archetype value.
1 – All in one amp  – contains both repo and share
2 – Repo amp
3 – Share amp
Enter 1

You would get the following screen.

Choose a number or apply filter (format: [groupId:]artifactId, case sensitive co
ntains): : 1
Choose org.alfresco.maven.archetype:alfresco-allinone-archetype version:
1: 2.0.0-beta-1
2: 2.0.0-beta-2
3: 2.0.0-beta-3
4: 2.0.0-beta-4
5: 2.0.0
6: 2.1.0
7: 2.1.1
Choose a number: 7:
 
 It is recommended to stick with the latest version available. Also the latest version 7, in this case, is already chosen for us. Press enter to go with the default or press the number for the version you would like to work with.
Maven downloads a bunch of artifacts as shown below
Downloading: https://repo.maven.apache.org/maven2/org/alfresco/maven/archetype/a
lfresco-allinone-archetype/2.1.1/alfresco-allinone-archetype-2.1.1.jar
Downloaded: https://repo.maven.apache.org/maven2/org/alfresco/maven/archetype/al
fresco-allinone-archetype/2.1.1/alfresco-allinone-archetype-2.1.1.jar (61 KB at
62.8 KB/sec)
Downloading: https://repo.maven.apache.org/maven2/org/alfresco/maven/archetype/a
lfresco-allinone-archetype/2.1.1/alfresco-allinone-archetype-2.1.1.pom
Downloaded: https://repo.maven.apache.org/maven2/org/alfresco/maven/archetype/al
fresco-allinone-archetype/2.1.1/alfresco-allinone-archetype-2.1.1.pom (3 KB at 4
4.2 KB/sec)
Define value for property ‘groupId’: :
Enter ‘com.atechref.alf’ for groupid and ‘allinone’ for artifactid. You would get the following screen
Define value for property ‘groupId’: : com.atechref.alf
Define value for property ‘artifactId’: : allinone
[INFO] Using property: version = 1.0-SNAPSHOT
Define value for property ‘package’:  com.atechref.alf: :
Confirm properties configuration:
groupId: com.atechref.alf
artifactId: allinone
version: 1.0-SNAPSHOT
package: com.atechref.alf
 Y: :
 
Press ‘y’ to create the project
 Y: : y
[INFO] ————————————————————————-
[INFO] Using following parameters for creating project from Archetype: alfresco-
allinone-archetype:2.1.1
[INFO] ————————————————————————-
[INFO] Parameter: groupId, Value: com.atechref.alf
[INFO] Parameter: artifactId, Value: allinone
[INFO] Parameter: version, Value: 1.0-SNAPSHOT
[INFO] Parameter: package, Value: com.atechref.alf
[INFO] Parameter: packageInPathFormat, Value: com/atechref/alf
[INFO] Parameter: package, Value: com.atechref.alf
[INFO] Parameter: version, Value: 1.0-SNAPSHOT
[INFO] Parameter: groupId, Value: com.atechref.alf
[INFO] Parameter: artifactId, Value: allinone
[INFO] Parent element not overwritten in C:\Java\projects\alfmodule\allinone\rep
o-amp\pom.xml
[INFO] Parent element not overwritten in C:\Java\projects\alfmodule\allinone\sha
re-amp\pom.xml
[INFO] Parent element not overwritten in C:\Java\projects\alfmodule\allinone\rep
o\pom.xml
[INFO] Parent element not overwritten in C:\Java\projects\alfmodule\allinone\sol
r-config\pom.xml
[INFO] Parent element not overwritten in C:\Java\projects\alfmodule\allinone\sha
re\pom.xml
[INFO] Parent element not overwritten in C:\Java\projects\alfmodule\allinone\run
ner\pom.xml
[INFO] project created from Archetype in dir: C:\Java\projects\alfmodule\allinon
e
[INFO] ————————————————————————
[INFO] BUILD SUCCESS
[INFO] ————————————————————————
[INFO] Total time: 18:39 min
[INFO] Finished at: 2016-03-02T22:35:45-05:00
[INFO] Final Memory: 14M/126M
[INFO] ————————————————————————
The project is now created and ready to import from your IDE. I am using IntelliJ IDEA and the below steps should be adapted to other IDEs appropriately
Open IntelliJ and Select ‘New -> Project from existing sources’

1

Select ‘allinone’ folder under ‘alfmodule’

2

Select ‘Create Project from existing sources’

Advertisements

3

Enter project name ‘allinone’

4

Select ‘Finish’

5

Select ‘New Window’

6

Now IntelliJ would work its magic and setup the project. It may take a while to get all the artifacts in place. Once done the project would be similar to the structure shown below.
7
Majority of the customizations are done to the repo-amp and share-amp modules. The rest of the modules are required for specific configurations.
Now that the project is loaded lets configure the maven build settings first, before updating the profiles.
In IntelliJ select ‘Run -> Edit Configurations’ from the menu bar.
8
Enter the name as ‘mvn install’ and set the properties as shown below.
9
The -Prun command tells maven to run the application on an embedded tomcat instance using an in memory h2 database. This way you can run both Alfresco Share and Repo off your local machine for development and debugging purposes.
Now save the settings and lets edit the Profiles. The required profiles for the Community edition are shown below. If you have an enterprise license and access to enterprise repository, only then should you select the ‘enterprise’ profile. Enabling the ‘enterprise’, ‘amp-to-war’ or other profiles would result in error messages while executing the ‘mvn install’ configuration that we setup earlier.
10
Cool. Now that we have set all the required configurations, lets run ‘mvn install’
Since we have defined an all in one amp, the above command would initialize the spring context for all modules, pull down other required dependency from alfresco’s community maven site, compile and validate all the modules, start the included tomcat instances, deploy the repo-amp and share-amp module loads the application. This would take a while depending on the system. As i mentioned earlier, the enterprise version jars are not available in the community maven site, and these dependencies would require a separate login credential provided by Alfresco only for enterprise customers.
The following is how it looks with my current setup in my IDE.
11
Once you see “Successfully retrieved license info from Alfresco.” it means the server has completed the deployment and we can load the share login page in a browser.
Open a browser window and enter ‘localhost:8080/share’ and you should get the following page.
12
Enter ‘admin’ admin’ as the user name and password. These are the default values for the local server instance. You should be able to log into share. You may notice that there is a new ‘Debug Menu’, as highlighted below.
13
This menu is visible by default when running in this mode from an IDE. This menu contains settings that would help with trouble shooting issues with the UI customization or changes. It is also a good place to play around and get a better understanding of how the various UI components work together.
14
Great. Now you have a complete alfresco instance running on your local development environment. You can also start this in the debug mode and step through breakpoints etc. This would be tremendously helpful when you begin working with web-scripts and java classes.
Using IntelliJ it is pretty straight forward to restart the server instance as shown below.
15
Go ahead and stop the server using the Stop button in the Run view in IntelliJ. Restart the server in Debug mode and step through the existing java classes.
16
Now that we have setup the environment we would look at creating some web-scripts in future posts.
Advertisements

Leave a Reply

Your email address will not be published. Required fields are marked *