This post aims at explaining how to set up Eclipse to build a new Alfresco module easily. Before continuing to read, be sure to have downloaded Alfresco and its Software Development Kit (SDK). Of course the following will assume that you have an installed Eclipse with the J2EE plugins. This article will not explain all the technical details on AMP files, for more informations on this topic, please refer to the corresponding Alfresco Wiki page.

This post will be composed of the following parts:

1. Creating the project
2. Useful settings for Alfresco development

Creating the project

First we need to create a common Java project in Eclipse. What will be interesting here is only how to structure the project and build it easily. The only tricky thing during the project creation is to remove the default source folder and replace it by two source/java and config folders. Don't forget to add the Alfresco embedded SDK project as a dependency of the new project.

In the newly created project, create the following folders:

• source/web/jsp: this folder is mapped to the jsp folder in the Alfresco WAR
• source/web/scripts: this folder is mapped to the scripts folder in the Alfresco WAR
• source/web/images: this folder is mapped to the images folder in the Alfresco WAR
• source/web/css: this folder is mapped to the css folder in the Alfresco WAR
• lib: this folder will contain all the third party dependencies to include in the AMP file
• WEB-INF: this folder will be mapped to the WEB-INF folder of the Alfresco WAR.

Now that the useful folders are created, we need to create the mandatory files of an Alfresco module package. Before continuing, please choose an identifier for the module: this will be needed in the next steps. For this tutorial I will named the module sample. The AMP file will need to have a descriptor file. This one will be a module.properties file created at the project's root. This file will need to contain the following properties:

• module.id: the chosen identifier for the module. In my case: sample
• module.version: the module version. Let's put 1.0 for a first version, but don't forget to change it afterwards
• module.title: a displayable title for the module
• module.description: a longer description for the module
• module.repo.version.min: the minimum required version of Alfresco
• module.repo.version.max: the maximum possible version of Alfresco

The module is almost ready, but there is still to add the module-context.xml file. This one will have to be placed in a alfresco.module.<your_id> package. In the example case, the file will need to be created in a alfresco.module.sample package in the config folder. This file only needs to contain the following content:

<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE beans PUBLIC '-//SPRING//DTD BEAN//EN' 'http://www.springframework.org/dtd/spring-beans.dtd'>
<beans>
</beans>

All the spring configuration can go in the beans tag of this file. However you can also place it in files ending with -context.xml in a alfresco.extension package in the source/java folder. All the Java classes to package in a JAR and deploy with the AMP have to be placed somewhere inside the source/java folder.

To make Alfresco use the WEB-INF folder in the AMP file, you need to add a new file-mapping.properties file at the project's root containing the following line. Do not use the WEB-INF folder unless you really know what you are doing!

/WEB-INF = /WEB-INF

Now that all the important parts of the project are created we need to write an ANT build file to transform this into a valid AMP file. The ANT build file will need to know the path where to find the Alfresco SDK: this will need to be configured in a build.properties file. I won't explain the details of the ANT build file as this is not an ANT tutorial. However you will see that it is composed of the following targets:

• clean: cleans the build results
• compile: compile the Java code in the source/java folder and copy the resources in the build output tree
• package-jar: package the results of the compile target into a JAR file
• package-amp: package the JAR file, libraries, WEB-INF, config folders and configuration files into an AMP file

The ANT build file is a build.xml file at the project's root. This file will contain the code shown by the following snippet. Of course it can be changed to fit your needs, but don't forget to update the project's structure if necessary.

<?xml version="1.0"?>

<project name="Sample Module" default="package-amp" basedir=".">

    <property name="project.dir" value="."/>
    <property file="${project.dir}/build.properties"/>
    <property file="${project.dir}/module.properties"/>

    <property name="build.dir" value="${project.dir}/build"/>
    <property name="config.dir" value="${project.dir}/config"/>
    <property name="jar.file" value="${build.dir}/lib/${module.id}.jar"/>
    <property name="amp.file" value="${build.dir}/dist/${module.id}.amp"/>

    <target name="mkdirs">
        <mkdir dir="${build.dir}/dist" />
        <mkdir dir="${build.dir}/lib" />
        <mkdir dir="${build.dir}/classes" />
    </target>

    <path id="class.path">
        <dirset dir="${build.dir}" />
        <fileset dir="${project.dir}/lib" includes="**/*.jar" />
        <fileset dir="${alfresco.sdk.dir}/lib/server" includes="**/*.jar" />
    </path>

    <target name="clean">
        <delete dir="${build.dir}" />
    </target>

    <target name="compile" depends="mkdirs">      
        <javac classpathref="class.path" debug="${debug}" srcdir="${project.dir}/source/java" 
            destdir="${build.dir}/classes" target="1.5" encoding="UTF-8"/>
        <copy todir="${build.dir}/classes">
            <fileset dir="${project.dir}/source/java" defaultexcludes="false">
                <exclude name="**/*.java"/>
                <exclude name="**/.svn/**"/>
                <exclude name="**/CVS/**"/>
            </fileset>
        </copy>
    </target>

    <target name="package-jar" depends="compile">
        <jar destfile="${jar.file}" encoding="UTF-8">
            <fileset dir="${build.dir}/classes" excludes="**/custom*,**/*Test*" defaultexcludes="false" />
        </jar>
    </target>

    <target name="package-amp" depends="package-jar" description="Package the Module" >
        <zip destfile="${amp.file}" encoding="UTF-8">
            <fileset dir="${project.dir}/build" includes="lib/*.jar" />
            <fileset dir="${project.dir}" includes="config/**/*.*" excludes="**/module.properties" />
            <fileset dir="${project.dir}">
                <include name="module.properties"/>
                <include name="file-mapping.properties" />
                <include name="WEB-INF/**/*" />
                <include name="lib/**/*" />
                <exclude name="WEB-INF/alfresco.tld"/>
                <exclude name="WEB-INF/repo.tld"/>
            </fileset>
            <zipfileset dir="source/web" prefix="web"/>
        </zip>
    </target>
</project>

The ANT build file will try to find some configuration in a build.properties file. This file will have to be created under the project's root and have to contain the following properties:

• alfresco.sdk.dir: the absolute path to the Alfresco SDK to build the module for.
• debug: true if the module should be build with the debugging symbols. This property is not mandatory.

Useful settings for Alfresco development

Now that the module is ready for development, here are some Eclipse tricks to ease the Alfresco developement.

• Copy the tomcat/webapps/alfresco/WEB-INF/classes/alfresco/model/modelSchema.xsd into the SDK folder and add it to the Eclipse XML Catalog in Window > Preferences. This schema doesn't cover the constraints in Alfresco model definitions, but it saves a lot of time fixing dummy syntax errors or typos.
• You can do the same with the tomcat/webapps/alfresco/WEB-INF/classes/alfresco/auditSchema.xsd file.
• Copy the alfresco.tld and repo.tld files into the WEB-INF folder of your project. This will provide auto-completion for the Alfresco tags when writing your JSP pages.
• Install the Eclipse plugin for FreeMarker support: it helps a lot to write template and webscripts.

With the created module project and some Eclipse configuration, you are now ready for Alfresco extensions development. You can still improve the ANT build file by adding some target to auto-deploy your changes... Don't forget to have a look at the post explaining how to debug an Alfresco extension: this can save a lot of time too during your module development.