Packaging And Deploying Extensions
From AlfrescoWiki
Contents |
[edit] Introduction
There are several ways of deploying extensions, the method will depend on how complex your extension is and typically which appserver you are using. This article explains some of the lighter-weight methods for packaging extensions. However, for code that will be reusable or modular, consider using AMP Files. From version 2.0 onwards a Module Management Tool can be used to deploy your AMP File extension. Since July 2008 a Sourcesense contribution (http://repository.sourcesense.com/maven2-sites/maven-alfresco-extension-archetype) is available for building and packaging extensions with Apache Maven2.
[edit] Alfresco configuration files
If your customisation only consists of Alfresco configuration files or properties files i.e. web-client-config-custom.xml, Spring context files or webclient.properties, you can place them on the appserver's classpath.
For Tomcat, place your files in <tomcat-home>/shared/classes/alfresco/extension.
For JBoss, place your files in <jboss-home>/server/default/conf/alfresco/extension.
NOTE: You can only have one identically named file on the classpath as only the first one will be found. For example, if you have multiple JARs with a web-client-config-custom.xml file in the alfresco/extension package the ClassLoader will load the first one it finds, which in turn, will result in unpredictable behaviour. Furthermore, you can not guarantee which file will be found first.
From version 2.0 onwards the problem above has been resolved. You can now have multiple web-client-config-custom.xml files present in the system by placing them in the JAR file's META-INF folder. This change is part of the module management improvements made in 2.0
[edit] Java code
Java classes are typically packaged within a JAR file, which has to be put in the appserver's classpath. The most reliable location is the web application's WEB-INF/lib directory. The suggested way to do it is by adding your JAR file to the alfresco.war file, see the Integrated deployment section below.
In addition to your Java code, you'll most likely also have configuration files injecting the new code into Alfresco. These too can be contained within the JAR file, simply package them within the JAR file in the alfresco/extension package.
[edit] Tomcat
Once the server has been started, the application is exploded into <tomcat-home>/webapps/alfresco. Stop the server if it is running, copy the JAR file to <tomcat-home>/webapps/alfresco/WEB-INF/lib and re-start Tomcat.
Beware though, if at any time you re-deploy the Alfresco WAR file though your extension will be deleted and you will have to re-deploy it.
One solution is to use a permanently exploded deployment (instead of deploying an Alfresco WAR file under /webapps). Create a directory called alfresco under the webapps directory and extract the contents of alfresco.war into it. Then copy your JAR file to ...webapps/alfresco/WEB-INF/lib and restart Tomcat.
[edit] JBoss
In JBoss, if you deploy a web application as a WAR file the application gets exploded to a temporary directory each time the appserver starts. Thus there is nowhere to copy the JAR file to. One solution is to use an exploded deployment. Create a directory called alfresco.war under the deploy directory and extract the contents of alfresco.war (the file) into it. Then copy your JAR file to ...deploy/alfresco.war/WEB-INF/lib and restart JBoss.
[edit] JSF configuration files
Unfortunately, to override JSF configuration differs depending on what you want to override. For whatever reason, JSF has a first one wins policy for navigation rules and a last one wins policy for managed beans.
We therefore provide hooks for JSF configuration at the start and the end of JSF initialisation. To hook in at the beginning (i.e. to override a navigation rule,) create a faces-config.xml and package the file within a JAR within the META-INF folder. To hook in at the end, create a faces-config-custom.xml file and copy it to the WEB-INF folder of the Alfresco web application (this should replace our empty placeholder file).
As a guide the table below shows which file JSF config should go to:
| Override | File and Location |
|---|---|
| Overriding navigation rules | faces-config.xml in META-INF |
| Overriding managed beans | faces-config-custom.xml in WEB-INF |
| New navigation rules | Either |
| New managed beans | Either |
[edit] Single file deployment
A lot of extensions are also going to involve custom JSP files which can not be placed within a JAR file. Other web content i.e. images, JavaScript files etc. can be read from JAR using weblets but typically you'll want these on the filesystem too.
The simplest way to package your extension is to use a zip file. All the SDK samples that need to, e.g. Adding a Custom Dialog, use this technique. For deployment all you need to do is extract the contents of the zip file to the root of the deployed Alfresco application.
As an example, the custom dialog sample ends up with a zip file with the following structure:
> jsp
> extension
> add-aspect.jsp
> WEB-INF
> lib
> custom-dialog.jar
> alfresco
> extension
> web-client-config-custom.xml
> META-INF
> faces-config.xml
> MANIFEST.MF
> org
> alfresco
> sample
> AddAspectDialog.class
[edit] Integrated deployment
The final option you have for deploying your extension is to integrate it into the alfresco.war file. Each of the web client oriented SDK samples features an Ant target to integrate the sample into a pre-built Alfresco WAR file. To try it out copy an alfresco.war file to the root directory of the sample and run ant integrate-extension.
