Building the AMP

An AMP is ZIP compressed and has the following default structure:

  • /config

  • /lib

  • /licenses

  • /web

    • /jsp

    • /css

    • /images

    • /scripts

  • module.properties

  • file-mapping.properties

The config folder contains the Spring module-context.xml file and user interface configuration that typically reside in the standard package structure (org.alfresco.module.<moduleid>). It can also contain other resources, such as XML import files or Alfresco Content Package (ACP) files. The contents are mapped to the /WEB-INF/classes folder in the WAR file and are defined in the classpath.

The lib folder contains all of the module-specific JAR files, which are mapped to the /WEB-INF/lib folder in the WAR file.

The licenses folder contains license files for any third party JARs contained in the lib folder.

The web folder contains any custom or modified JSPs, CSS files, images, and JavaScript files. The contents are mapped to the equivalent folders in the WAR file, and all subfolder structures are preserved. If a file already exists in the WAR file, it is overwritten and a backup file is created.

The module.properties file is required and contains metadata about the module, including its identifier and version number.

The file-mapping.properties file is optional and can be provided to customize the way AMPs are mapped to the WAR file. (See Customizing the structure of an AMP.)

The module files are packaged into an AMP using Ant, as shown in the following example.

Packaging the module files into an AMP using ANT

The following build.xml file specifies the following behavior:

  • The Java source in the /source/java folder is compiled and stored in the /build/classes folder.

  • The package-jar target packages the compiled class files into the destination JAR file.

  • The package-amp target packages the JAR files and configuration files into the destination AMP.

  • The update-war target uses the Module Management Tool to install the AMP into an existing WAR file.

<?xml version="1.0"?> 
 
<project name="SDK Demo AMP Build File" default="package-amp" basedir="."> 
     
       <property name="project.dir" value="."/> 
       <property name="build.dir" value="${project.dir}/build"/> 
       <property name="config.dir" value="${project.dir}/config"/> 
       <property name="jar.file" value="${build.dir}/lib/alfresco-sdk-custom-service.jar"/> 
       <property name="amp.file" value="${build.dir}/dist/alfresco-sdk-custom-service.amp"/> 
     
       <target name="mkdirs"> 
           <mkdir dir="${build.dir}/dist" /> 
           <mkdir dir="${build.dir}/lib" /> 
       </target> 
     
       <path id="class.path"> 
           <dirset dir="${build.dir}" /> 
           <fileset dir="../../lib/server" includes="**/*.jar"/> 
       </path> 
 
       <target name="compile"> 
           <mkdir dir="${build.dir}/classes" /> 
           <javac classpathref="class.path" srcdir="${project.dir}/source/java" destdir="${build.dir}/classes" /> 
       </target> 
     
       <target name="package-jar" depends="compile"> 
           <jar destfile="${jar.file}" > 
               <fileset dir="${build.dir}/classes" excludes="**/custom*,**/*Test*" includes="**/*.class" /> 
           </jar> 
       </target> 
     
       <target name="package-amp" depends="mkdirs, package-jar" description="Package the Module" > 
           <zip destfile="${amp.file}" > 
               <fileset dir="${project.dir}/build" includes="lib/*.jar" /> 
               <fileset dir="${project.dir}" includes="config/**/*.*" excludes="**/module.properties" /> 
               <fileset dir="${project.dir}/config/alfresco/module/sdkDemoAmp" includes="module.properties" /> 
           </zip> 
       </target> 
 
       <target name="update-war" depends="package-amp" description="Update the WAR file.  Set -Dwar.file=..." > 
           <echo>Installing SDK Demo AMP into WAR</echo> 
           <java dir="." fork="true" classname="org.alfresco.repo.module.tool.ModuleManagementTool"> 
               <classpath refid="class.path" /> 
               <arg line="install ${amp.file} ${war.file} -force -verbose"/> 
           </java> 
       </target> 
 
</project>

Installing the AMP

AMPs are installed and managed using the Module Management Tool. (See Using the Module Management Tool.) An EAR is used for deployment. You must open the WAR inside adobe-contentservices.ear before packaging. After the AMP has been packaged, it can be added to the WAR file using Ant or directly from the command line using the Module Management Tool.

To install the AMP in an existing WAR file using Ant, you must use the following command:

  • ant -f build.xml -Dwar.file=/path/to/contentservices.war update-war

    To install the AMP from the command line using the Module Management Tool, use the following commands for a preview installation or verbose mode, respectively. In these examples, the AMP is named alfresco-sdk-custom-service.amp.

    Preview mode:

  • java - jar alfresco-mmt-2.1.jar install alfresco-sdk-custom-service.amp contentservices.war -preview

    Verbose mode:

  • java - jar alfresco-mmt-2.1.jar install alfresco-sdk-custom-service.amp contentservices.war -verbose

    When you restart the application server, the console shows that the custom class has been initialized during startup.

Using the Module Management Tool

The Module Management Tool can be used to install AMPs or list the modules installed within a WAR file.

To install AMPs, you must use the following command:

  • install <AMP location> <WAR file location> [options]

    The following options can be used when installing AMPs.

    Option

    Description

    -verbose

    Enables verbose output.

    -directory

    Indicates that the specified AMP location is a directory. All AMPs found in the directory and its subdirectories are installed.

    -force

    Forces the installation of the AMP regardless of the currently installed module version. This option is often useful when you are developing an AMP.

    -preview

    Previews the installation of the AMP without modifying the WAR file. This is considered good practice prior to actual installation, especially if existing files are being updated.

    -nobackup

    Indicates that a backup of the WAR file is not to be created. If this option is not specified, a copy of the original WAR file is placed in the same directory. It is recommended that you do not use this option if existing files in the AMP are being overwritten.

    The install command installs the files contained within the AMP into the WAR file, and updates the WAR file if an older version was previously installed (removing the older files from the WAR file). The installation is performed using a standard mapping unless a custom mapping is provided. You must be sure to provide the appropriate module components to bootstrap or patch any required data. If the version of the module being installed is less than or equal to the previously installed version, the installation aborts unless the -force option is specified.

    To list the details about the modules currently installed in a WAR file, you can use the following command:

  • list <WAR file>

    The output is directed to the console.

Customizing the structure of an AMP

To customize the structure of an AMP, you must provide a file named file-mapping.properties. This file describes how the structure of your AMP can be mapped to the WAR file when it is installed by the Module Management Tool. If this file is not provided, the default mapping is used.

The file mapping properties file has an identical structure to that of a standard Java property file. Each key is a folder in the AMP structure, and each value is the target location in the WAR file.

If the source directory does not exist in the AMP, the mapping is ignored. If the destination directory in the WAR file does not exist, a run-time exception is raised.

If a mapping has a folder as the source directory, the folder is recursively copied into the WAR file.

An include.default property can be specified to indicate whether the default mappings are to be augmented or modified. If include.default=true is used, all of the default mappings are used unless augmented or modified. If include.default=false is used, only the custom mappings specified in the file mapping properties file are used, as shown in the following example.

Customizing the structure of an AMP

In the file-mapping.properties file, only the specified custom mappings are used.

include.default=false 
/WEB-INF=/WEB-INF 
/web=/

Importing module data

Module data can be imported from an XML file or an ACP file during module initialization using the Importer Module Component. The XML file or ACP file must be defined on the module’s classpath, and a Spring bean must be defined in the module’s context file, which must be named module-context.xml. The XML or ACP files to be imported and the destination location in the Content Services (deprecated) repository where the data should be imported are supplied as a list to the bootstrapViews property.

// Ethnio survey code removed