Introduction

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

Understanding Oracle ATG Commerce modules, and their relationship to 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.

ATG Module layout

Assume we have a module named ATeamSample. The following is an example directory structure, starting at the root of the ATG installation ($ATG_ROOT)

• $ATG_ROOT/ATeamSample
  • config - this is where configuration/properties files are located
  • lib - this is there class files, jar files, and other items meant for the classpath are located
  • META-INF - this is where the module MANIFEST.MF exists, and is the core of what defines and ATG module
    • MANIFEST.MF - The MANIFEST.MF file is what tells the ATG product that this is a module, and defines how it is structured

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:

• ATG-Product - This defines the name this module will be referred to by in the ATG product. When you pass modules to runAssembler, or load modules in your application server, the MANIFEST is parsed to look for a matching ATG-Product value
• ATG-Class-Path - This tells the product where to load classpath artifacts from
• ATG-Config-Path - This tells the product where to load configpath artifacts from
• ATG-Required - This tells the product what other ATG modules must be loaded for this module to function properly. This line is used to calculate module dependencies.

There are additional fields that can be added to the MANIFEST.MF file. Refer to the product documentation for more details.

Maven layout

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:

• src/main – this is the root of all other folders
  • module – contains the META-INF/MANFIEST.MF used by ATG modules
  • config - contains the ATG module configs, which will be jar’d and copied to your module’s config directory in ATG_ROOT
  • configlayers – contains config layers that runAssembler will pull in if they are specified
  • java – contains source code, which will be compile, then jar’d, then the jar is copied to your ATG_ROOT/module’s lib directory
  • liveconfig – contains properties for your ATG liveconfig layer
  • j2ee-apps – These trees contain war files

Mapping Maven to an ATG module

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.

Best practices with Maven

The following best practices are demonstrated in the sample build process available on github.

Use a parent pom to control artifacts

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.

Tag libraries

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.

Third party libraries

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.

Identify your build version

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.

A note on using IDE's, such as Eclipse.

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.

Integration with Oracle Developer Cloud Service

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.