parent:AlfrescoDev

Integrating plutext-server into Alfresco

Approach

plutext-server is packaged as an AMP file.

Our build processes can create that AMP file for deployment into an existing Alfresco WAR file.

But for ease/speed of ongoing iterative development, its easier if the module can be added or updated in an existing exploded Alfresco webapp.

Here is how we have approached things:

* the AMP source code lives in plutext-server/src/alfresco

* as you would expect, you can edit the config files you find there, and rebuild etc

* however, the twist is that you copy the Java source code into alfresco/HEAD/root/projects/remote-api. It is this copy of the code which is used in the build. You can edit it in Eclipse. But if it is to be committed to plutext's SVN repository, the modified code will need to be copied back to plutext-server/src/alfresco. An ant task is provided for this purpose.

* you can build the AMP file, or bypass that step, and instead deploy the module into an existing exploded Alfresco WAR (we've be doing this on Tomcat).

Preliminaries

You should already have the plutext-server sources installed.

Apply the patch for alfresco bug AR-1989 - see the end of this file for further notes on this.

'Eclipse environment:' For Alfresco's Remote API project, add plutext-server and docx4j to Eclipse build path on the projects tab. This isn't essential, since we build from the command line, but it does keep Eclipse happy if you plan to use it to do further development.

Step 1 - build a plutext-server distribution

In the plutext-server project directory, run

ant dist

This copies plutext-server jar files to a known location (plutext-server/src/alfresco/lib)

You may need to edit a couple of paths in the build.xml file before this works.

Step 2 - copy some files into the alfreso source tree

There is an ant task to do this.

In plutext-server/

Open the plutext-server project's build.xml file in a text editor, and check the value of alfresco.root reflects your environment.

Then run ant:

ant enhance-alfresco-sources

This will copy plutext code into alfresco source tree.
I have kept step 1 and step 2 separate, since we might change something in plutext-server, and want to deploy it (but not want to run this step 2 again).

Step 3 - build your modified alfresco

Patch Alfresco/HEAD/root/build.xml and projects.xml using the 2 corresponding patches from plutext-server/src/alfresco/patches. You can do this in Eclipse, or, if you are using Linux, from a command line. I haven't automated it via ant, since patch on Windows is screwy :(

To modify web.xml, apply the patch alf-web-client-patches.txt.

After you have applied the patches, see below, depending on whether you want an AMP file and WAR, or an incremental tomcat deployment.

Note: in either case, building alfresco's remote-api will create a plutext-alfresco jar containing plutext/alfresco integration classes. This will be part of the AMP. In order to do this, the plutext-server libs are copied temporarily to alfresco's 3rd-party/lib.

Incremental Tomcat deployment

Build alfresco. From alfresco/HEAD/root, run:

ant plutext-incremental-tomcat-exploded

This simulates module deployment without creating a WAR, by copying the relevant module files to the places the WAR would eventually explode them to.

You can now start Tomcat. See further ConfigureTomcat?.

AMP file and WAR (ie for distribution)

Build alfresco. From alfresco/HEAD/root, run:

ant build

ant package-webclient-war

From plutext-server/src/alfreso, run:

ant package-amp

Then run the ModuleManagementTool. From alfresco/HEAD/root/projects/web-client/build/assemble/WEB-INF/lib:

/java/bin/java -cp activation.jar:* org.alfresco.repo.module.tool.ModuleManagementTool install /home/jharrop/workspace200711/plutext-server/src/alfresco/dist/plutext-server.amp ../../../dist/alfresco.war -verbose -preview

Remove the '-preview' if you are happy with what it will do. Note that it overwrites web.xml and server-config.wsdd.

(Or you could try the deploy-amp task in Alfresco's build.xml) Then deploy the modified WAR.

patch for alfresco bug AR-1989

This directory (which you will have checked out) contains a file alf-repository-patches.txt which needs to be used to patch the Alfresco repository project.

You can use Eclipse to apply the project patches (this is certainly the easiest way if you are using Windows). Right click on the relevant project: Team > Apply Patch > (then navigate to the relevant patch file in Workspace > plutext-server). Then work your way through the wizard.

Or, from a shell:

cd to the 'workspace' directory (parent of 'Alfresco' and plutext-server)

patch -p4 < plutext-server/src/alfresco/patches/alf-repository-patches.txt