What's changed for deploying customized assets

J2EE packaging improvements

The J2EE specification outlines the packaging format of J2EE applications. This package is called an Enterprise Application Archive (EAR) file. It is a single ZIP file with an .ear extension that contains special files that describe the application. The EAR file contains all of the file assets required to run the J2EE application. These include, but are not limited to the following assets:

• Utility JAR files
• EJB modules
• Web modules
• Connector modules
• XML configuration files
• Properties files

WebSphere Commerce is a J2EE application and is therefore packaged as an EAR file to leverage the deployment capabilities provided by J2EE application servers. WebSphere Application Server distributes the EAR file throughout your distributed environment, and therefore, it is imperative that this EAR file contains all files needed for your application.

In previous releases of WebSphere Commerce, many files required at runtime were stored outside of the EAR file. This made it difficult to distribute the application throughout your environment. Starting with version 7.0, the WebSphere Commerce application has been repackaged. All files required at runtime are now inside the EAR file. WebSphere Application Server can now easily distribute the application throughout the environment.

The location of the file within the EAR file varies by the WebSphere Commerce component. Some key files that have been moved into the EAR file:

• Tools framework configuration files (under xml/tools)
• Messaging files (under xml/messaging)
• WebSphere Commerce instance configuration file (that is, EAR/xml/config/wc-server.xml)
  Note: For WebSphere Commerce 7.0, there are two versions of the WebSphere Commerce configuration file. Ensure that you understand the variations.

Configuration files

The packaging for WebSphere Commerce 7.0 has changed, and therefore, the procedure for locating and reading configuration files has also changed. In addition, each WebSphere Commerce component takes a slightly different approach on how the search for the files is configured.

For a clustered WebSphere Commerce EAR file, the EAR file is stored under a different path for each cluster member. You cannot store an absolute path to any file in the application; you must use a dynamic mechanism to locate the files. WebSphere Commerce 7.0, uses the class loader to locate and read the file assets that are in the EAR file. If you migrated your instance from WebSphere Commerce 5.x to 7.0, all absolute paths in your instance configuration file have been changed to relative paths. The path is relative to entries in the class path. The following section describes how the files are located with the class path.

Be familiar with what is in the class path of the WebSphere Commerce application. All modules share the same class path. There is a single class loader for the entire application. As per the J2EE specification, the following are automatically added to the class path of the WebSphere Commerce application:

• Each EJB JAR
• For each WAR file, the following is added to the class path:
  • WAR/WEB-INF/classes
  • Project\WebContent\WEB-INF\classes
  • All JAR files under
    • WAR/WEB-INF/lib
    • Project\WebContent\WEB-INF\lib

  where WAR is the root of your Web module (for example stores.war) and Project is the name of your Dynamic Web Project (for example, stores).

In addition, WebSphere Commerce has included additional utility JAR files and the WC_ instance_name.ear/xml and /properties directories to the application class path.

As an example, consider the WebSphere Commerce tools framework system. Inside your instance configuration file, you will see the following configuration:

<ToolsGeneralConfig 
DTDPath="tools/common:tools/devtools:tools/bi:tools/catalog:schema/xml:sar"

XMLCacheSize="1000"
XMLPath="tools:tools/devtools:WEB-INF/xml/tools:WEB-INF" 
developmentMode="false" display="false" resourceBundlePath=""> 
<resourceConfig file="common/resources.xml"/> 
<resourceConfig file="preview/resources.xml"/> 
<resourceConfig file="policyeditor/resources.xml"/> 
.... 
</ToolsGeneralConfig> 

Note that during the migration process to WebSphere Commerce 7.0 runtime environment, all absolute paths in your instance.xml file have been converted to relative paths. For example, file and paths are changed to relative paths in the instance_name .xml file. If files and paths are in the EAR, their paths are relative to class paths in EAR. Consider this example: in previous release, such as WebSphere Commerce 5.6.1, you would have EcInboundMessageDtdPath="E:\WebSphere\CommerceServer561\xml\messaging. However, in WebSphere Commerce 7.0, this would be EcInboundMessageDtdPath="messaging". All files required at run time should be moved into the EAR. The EcInboundMessageDtdPath is relative to the EAR instead of to WC_installdir.

Also note that tools framework is a bit unique. It has the concept of an XML search path. This is identified by the XMLPath attribute in the tools framework system preceding example. This attribute specifies a set of directories that search for a particular file. In this example, the tools framework must load all of the resourceConfig files identified by the file attribute of the nested resourceConfig elements.

The algorithm is:

For each resourceConfig file

   for each XMLPath

           URL filePath = this.getClassLoader().getResource(XMLPath
+ "/" + resourceConfigFile)
                if (filePath !=null) file is found, process it,
move to next file 
                else file is not found, move to next XMLPath

Here is an example execution for the algorithm in the WebSphere Commerce Server environment, on AIX, when the runtime is trying to load the common/resources.xml file:

this.getClassloader().getResource("tools" + "/" + "common/resources.xml");

This causes the application server to locate the file tools/common/resources.xml in the application's class path. Since the WC_ instance_name .ear/xml directory is in the class path, the application server will return the following URL:

file:///usr/WebSphere/AppServer/profiles/demo/installedApps/WC_demo_cell/WC_demo.ear/xml/tools/common/resources.xml

If null was returned, it would move on to the next search path of this.getClassloader().getResource("tools/devtools" + "/" + "common/resources.xml");

Although some components do not have this search path feature, these components will all assume the relative paths found in the instance configuration file are retrievable from the application's class path.

Application updates

WebSphere Commerce provides an extensible application. You typically customize the WebSphere Commerce application to meet your business requirements. This could be as simple as adding some JSP files, or it could involve adding new EJB beans.

In the past, updating the WebSphere Commerce application was a cumbersome process; in particular, when using the clustering feature within WebSphere Application Server. The application update process has been improved in WebSphere Commerce 7.0 by leveraging the fine grained application update feature of WebSphere Application Server 7.0. In the past, to update the application, you needed to provide a completely new EAR file. Building, installing, and distributing the new EAR file was a time consuming process. In WebSphere Application Server 7.0, you no longer have to provide an entire EAR file. All WebSphere Commerce tooling that updates the EAR file has been updated to take advantage of this new function. Some examples:

• Publishing a starter store using the Administration Console
• Adding an attachment
• Updating a store logo using the WebSphere Commerce Accelerator
• Applying WebSphere Commerce fix packs

WebSphere Application Server offers a fine grained application update feature, which ensures that your application will be updated correctly. WebSphere Application Server ensures that the changed application files are distributed to all nodes running the WebSphere Commerce application. This also ensures that when you export the application, any customization is included in the resulting EAR file.