What's changed for deploying customized assets

In WebSphere Commerce V6, there are changes that you should be aware of when deploying customized assets in WebSphere Commerce version 6.0. The information includes customizing the database, the Enterprise Application (EAR) file, and the Web server. It is intended for users who have experience with previous versions of deployment within WebSphere Commerce.

Deployment changes have been made in the following areas:

 

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 be limited to the following assets:

WebSphere Commerce is a J2EE application and is therefore packaged as an EAR file to leverage the deployment capabilities provided by J2EE application servers. WAS distributes the EAR file throughout your distributed environment, and therefore, it is imperative that this EAR file contains all files needed for the 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 6.0, the WebSphere Commerce application has been repackaged. All files required at runtime are now inside the EAR file. WAS can now 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:

 

Configuration files

The packaging for WebSphere Commerce 6.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; use a dynamic mechanism to locate the files. WebSphere Commerce 6.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 6.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:

In addition, WebSphere Commerce has included additional utility JAR files and the WC_ instance.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>

during the migration process to WebSphere Commerce 6.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 .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 6.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 .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 6.0 by leveraging the fine grained application update feature of WAS 6.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 WAS 6.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:

WAS offers a fine grained application update feature, which ensures that the application will be updated correctly. WAS 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.

It is imperative that you use the WAS tooling to update the WebSphere Commerce application. If you use the old deployment procedure you will encounter problems later, such as:

Related concepts

Customized WebSphere Commerce database assets
Customized WebSphere Commerce Enterprise Application (EAR) assets
Customized WebSphere Commerce Web server assets

Related tasks

Stages of deploying customized assets
Package custom database assets
Deploy custom database assets
Package custom J2EE assets
Deploy custom J2EE assets
Package custom Web server assets
Deploy custom Web server assets

Related reference

Minimizing downtime during deployment
Troubleshoot: Deployment
WebSphere Commerce deployment checklist
Top 10 tips to ensure a successful deployment of WebSphere Commerce
How to increase your success with WebSphere Commerce deployment
Additional deployment resources