Setting up the AMP project structure

Creating the module properties file
Creating the module context file

An AMP project can be structured in any way that suits the development environment. As long as the resulting AMP is packaged correctly and the required property and context files are present, the module installs successfully.

The recommended structure for an AMP project is as follows:

/source/java/<Java source files>
/source/web/<web UI sources such as JSPs, images, CSS, and JavaScript>
/config/<configuration files and resources used by the module>
/build/<compiled class files>
/build/dist/<AMPs>
/build/lib/<JAR files>

The recommended package structure for Java source files, configuration files, and resources is org.alfresco.module.<moduleid>, where moduleid is the unique module identifier defined in the module properties file. (See Creating the module properties file.)

Creating the module properties file

The module properties file (module.properties) is used by the module service to identify the module and its details when it is installed. During development, you must place the module properties file in the org.alfresco.module.<moduleid> package since this will be its final location when it is installed in the EAR file. You must extract the WAR from the EAR before packaging the content. This location permits unit tests within Eclipse and the embedded repository behaves as though the module is installed. When you finally build the AMP, you must place the module properties file at the root.

The module properties file is comprised of the following properties.

Property	Description
`module.id`	The unique identifier for the module. It must be globally unique to prevent collisions with other modules. For example, it can be named `org.alfresco.module.RecordsManagement`. You can rename a module using the alias mechanism. Module identifiers can contain a-z, A-Z, 0-9, spaces, minuses, and underscores.
`module.version`	The current module version, which helps identify whether the module is a new installation or an update to an existing installation of a previous version. The version number must be comprised of numeric values separated by dots. For example, `2.1.56` is a valid version, but `2.3.4a` is not valid.
`module.title`	The module title.
`module.description`	The module description.
`module.aliases`	(Optional) Additional names for the module. When a module is renamed, you must add the original name to the list of aliases to ensure that the module tool and repository correctly match the new name to one of the old names.
`module.depends`	(Optional) Versions on which the module depends. When one module is installed, it can be necessary to install additional modules and that a specific version, set of versions, or range of versions be present. The dependency is satisfied if the installed version of the dependency matches any of the specified ranges or versions. For example, `module.depends.X=` indicates that any version of X must be installed, `module.depends.Y=1.0, 1.5, 2.0` indicates that version 1.0, 1.5, or 2.0 of Y must be installed, and `module.depends.Z=-0.9.9` indicates that any version of Z less than 1.0 must be installed.

Creating a module properties file

The following module.properties file contains the module identifier, version, title, and description.

# SDK Sample module 
module.id=sdkDemoAmp 
module.title=SDK Demo AMP Project 
module.description=Skeleton demo project to build an amp file 
module.version=1.0

Creating the module context file

A module is initialized when the Content Services (deprecated) repository loads the root Spring configuration for that module. When the module service is initialized, all of the module context configurations are loaded.

The root Spring configuration contains new bean definitions, custom content models, client configurations, or data to be loaded or patched. In a large module, the configuration can be split into smaller Spring configurations that are included by the module context file.

The module context file must be placed in the org.alfresco.module.<moduleid> package and must be named module-context.xml, as shown in the following example.

Creating the module context file

This example refers to an imported file called service-context.xml.

<?xml version='1.0' encoding='UTF-8'?> 
<!DOCTYPE beans PUBLIC '-//SPRING//DTD BEAN//EN' 'http://www.springframework.org/dtd/spring-beans.dtd'> 
 
<beans> 
     
       <import resource="classpath:alfresco/module/sdkDemoAmp/context/service-context.xml" /> 
     
</beans>

Importing a Spring configuration

The following code represents the imported contents of the service-context.xml file. Note that it uses two classes called Demo and DemoComponent.

<?xml version='1.0' encoding='UTF-8'?> 
<!DOCTYPE beans PUBLIC '-//SPRING//DTD BEAN//EN' 'http://www.springframework.org/dtd/spring-beans.dtd'> 
 
<beans> 
     
       <!-- A simple class that is initialized by Spring --> 
       <bean id="sdk.demoAmp.exampleBean" class="org.alfresco.module.sdkdemoamp.Demo" init-method="init" /> 
     
       <!-- A simple module component that will be executed once --> 
       <bean id="sdk.demoAmp.exampleComponent" class="org.alfresco.module.sdkdemoamp.DemoComponent" parent="module.baseComponent" > 
           <property name="moduleId" value="sdkDemoAmp" />  <!-- See module.properties --> 
           <property name="name" value="exampleComponent" /> 
           <property name="description" value="A demonstration component" /> 
           <property name="sinceVersion" value="1.0" /> 
           <property name="appliesFromVersion" value="1.0" /> 
       </bean> 
     
</beans>

Beans used by a Spring configuration

The Demo class prints a message to the console when it is initialized, and the DemoComponent class is executed once during module initialization.

/* 
    * Copyright (C) 2005-2007 Alfresco Software Limited. 
    * 
    * This program is free software; you can redistribute it and/or 
    * modify it under the terms of the GNU General Public License 
    * as published by the Free Software Foundation; either version 2 
    * of the License, or (at your option) any later version. 
 
    * This program is distributed in the hope that it will be useful, 
    * but WITHOUT ANY WARRANTY; without even the implied warranty of 
    * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the 
    * GNU General Public License for more details. 
 
    * You should have received a copy of the GNU General Public License 
    * along with this program; if not, write to the Free Software 
    * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. 
 
    * As a special exception to the terms and conditions of version 2.0 of  
    * the GPL, you may redistribute this Program in connection with Free/Libre  
    * and Open Source Software ("FLOSS") applications as described in Alfresco's  
    * FLOSS exception.  You should have recieved a copy of the text describing  
    * the FLOSS exception, and it is also available here:  
    * http://www.alfresco.com/legal/licensing" 
    */ 
package org.alfresco.module.sdkdemoamp; 
 
/** 
    * This class does nothing except dump some output to <i>system.out</i>. 
    *  
    * @author Derek Hulley 
    */ 
public class Demo 
{ 
    public void init() 
    { 
        System.out.println("SDK Demo AMP class has been loaded"); 
    } 
} 
 
/* 
    * Copyright (C) 2005-2007 Alfresco Software Limited. 
    * 
    * This program is free software; you can redistribute it and/or 
    * modify it under the terms of the GNU General Public License 
    * as published by the Free Software Foundation; either version 2 
    * of the License, or (at your option) any later version. 
 
    * This program is distributed in the hope that it will be useful, 
    * but WITHOUT ANY WARRANTY; without even the implied warranty of 
    * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the 
    * GNU General Public License for more details. 
 
    * You should have received a copy of the GNU General Public License 
    * along with this program; if not, write to the Free Software 
    * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. 
 
    * As a special exception to the terms and conditions of version 2.0 of  
    * the GPL, you may redistribute this Program in connection with Free/Libre  
    * and Open Source Software ("FLOSS") applications as described in Alfresco's  
    * FLOSS exception.  You should have recieved a copy of the text describing  
    * the FLOSS exception, and it is also available here:  
    * http://www.alfresco.com/legal/licensing" 
    */ 
package org.alfresco.module.sdkdemoamp; 
 
import org.alfresco.repo.module.AbstractModuleComponent; 
 
/** 
    * A basic component that will be started for this module. 
    *  
    * @author Derek Hulley 
    */ 
public class DemoComponent extends AbstractModuleComponent 
{ 
       @Override 
       protected void executeInternal() throws Throwable 
       { 
           System.out.println("DemoComponent has been executed"); 
       } 
}