This article will provide an overview of using Maven to build code and create modules for Oracle ATG Commerce.
A sample that builds the Commerce Reference Store for Oracle ATG Commerce 11.2 is available at https://github.com/oracle/atg-build-tools/tree/master/atg-crs-11.2-maven
In order to effectively use Maven with Oracle ATG Commerce, or any other build tool, it is important to understand how ATG modules are structured and used by the product.
Assume we have a module named ATeamSample. The following is an example directory structure, starting at the root of the ATG installation ($ATG_ROOT)
The MANIFEST.MF file contains entries that are read by the ATG product, and tell the product how to load this module.
Here is an example MANIFEST.MF for our ATeamSample module
ATG-Product: ATeamSample ATG-Class-Path: lib/classes.jar ATG-Config-Path: config/config.jar ATG-Required: DAS
The purpose of each line is as follows:
There are additional fields that can be added to the MANIFEST.MF file. Refer to the product documentation for more details.
The structure of a Maven project is different from the layout used for ATG modules.
A sample layout of a Maven project to be used with Oracle ATG Commerce is as follows:
Using the EStore module in the Commerce Reference Store sample application, the following shows a mapping of Maven directories to ATG Module directories.
The sample build process available on github shows you how to automatically compile, jar, and move files from Maven to the appropriate ATG directory structure.
The following best practices are demonstrated in the sample build process available on github.
Define artifact dependencies in as few locations as possible. Ideally, a single parent pom will define the specific version of artifacts all your modules utilize. This gives you a central location to control what version of what artifact is being used, and helps prevent clutter across poms that can result is conflicting dependencies like pulling in multiple versions of the same library.
Pull tag libraries in at build time with Maven.
Instead of including a tag library in your maven builds, and possible having the exact same tab library checked in to your source repository in multiple locations, you can pull the tab libraries directly into your build at build time.
This allows you to centrally manage your tab libraries in a single location, and easily update the version of a tag library your build is using.
Here is a sample scenario seen on actual projects in the past.
Multiple custom ATG modules were checked into source control. The DSP tag library was used by several of these modules. This resulted in dspjspTaglib1_0.jar and dspjspTaglib1_0.tld being checked in to source control multiple times, in multiple locations. There were actually many product tag libraries in multiple locations, all checked in the same way.
When it came time to upgrade/patch the ATG product, it was necessary to manually locate every product tag library checked into source control, and manually update it to the new version. It took several iterations, and a good deal of time to get them all updated.
By allowing Maven to pull in the tag libaries you want at build time, you add your new taglib to your Maven repository, update your pom file to point at the new version, and rebuild your code. The new version is automatically pulled in.
Similar to the tag libraries, 3rd party libraries can be pulled in at build time.
In the Maven to ATG mapping image above, commons-codec-1.3.jar is shown. Instead of checking this into source control, and embedding it in your Maven module, it can be pulled in at build time when it is needed.
Custom fields can be added to the ATG Modules MANIFEST.MF
These fields can be visible in /dyn/admin, and optionally accessed through JSP's in your running application.
Maven can be used to automatically add items like a build number, and/or build timestamp to your MANIFEST when you build your code.
This is useful to keep track of exactly what version of code is running in what environment.
When following the above suggestions using a parent pom, and allowing Maven to manage dependencies, the same process will work in an IDE. You are not loosing development functionality by allowing Maven to manage your dependencies.
This Maven samples in github, and best practices mentioned here also translate to Oracle's Developer Cloud Service.
By following the layout and dependency management techniques outlined here, you can easily move a local project to Developer Cloud Service.