AlfrescoSDK Creating a Repository extension project (AMP)

To get started we need developing a custom alfresco war we need to download the latest AlfrescoSDK from the community site:

https://github.com/Alfresco/alfresco-sdk

We require Alfresco Repository AMP for building our webscripts, workflow and custom UI. But before make sure you’ve met the pre-requisites as follows.

You’ll need to download and install the following tools and libraries, if you don’t already have them:

  1. The Java Software Development Kit (JDK) version 8. Use the JDK 8 from the Oracle JDK site and set the JAVA_HOME environment variable. See my Java pages on installing this.
  2. Apache Maven 3.2.5. Download Maven from the Apache Maven project web site and set the environment variables in Windows Advanced settings. See my Maven pages on installing this.
    set M2_HOME=C:\Tools\apache-maven-3.3.1
    set MAVEN_OPTS=-Xms256m -Xmx1G -javaagent:C:\Tools\spring-loaded\springloaded-1.2.3.RELEASE.jar -noverify
  3. Spring Loaded
    Spring Loaded is a Java agent (represented by a JAR file) that enables class reloading in a running JVM. It will enable you to update a Java file in your Alfresco extension project and then see the effect of the change directly in a running Alfresco-Tomcat-JVM instance without having to re-build JARs, AMPs, and WARs and re-deploying them, saving you loads of time.
    1. Download the Spring Loaded JAR from here.
    2. Copy JAR to some directory.

Check your configuration by running the command mvn –version. This will display information similar to the following:

Apache Maven 3.2.5 (12a6b3acb947671f09b81f49094c53f426d8cea1; 2014-12-14T17:29:23+00:00) Maven home: /usr/local/apache-maven-3.2.5 Java version: 1.8.0_45, vendor: Oracle Corporation Java home: /usr/lib/jvm/java-8-oracle/jre Default locale: en_GB, platform encoding: UTF-8 OS name: “linux”, version: “3.13.0-51-generic”, arch: “amd64”, family: “unix”

Archtypes

The following project types, and archetypes, are available:

  • Alfresco Repository AMP: this archetype is used to create extensions for the Alfresco Repository Web Application (alfresco.war) in the form of Alfresco Module Packages (AMP).
  • Alfresco Share AMP: this archetype is used to create extensions for the Alfresco Share Web Application (share.war) in the form of AMPs.
  • Alfresco all-in-one (AIO): this archetype is a multi-module project that leverages the Alfresco SDK’s powerful capabilities to customize and run the full Alfresco platform embedded with all its components. The archetype does not require additional downloads and provides a perfect starting point for full-blown Alfresco projects.

The Alfresco Repository AMP maven archetype can be used to create a new Alfresco Module extension project for thealfresco.war. For more information about this project type see Repository AMP Archetype

This task assumes that you have completed all instructions in Installing and configuring software.
This task shows how you can use the Repo AMP archetype of the Alfresco SDK to generate a repository extension module containing a simple example web script.
  1. Create a suitable directory in which to store all your Maven projects (if you have not already done so), such as alfresco-extensions.
  2. Change into your alfresco-extensions directory.
  3. Run the following command:
    mvn archetype:generate -Dfilter=org.alfresco:
    Important:As the archetypes are available via Maven Central you do not need to specify a catalog.

    You will be prompted to choose an archetype:

                        
    Choose archetype:
    1: remote -> 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)
    2: remote -> org.alfresco.maven.archetype:alfresco-amp-archetype (Sample project with full support for lifecycle and rapid development of Repository AMPs (Alfresco Module Packages))
    3: remote -> org.alfresco.maven.archetype:share-amp-archetype (Share project with full support for lifecycle and rapid development of AMPs (Alfresco Module Packages))
    Choose a number or apply filter (format: [groupId:]artifactId, case sensitive contains): : 
    
  4. Enter 2 to have Maven generate an Alfresco Repository Module Package (AMP) project.
  5. You will be prompted to choose an archetype version:
    Choose org.alfresco.maven.archetype:alfresco-amp-archetype version: 
    1: 2.0.0-beta-2
    2: 2.0.0-beta-3
    3: 2.0.0-beta-4
    4: 2.0.0
    5: 2.1.0
    6: 2.1.1
    Choose a number: 6: 
    

    Press Enter to select the default (the most recent version).

  6. You will then be prompted to enter a value for the property groupId:
    Define value for property 'groupId': : com.empeccable

    Here we have specified com.empeccable representing the domain for your company empeccable.com. Specify a groupId matching your company domain.

  7. You will then be prompted to enter a value for the property artifactId:
    Define value for property 'artifactId': : hubhq-repo

    Here we have specified hubhq-repo representing a HUBHQ component with a specific extension for the Alfresco Repository. Try and name the Repository extensions in a way so it is easy to see what kind of extension it is for the alfresco.war application. Here are some example names for repo extensions so you get the idea: zip-and-download-action-repo, digital-signature-repo, business-reporting-repo, these repository extensions would typically have corresponding Share extensions if they also include user interface functionality. It is good practice to use the following naming convention for repository extensions: {name}-repo, where -repo indicates that this is an Alfresco Repository extension. Note, hyphens are typically used in artifact IDs.

  8. You will then be prompted to enter a value for the property package:
    Define value for property 'package':  com.empeccable: : com.empeccable.hubhq

    Here we have specified com.empeccable.hubhq representing an HUBHQ component Java package. This package will be used for any example Java code generated by the archetype. It is good practice to keep all Java code you write under this package so it does not clash with other components/extensions. Any Spring beans generated by this archetype will use this package in the ID.

    Important:Java packages cannot have hyphens in them.
  9. You will then be prompted to enter Y to accept the values you have entered, or n to reject and change. Press Enter to accept the values.

    A new project directory containing a number of sub-directories and support files for the AMP will be created in the directory hubhq-repo.

  10. Change into the freshly created hubhq-repo directory and browse the various files and directories to see what has been created.

    The following directory structure has been created for you:

    hubhq-repo/
    ├── pom.xml (Maven project file)
    ├── run.sh  (Mac/Linux script to have this AMP applied to the Alfresco WAR and run in Tomcat)
    ├── run.bat (Windows script to have this AMP applied to the Alfresco WAR and run in Tomcat)
    ├── src
    │   ├── main
    │   │   ├── amp (For more information about the AMP structure see: http://docs.alfresco.com/community/concepts/dev-extensions-modules-intro.html)
    │   │   │   ├── config
    │   │   │   │   └── alfresco
    │   │   │   │       ├── extension
    │   │   │   │       │   └── templates
    │   │   │   │       │       └── webscripts (Your Web Scripts should go under this directory)
    │   │   │   │       │           ├── webscript.get.desc.xml   (Sample Web Script that you can try out)
    │   │   │   │       │           ├── webscript.get.html.ftl
    │   │   │   │       │           └── webscript.get.js
    │   │   │   │       └── module
    │   │   │   │           └── componentX-repo (AMP Module ID)
    │   │   │   │               ├── alfresco-global.properties (Put default values for properties specific to this extension here) 
    │   │   │   │               ├── context
    │   │   │   │               │   ├── bootstrap-context.xml (Bootstrapping of content models, content, i18n files etc)
    │   │   │   │               │   └── service-context.xml (Your service beans go here)
    │   │   │   │               ├── log4j.properties
    │   │   │   │               ├── model
    │   │   │   │               │   ├── content-model.xml (Content model for your files)
    │   │   │   │               │   └── workflow-model.xml (Content model for workflow implementations)
    │   │   │   │               └── module-context.xml (Spring context file that is picked up by Alfresco)
    │   │   │   ├── module.properties (AMP module ID, Version etc)
    │   │   │   └── web (If your AMP has some UI the files would go here, unlikely now when the Alfresco Explorer UI is gone)
    │   │   │       ├── css
    │   │   │       │   └── demoamp.css
    │   │   │       ├── jsp
    │   │   │       │   └── demoamp.jsp
    │   │   │       ├── licenses
    │   │   │       │   └── README-licenses.txt
    │   │   │       └── scripts
    │   │   │           └── demoamp.js
    │   │   └── java (Your Java classes go here, this is where most of the module extension implementation code would go, you can remove the demo component)
    │   │       └── com
    │   │           └── acme
    │   │               └── componentX
    │   │                   └── demoamp  (Demo module component, can be removed)
    │   │                       ├── DemoComponent.java
    │   │                       └── Demo.java
    │   └── test
    │       ├── java
    │       │   └── com
    │       │       └── acme
    │       │           └── componentX
    │       │               └── demoamp
    │       │                   └── test  (Example test of the demo component, can be removed)
    │       │                       └── DemoComponentTest.java 
    │       ├── properties
    │       │   └── local
    │       │       └── alfresco-global.properties (environment specific configuration, the local env is active by default)
    │       └── resources
    │           ├── alfresco
    │           │   └── extension
    │           │       └── disable-webscript-caching-context.xml (file to disable server side JavaScript compilation to Java code)
    │           └── log4j.properties 
    └── tomcat
        └── context.xml  (Virtual Webapp context for RAD development)
    
  11. At this point, before you have made any changes, you can build the project by typing:
    mvn install
    Attention: Maven will ensure that all requirements are downloaded. This make take some time.

    The project will return with the message BUILD SUCCESS. You should see the AMP artifact installed in your local repository.m2/repository/com/empeccable/hubhq-repo/1.0-SNAPSHOT/hubhq-repo-1.0-SNAPSHOT.amp

  12. Run and Test the sample Web Script

    To test the Web Script you will need to start an embedded Tomcat and deploy the Alfresco WAR with the component hubhq-repo AMP applied. This can be done in two ways:

    1. With mvn clean install -Pamp-to-war
    2. Via the run.sh script (or run.bat on Windows), which does the same thing, plus making sure Spring Loaded library is available.
    Important:This will only run the customized Alfresco Repository application (alfresco.war), Alfresco Share UI (share.war) and Search (solr4.war) is not available. If you need those too then use the All-in-One project instead.

    Let’s start Tomcat via the script as follows (use run.bat on Windows):

    ./run.sh
    ...
    INFO: WSSERVLET12: JAX-WS context listener initializing
    Apr 30, 2015 10:04:39 AM com.sun.xml.ws.transport.http.servlet.WSServletDelegate <init>
    INFO: WSSERVLET14: JAX-WS servlet initializing
    2015-04-30 10:04:39,152  WARN  [shared_impl.util.LocaleUtils] [localhost-startStop-1] Locale name in faces-config.xml null or empty, setting locale to default locale : en_GB
     Apr 30, 2015 10:04:39 AM org.apache.coyote.AbstractProtocol start
    INFO: Starting ProtocolHandler ["http-bio-8080"]
    2015-04-30 10:05:24,545  INFO  [management.subsystems.ChildApplicationContextFactory] [SearchScheduler_Worker-1] Starting 'Transformers' subsystem, ID: [Transformers, default]
     2015-04-30 10:05:24,741  INFO  [management.subsystems.ChildApplicationContextFactory] [SearchScheduler_Worker-1] Startup of 'Transformers' subsystem, ID: [Transformers, default] complete
    
    Important:You may first need to make the shell script executable using the command chmod +x run.sh.
  13. Once the web application has started (it may take a little while), point your browser athttp://localhost:8080/alfresco/service/sample/helloworld to test the web script. The web script should return the following text: Message: Hello World!
  14. If you are prompted to login, then use username admin and a password admin.
  15. Configure Enterprise Edition (Optional)

    So far we have used the project with its default configuration, which is using Alfresco Community edition 5.0.d. If you are going to work with the Enterprise edition then you need to do the following:

    1. Decide what Enterprise version you will be using, if you are going to use version 5.0.1 then you are set as that is the default Enterprise version. If you want to use another version then open up the componentX-repo/pom.xml file and uncomment the <alfresco.version>5.0.d</alfresco.version> property and set the new version number you want to use.
    2. Update the run.sh and run.bat scripts to use the Enterprise edition, this is done by using the enterprise profile in the maven command line: mvn clean install -Pamp-to-war,enterprise. Note. this automatically sets the version to 5.0.1 if you have not explicitly set it.
    3. And as you might have guessed, if you are not using the run script, you will have to remember to always activate the Enterprise profile when running: mvn clean install -Pamp-to-war,enterprise
    4. Install an enterprise license, otherwise the server will be in read-only mode, it goes into the following directory:
      hubhq-repo/
      ├── src
      │   ├── main
      │   │   ├── amp 
      │   │   │   ├── config
      │   │   │   │   └── alfresco
      │   │   │   │       ├── extension
      │   │   │   │       │   └── license
      │   │   │   │       │       └── acme-5.0.1-enterprise.lic
      
In this tutorial you have learned how to generate, deploy, and run a project using the Repository AMP archetype.
Other common usage supported by this archetype includes the following:
Command Description
mvn package Runs unit tests and packages AMP in ${project.build.directory}/${project.build.finalName}.amp
mvn install Like mvn package but also installs AMP in local Maven repository to be depended upon
mvn test Runs unit tests
mvn install -DskipTests=true Like mvn install but skips unit tests
mvn package -Pamp-to-war Like mvn package but also installs the AMP into an Alfresco WAR.
mvn integration-test -Pamp-to-war Like mvn package -Pamp-to-war but also runs the resulting WAR+AMP in Tomcat + H2 embedded for integration testing
mvn integration-test -Pamp-to-war -Dalfresco.client.war=share Like mvn integration-test -Pamp-to-war but installs the AMP and runs on the Share WAR in embedded Tomcat.
mvn clean -Ppurge Removes DB, alf_data, indexes and log files. Useful to purge the development repo (by default self contained in ${project.basedir}/alf_data_dev.

Note:This is an important command to use if you change significant settings in your project – for example you change the Alfresco edition from Community to Enterprise. It is important to purge databases and other data that might otherwise be persisted.
mvn install -Pamp-to-war,rad Similar to mvn install -Pamp-to-war but also adds support for remote JUnit running and for hot reloading with JRebel (requires appropriate MAVEN_OPTS configuration).
Read more…

admin has written 55 articles