Including Extra Files in ATG Standalone EARs

This blog post was originally posted in the ATG Developer Community by Adam Belmont in July, 2008.

ATG applications are executed on J2EE application servers as EAR files.

The ‘runAssembler’ tool is what one should use to create an EAR file. Command line scripts such as “startDynamoOnJBoss” are really just wrappers around the runAssembler command. Note, runAssembler can also be invoked via ant but I won’t get into that here.

For production deployments ATG ear files should be built using the -standalone flag to runAssembler.
This creates an ear file that can be installed without requiring an ATG installation. It really cuts down on server maintenance to have this single file rather than a whole ATG installation on each machine.

Reducing Ear File Size

To keep the size of this file somewhat in control, the runAssembler command only includes minimal items in an ear file.
The minimal items are:

• Entries in the module’s classpath (ATG-Class-Path directive)
• Entries in the module’s configpath (ATG-Config-Path directive)

Most application modules don’t need more than classpath entries and configpath entries, but at times there are other “extra” files and directories required by an application.
For example the DAS module, located at ${DYNAMO_ROOT}/DAS, has a “keystore” directory that is used for key generation. These files aren’t in the classpath or the configpath, but they are needed at runtime. The DAS manifest explicitly tells runAssembler to include this directory.

Take a look at the $DYNAMO_ROOT/DAS/META-INF/MANIFEST.MF for an example.

Including more files in your EAR

Here’s how you tell runAssembler to include an additional file or directory.
Edit your module’s META-INF/MANIFEST.MF. In that file append a blank line. On the next line add the module relative path of the file or directory to be included. Finally on the third line add the directive ATG-Assembler-Import-File:True.
If you have more than one file to include, repeat the steps above for each file.

The blank line preceding the Name: is significant!

Here’s an example snipped showing two files to be included: