ATG/Oracle Commerce modules are simply functional parts of an application that have been given their own organization and identifier. With a large e-commerce project, it might be split into the following modules:

  • Storefront (primarily jsps and config only)
  • Mobile (primarily jsps and config only)
  • Custom ATG code
  • Search
  • Integrations

This is highly-dependent on the software integrator in charge of the application development. ATG/Oracle Commerce itself is mostly just a collection of modules. Some notable examples are:

  • DAF (Dynamo Application Framework) – Responsible for Nucleus and other very important services
  • DAS (Dynamo Application Server) – Another core module, brings many
  • DCS (Dynamo Commerce Server) – Core ATG/Oracle Commerce commerce functionality
  • DPS (Dynamo Personalization Server) – Primarily personalization (targeters, slots), among other things

You can find more info on the out-of-the-box modules in the Appendix E. ATG Modules of the ATG Programming Guide.

When learning ATG/Oracle Commerce, it can be a good exercise to write an ATG module from ground up. It will give you experience in a core ATG/Oracle Commerce area, and also strip ATG/Oracle Commerce down to something that seems more manageable if you’re just starting out. I think everyone should at least once labor through and write an ATG/Oracle Commerce module from the ground up. It really teaches a lot of things.

In this discussion, we’ll make a custom ATG/Oracle Commerce module that includes java files, configurations, and an application WAR (jsps). The complete source of the module can be found towards the end of this post.

Writing the Module

The controlling power in an ATG/Oracle Commerce module is the MANIFEST.MF file, located as shown below:

$DYNAMO_ROOT (where ATG is installed)

—-> SparkredHelloWorld/

——–> META-INF/

————> MANFEST.MF

The manifest file is required in all ATG/Oracle Commerce modules. It specifies meta information to ATG/Oracle Commerce. Much of the information is required for the module assembly process.

The manifest clearly outlines the resources contained within the module. You can take a look at any of the out-of-the-box modules for a practical example of a manifest.

The manifest is really the only “required” file in an ATG/Oracle Commerce module. As you layer in things like java files, configuration and WARs, you’ll need to specify them in the manifest, otherwise ATG/Oracle Commerce will never know they’re there!

Step 1. Creating the Structure

To start with the module, create the following structure with your $DYNAMO_ROOT directory. Your module should be along-side all of the other ATG/Oracle Commerce modules mentioned above.

$DYNAMO_ROOT/

—-> SparkredHelloWorld

——–> META-INF/

————> MANIFEST.MF

Step 2. Adding Configuration

The first practical thing we’ll add is configuration to the module. We need the configuration to start out because we’ll override some ATG/Oracle Commerce properties to get the datasource setup as later on.

2.1. Add the following into MANIFEST.MF:

ATG-Config-Path: config/

2.2. Add a config directory into the root of your module:

$DYNAMO_ROOT/

—-> SparkredHelloWorld/

——–> META-INF/

————> MANIFEST.MF

——–> config/

All configuration goes into this directory. In most cases, the configuration is jarred up, and ATG-Config-Path would reference config/config.jar. We won’t do that to keep things simpler.

Step 3. Adding Java Source Files

Next, we’ll add a place for java source files.

3.1. Add these provisions into MANIFEST.MF:

ATG-Class-Path: lib/classes/

3.2. Create a src directory in the root of your module. The module should now look like:

$DYNAMO_ROOT/

—-> SparkredHelloWorld/

——–> META-INF/

————> MANIFEST.MF

——–> config/

——–> src/

ATG-Class-Path is where all .class files are located, NOT .java files. Once again, they are almost always jarred up, so ATG-Class-Path would reference lib/classes.jar, but we won’t complicate it.

Step 4. Adding a Web Application Archive (WAR)

The final component we’ll add is a WAR for jsp files. This is also the hardest to get right, so pay attention closely.

4.1. From the root of your module, add the following files/directories:

$DYNAMO_ROOT/

—-> SparkredHelloWorld/

——–> META-INF/

————> MANIFEST.MF

——–> config/

——–> j2ee-apps/META-INF/application.xml

——–> j2ee-apps/store.war/WEB-INF/web.xml

——–> j2ee-apps/store.war/META-INF/MANIFEST.MF

There are a few j2ee configs to hook up in these files to ensure that the application is registered and the context root is setup correctly. I’m not going to go through each one. Instead, you can take a look at them using the module source provided at the end of this post.

4.2. Add reference to the war using the ATG-Web-Module directive in the module’s root manifest:

ATG-Web-Module: j2ee-apps/store.war

Step 5. Adding Datasources

Core ATG/Oracle Commerce requires a database and a number of tables to function. Since we’re only going to be using a small subset of ATG/Oracle Commerce functionality for the module, we can get away with just a little SQL to run.

Once we get the correct tables created, we also have to tell ATG/Oracle Commerce which data source to use, and how to connect to it.

5.1. Install or get access to an Oracle (or what have you) database that is the correct version per your ATG/Oracle Commerce version. I’d recommend grabbing a VM with Oracle pre-installed, as I detailed in the article Setting Up ATG/Oracle Commerce on Mac OSX.

5.2. With Oracle setup and running, log in as root and make a user for this project:

create user myproj_core identified by myproj_core;

grant connect, resource, dba to myproj_core;

5.3. The only SQL you should need to run can be found at $DYNAMO_ROOT/DAS/sql/install/oracle/das_ddl.sql. Run that against myproj_core.

5.4. Add the following two configuration files into the config as shown:

$DYNAMO_ROOT/

—-> SparkredHelloWorld

——–> META-INF/

————> MANIFEST.MF

——–> config/

——–> config/atg/dynamo/service/jdbc/FakeXA_DS.properties

——–> config/atg/dynamo/service/jdbc/JTDataSource.properties

——–> j2ee-apps/META-INF/application.xml

——–> j2ee-apps/store.war/WEB-INF/web.xml

——–> j2ee-apps/store.war/META-INF/MANIFEST.MF

FakeXA_DS.properties should contain:

$class=atg.service.jdbc.FakeXADataSource

driver=oracle.jdbc.driver.OracleDriver

JTDataSource.properties should contain:

$class=atg.nucleus.JNDIReference

JNDIName=java:/XAOracleDS

min=10

max=10

blocking=true

maxFree=-1

loggingSQLWarning=false

loggingSQLDebug=false

loggingSQLInfo=false

dataSource=/atg/dynamo/service/jdbc/FakeXA_DS

loggingSQLError=false

For more info on these files, take a look at the Configuring ATG Data Sources for Data Import section of the “ATG Installation and Configuration Guide”.

5.5. Next we have to setup the datasources on our application server. The ATG/Oracle Commerce configurations only say “use a datasource with JNDI name XAOracleDS”. It’s up to the application server to make XAOracleDS something we can use.

For JBoss: Open the atg-xa-ds.xml file found in the module source, and edit the “URL”, “User” and “Password”. Place the file in $JBOSS_HOME/server/<server>/deploy

For WebLogic: You can configure this in the WebLogic admin console with the steps found in the Configuring and Managing Weblogic JDBS document.

For other application servers: You’re on your own.

5.6. In the final step may be optional. If you find ClassNotFoundException errors in your log for the OracleXADataSource class, you need to add the correct database driver jar into your classpath. They can be found on the Oracle Technology Networking page.

These steps will give you the baseline tables required for core ATG/Oracle Commerce to run. As you layer in more ATG/Oracle Commerce components like commerce, search or publishing, more schemas will have to be created.

Step 6. Tying Everything Together

Now that all of the groundwork for the module is laid, we can create an ATG/Oracle Commerce component and jsp to invoke it to verify everything works.

6.1. Copy TestDroplet.java, TestDroplet.properties and hello.jsp into the following locations within your module. The three files are really basic and I’m not going to spend time  explaining them. You can find them within the module source. The final structure of your entire module should match below:

$DYNAMO_ROOT/

—-> SparkredHelloWorld/

——–> META-INF/

————> MANIFEST.MF

——–> config/

——–> config/atg/dynamo/service/jdbc/FakeXA_DS.properties

——–> config/atg/dynamo/service/jdbc/JTDataSource.properties

——–> config/com/acme/droplet/TestDroplet.properties

——–> j2ee-apps/META-INF/application.xml

——–> j2ee-apps/store.war/hello.jsp

——–> j2ee-apps/store.war/WEB-INF/web.xml

——–> j2ee-apps/store.war/META-INF/MANIFEST.MF

——–> src/com/acme/droplet/TestDroplet.java

Click SparkredHelloWorld to download the final module source.

Building and Assembling the Module

Use the build.xml script contained within the module source to build the module. All it does is compile the source and place it into lib/.

To assemble the application run:

$DYNAMO_HOME/bin/runAssembler $JBOSS_HOME/server/<server>/deploy/SparkredHelloWorld.ear -m SparkredHelloWorld

This is for unix-based systems running JBoss. For windows or other application servers, you’ll have to change some things.

Testing the Module

The final step is starting the application server and ATG/Oracle Commerce. If using JBoss, you can use:

$JBOSS_HOME/bin/run.sh -c <server>

You’ll have to modify for other application servers.

You can finally test the application by hitting the URL:

<host>:<port>/store/hello.jsp

If all is well you’ll see “Hello, World!”.

Summary

I’ve given the steps to write a barebones ATG/Oracle Commerce module from the ground up. In the interest of time and simplicity, I’ve left out many things.  Please excuse my hand-wavy procedure; this is only meant for learning. Here are some things I feel obligated to remind that I skipped:

  • I’ve only scratched the surface on web.xml and application.xml
  • There are tons more directives that can be used in the manifest files. A full list can be found in the Application Module Manifest File section of the ATG Platform Programming Guide
  • Multisite isn’t setup or even considered
  • Skirted around ATG database schemas, which can be hard to keep straight
  • The droplet I wrote was only for environment verification, it in no way resembles a practical ATG droplet

For a more detailed example of module structure, download and take a look at the ATG Commerce Reference Store’s layout.