[tutoriel] utilisation d’un script Ant pour packager une extension

illustration apache ant

Alfresco est une application modulaire, ce qui signifie qu’on peut lui ajouter des extensions sans avoir besoin de recompiler tout le code source. Lorsque vous développez une extension avec Eclipse, vous pouvez utiliser des scripts Ant pour ajouter vos modifications dans Alfresco.

Plusieurs solutions sont envisageables :

  • Intégrer vos modifications dans une archive war alfresco et déployer cette archive dans tomcat.
  • Packager vos fichiers puis les déployer directement sur un war alfresco éclaté.
  • Générer un package AMP qui sera installé au prochain lancement d’Alfresco

Lorsqu’il s’agit de déployer des modifications pour faire des tests rapides, il est sans doute préférable d’utiliser la seconde méthode. Les packages amp et l’intégration dans une archive war sont plutôt utilisés lorsque l’extension est terminée. Ils évitent d’avoir à déployer une archive de l’extension après l’installation d’Alfresco. C’est un gain de temps et de simplicité d’utilisation.

Nous allons donc étudier un script ant standard utilisé pour déployer une extension sur un war alfresco explosé. Son but va être de compiler les classes java s’il y en a, de générer les archives jar puis de les copier, ainsi que tous les fichiers de configuration et les fichiers jsp/css/images nécessaires dans le répertoire de l’application web Alfresco, à savoir par défaut C:\Alfresco\tomcat\webapps\alfresco.

Tout d’abord, regardons à quoi peut ressembler l’arborescence d’un projet d’extension pour Alfresco:

projet d'extension pour Alfresco

  • source : Il contient vos classes java. vous en aurez besoin si vous voulez ajouter de nouvelles actions (copier/coller un document, le taguer, ajouter des commentaires, modifier ses paramètres, etc.)
  • build : Ce dossier accueille le jar contenant vos classes et l’archive zip de tout votre projet.
  • config : Ici se trouvent tous vos fichiers de configuration custom (web client, modèle, propriétés, etc.)
  • web : les fichiers de personnalisation du client web.

Pour utiliser un script Ant, ajoutez un fichier xml ant à votre projet et appelez le build.xml. Ajoutez également un fichier build.properties. Ce fichier va contenir quelques chemins absolus utilisés dans le build.xml. Copiez le code suivant à l’intérieur :

alfresco.sdk.dir=C:/alfresco-env/sdk/lib
alfresco.web.dir=C:/Alfresco/tomcat/webapps/metalawyerweb
alfresco.shared.extension.dir=C:/Alfresco/tomcat/shared/classes/alfresco/extension

Bien sûr, pensez à modifier les chemins par rapport à votre environnement. Le dossier shared est inclus dans le classpath d’Alfresco et vous permet de séparer vos fichiers de configuration personnalisés du reste des fichiers d’Alfresco. Ils sont ainsi plus faciles à retrouver. Vous pouvez aussi les placer dans le dossier de l’application web,  /Alfresco/WEB-INF/classes/alfresco/extensions.

Regardons maintenant le contenu du fichier build.xml. On commence par déclarer le projet, les différentes variables du script (les dossiers et sous-dossiers du projet) et quelques target simples :

<?xml version="1.0" encoding="UTF-8"?>
<project name="My Custom Alfresco Extension project" default="setup" basedir=".">
	<property file="build.properties" />

	<property name="project.dir" value="." />
	<property name="build.dir" value="${project.dir}/build" />
	<property name="bin.dir" value="${project.dir}/bin" />
	<property name="project.name" value="my-custom-alfresco-extension" />
	<property name="package.file.zip" value="${build.dir}/${project.name}.zip" />
	<property name="package.file.jar" value="${build.dir}/${project.name}.jar" />
	<property name="project.file.zip" value="${build.dir}/${project.name}-project.zip" />
	<property name="source.dir" value="${project.dir}/source" />
	<property name="config.dir" value="${project.dir}/config" />
	<property name="web.dir" value="${source.dir}/web" />
	<property name="extension.dir" value="/alfresco/extension" />

	<path id="classpath.server">
		<fileset dir="${alfresco.sdk.dir}/server" includes="**/*.jar" />
	</path>

	<path id="classpath.remote">
		<fileset dir="${alfresco.sdk.dir}/remote" includes="**/*.jar" />
	</path>

	<path id="classpath.local">
		<fileset dir="${project.dir}/lib" includes="**/*.jar" />
	</path>

	<path id="classpath.build">
	    <fileset dir="${build.dir}" includes="**/*.jar" />
    </path>

	<target name="clean" description="Removes all generated files">
		<delete dir="${build.dir}" />
		<delete dir="${bin.dir}" />
	</target>

	<target name="setup" description="Creates the ${build.dir} and ${bin.dir} directories">
		<mkdir dir="${build.dir}" />
		<mkdir dir="${bin.dir}" />
	</target>
</project>

La target setup va créer les deux dossiers build et bin dans votre workspace. On va ensuite compiler les classes java et les déplacer dans le dossier bin avec le code suivant :

<target name="compile" description="Compiles src to ${bin.dir}">
	<mkdir dir="${bin.dir}" />
	<javac srcdir="${project.dir}/source" destdir="${bin.dir}" source="1.6" target="1.6" debug="on" fork="yes" deprecation="on">
		<classpath refid="classpath.server"/>
		<classpath refid="classpath.remote"/>
		<classpath refid="classpath.local"/>
	</javac>
	<!-- copy in non-compiled files like props if needed -->
	<copy todir="${bin.dir}">
		<fileset dir="${project.dir}/source" excludes="**/*.java"/>
	</copy>
</target>

Une fois celà fait, On va générer l’archive .jar contenant ces classes :

<target name="package-jar" depends="setup, compile"
	description="Jars up the compiled classes and ${web.dir}/META-INF into ${package.file.jar}">
		<delete file="${package.file.jar}" />
		<jar destfile="${package.file.jar}">
			<fileset dir="${bin.dir}" includes="com/**" />
			<fileset dir="${bin.dir}" includes="org/**" />
			<zipfileset dir="${web.dir}/META-INF" excludes="*.zip" prefix="META-INF" />
		</jar>
</target>

Les lignes includes permettent de choisir les packages de votre code source qui vont être ajoutés au jar. Remarquez que l’argument depends fait appel aux target setup et compile, ce qui signifie que si vous exécutez la target package-jar, ces deux tâches seront exécutée en premier et dans l’ordre dans lequel elles sont indiquées !

On poursuit avec la tâche package-extension, qui va créer une archive zip de l’extension avec tout son contenu, pré-formatée pour être décompressée par dessus le dossier de l’application web alfresco :

<target name="package-extension" depends="setup, package-jar"
	description="Creates a zip called ${package.file.zip} which can be unzipped on top of an exploded Alfresco web app">
	<delete file="${package.file.zip}" />
	<zip destfile="${package.file.zip}" update="true">
		<zipfileset dir="${config.dir}${extension.dir}" prefix="WEB-INF/classes${extension.dir}" />
		<zipfileset file="${package.file.jar}" prefix="WEB-INF/lib" />
		<zipfileset dir="${web.dir}" excludes="META-INF/**" />
	</zip>
</target>

Enfin, on termine avec la tâche deploy, qui va s’occuper de décompresser pour vous l’archive de votre extension sur votre installation alfresco :

<target name="deploy" depends="package-extension" description="Unzips the ${package.file.zip} into ${alfresco.web.dir}">
	<unzip src="${package.file.zip}" dest="${alfresco.web.dir}" />
</target>

Votre script ant est maintenant complet et prêt à être exécuté. Faites un clic droit sur votre fichier build.xml et cliquez sur Run As… Vous pouvez choisir les tâches à exécuter dans l’ordre, mais pensez aussi que la tâche deploy appelle toutes les sous-tâches nécessaires à sa réalisation. Il vous suffit de cocher cette tâche pour que tout soit fait dans l’ordre et que votre extension soit déployée !

Pensez à consulter les fichiers build.xml des différents projets du SDK pour découvrir d’autres options et comprendre leur fonctionnement.

Laisser un commentaire

Votre adresse e-mail ne sera pas publiée. Les champs obligatoires sont indiqués avec *