Deprecated feature

WebSphere Commerce store archive separation

WebSphere Commerce provides the capability to separate the store (WAR) web application archive from the WebSphere Commerce (EAR) enterprise archive. When store developers create or change store assets, the assets must be included within the store WAR. Separating the store WAR from the WebSphere Commerce EAR, creates a new store EAR that contains a copy of the store WAR. Separating the store WAR can provide store developers the capability of packaging and deploying assets independently of developers that are deploying non-storefront assets.

By default all assets for a WebSphere Commerce site is packaged and deployed within a single application, the WebSphere Commerce EAR. After feature pack enablement WebSphere Commerce search assets are moved by default into a separate Search_instance_name.ear EAR file. Your site administrators and developers can also choose to separate store assets into a separate store EAR.

The following diagram shows the default process for developers to build and deploy assets into the production environment. In this process, when your site has multiple development teams that are simultaneously customizing WebSphere Commerce, the teams must schedule asset deployment to prevent errors or conflicts during the build process.


Deployment process before store archive separation

If asset deployment is not coordinated, errors and conflicts can occur during the build and deployment process when both teams are updating the WebSphere Commerce EAR simultaneously. By separating the store WAR, development teams that customize storefront assets can package and deploy store assets independently from teams that are customizing and deploying non-storefront assets. By deploying store assets into a separate EAR, the build and deployment process does not conflict with the deployment of non-storefront assets into the WebSphere Commerce EAR. The following diagram shows the process for developers to build and deploy assets after the store WAR is separated into a new store EAR.


Deployment process after store archive separation

In this build and deployment process, storefront and server-side development teams can create or update assets independently of the other team. The teams can build and deploy packages of assets from the development environment into a run time environment with a separated store archive. In this run time environment, storefront developers deploy the package of storefront assets into the store EAR. Developers deploy the package of server-side assets into the WebSphere Commerce EAR. Any assets that are deployed into the WebSphere Commerce EAR that must be referenced by logic or assets in the store EAR are referenced using a shared library.

When the store WAR is separated into a new store EAR, two shared libraries are configured to link the store EAR and WebSphere Commerce EAR. One shared library is intended for assets and logic that is provided by default with WebSphere Commerce. The second shared library is intended for your custom assets and logic. With these shard libraries, your store developers can separate the custom logic for your site from the logic that is provided by WebSphere Commerce.

If your site includes both a staging and production run time environment as shown in the preceding diagram, assets that are deployed to the staging environment must be published to the production environment. Administrators can use WebSphere Commerce utilities to propagate the new or changed assets from the separated EAR files to the corresponding locations in the production environment.

When the store WAR is separated into a new store EAR, the store EAR and WebSphere Commerce EAR still run as part of the same WebSphere Application Server process. The two EARS, while independent, run within the same Java virtual machine (JVM). Since the two EAR files operate within the same JVM, the store EAR can access classes and assets within the WebSphere Commerce EAR through shared libraries and a configured server level extension class loader. Each EAR however operates independently and all method invocations are still local calls without the use of remote calls. Any dependencies between custom store assets and default-provided assets remain.

Store separation enablement

To enable store separation, an administrator must use the WebSphere Commerce feature enablement framework to update your WebSphere Commerce instance to support store archive separation. The store WAR separation can be completed after feature pack enablement by running a script to enable the store separation. The store separation script exports a copy of the store WAR from the WebSphere Commerce EAR. The separation process then moves the copied WAR and store assets for all stores within the WebSphere Commerce instance into the new store EAR. The separation process disables the original store WAR that is within the WebSphere Commerce EAR. The new store WAR within the store EAR uses the same context root that was used before the store separation. For more information about completing the task to separate the store WAR into a new store EAR, see Separating the store WAR from the EAR.

The WebSphere Commerce Build and Deployment tool is updated to provide developers the option to deploy packaged assets into the WebSphere Commerce EAR, WebSphere Commerce search EAR, or a separated store EAR.

When the store archive is separated into a new store EAR, the two new shared libraries are configured along with a new server level extension class loader.

Shared libraries

A shared library is a configuration that points to a group of JAR files that can be accessed by a JVM. These shared libraries serve as a link between the applications. The store EAR application can use the shared libraries to access and use assets within the WebSphere Commerce application. Each shared library is associated with an extension class loader that loads the shared library so that other libraries or applications can reference the contents within the library. For more information about shared libraries, see Shared libraries.

When the store separation runs, two new shared libraries are configured to point to the location of the assets to make the assets available to a class loader. The shared libraries that are configured by the separation process point to the JAR files and assets within the WebSphere Commerce EAR. These shared libraries provide the class loader the capability to locate classes when needed. The following shared libraries are configured by the store separation process:
  • Shared library for assets that are provided by WebSphere Commerce

    This library is used for all of the JAR files and resources from the WebSphere Commerce EAR that a store can use. By default, the separation process identifies the assets and logic that are used by default-provided resources for a store and points to these assets with the shared library. For instance, the separation process configures the shared library to point to all Java archive (JAR) files that were in the WebSphere Commerce EAR.

  • Shared library for custom logic

    This shared library does not need to point to any files by default. When your store developers complete customization of store assets, the developers must then update the shared library to point to any custom logic that must be included within the WebSphere Commerce EAR and used by the store EAR.

The shared libraries exist at the directories level for easy maintenance and usage. The directory level classpath ensures that the content for all of the JAR files and compressed files within the library can be loaded for usage by the WebSphere Commerce applications. When your store or site developers add references to new JAR files or compressed files into the shared libraries, the new files load when the server restarts. The developers do not need to update the definition of the shared library.
Note: While the shared libraries can be configured to allow logic and assets in the WebSphere Commerce EAR to use assets within the store EAR, as a best practice, Do not configure this two-way relationship. As a best practice, ensure that the shared libraries are configured to only allow the store EAR to access and use logic and assets within the WebSphere Commerce EAR. As a best practice with this relationship, Java code and any server-side customization are deployed into the WebSphere Commerce EAR and storefront assets, such as JSP files and HTML are deployed into the store EAR.

Class loaders

Class loaders are part of the JVM code and are responsible for finding and loading class files. A class loader can enable an EAR application to access the repositories of available classes and resources for WebSphere Commerce.

A server level extension class loader is associated with the new shared libraries that the separation process creates. Associating shared libraries with a class loader for an application server makes the shared library available to all applications on that server. By using this extension class loader, the new store EAR can make local function calls to use assets within the WebSphere Commerce EAR through a shared library. An extension class loader must be configured for use on each server that your site uses. The class loader configuration cannot be shared within a cluster or cell level. By default, the separation process creates an extension class loader for use on each server. The separation process creates an extension class loader to associate with each of the two new shared libraries. For more information about class loaders, see Understanding Class Loaders.

Benefits and capabilities

By separating the store WAR into a new store EAR, your store and site developers can gain some of the following benefits and capabilities.
  • Store developers can create, package, and deploy assets into the store EAR independently of developers that are working on assets for the inclusion in the WebSphere Commerce or WebSphere Commerce search EAR.
  • Store developers can separate the custom logic for your stores from the logic that is provided by default by WebSphere Commerce. The custom logic can be separated and pointed to within the WebSphere Commerce EAR by the shared library for custom logic.
  • The fileprop utility is enhanced so administrators can propagate assets from a separated store archive in the staging environment to a separated store archive in the product environment.
  • Developers and administrators can use the WebSphere Commerce Build and Deployment tool to deploy assets into a selected application EAR files. This tool can deploy assets into the following applications:
    • WebSphere Commerce EAR. By default, this EAR is named WC_instance_name.ear
    • WebSphere Commerce search EAR. By default, this EAR is named Search_instance_name.ear
    • WebSphere Commerce store EAR. By default, this EAR is named WCStores_instance_name.ear
  • Existing customization for stores do not require changes. Developers need to point to the custom logic such as command implementations with a shared library.
  • Developers do not need to change how they customize WebSphere Commerce. Separating the store archive does not affect how developers use WebSphere Commerce developer. Developers can create or change assets as normal within the development environment and then deploy the assets into the separated EAR files within the production environment.
  • Depending on how assets are deployed, the assets can be available for use in the storefront when the store EAR is restarted, without restarting the server. If store developers are deploying assets into only the store EAR, only the store EAR needs to restart when the following conditions are met.
    • Assets are deployed within only the store EAR.
    • Assets are not deployed within the WebSphere Commerce EAR. If this EAR is updated, the EAR and the server must restart before the assets can be used in a store. If only the WebSphere Commerce EAR is restarted, the store cannot function properly because the store EAR can still reference old EJB references. These EJB references can be invalid after the WebSphere Commerce EAR updates.
    If conditions are not met, the EAR file and server must restart before the assets are available for use in a store.
  • Caching is not affected by separating the store archive. The cache configuration files however are affected. The store JSP cache definition file, cachespec.xml, is included in the store WAR within the new store EAR. The data cache instance configuration file, cacheinstances.properties, remains within the WebSphere Commerce EAR.
  • Separating the store archive does not affect how administrators apply maintenance, fix packs, or feature packs to WebSphere Commerce.
  • Separating the store archive does not affect existing store models. Existing stores can support the store archive separation.

Considerations

  • The separation of the store WAR is not completed as part of enabling the store enhancements feature. After a site administrator installs your latest feature pack, the store archive separation can be enabled only after an administrator enables the store enhancements feature.
  • The separated WebSphere Commerce EAR and store EAR must remain in the same Java virtual machine (JVM), even within a clustered environment. This limitation is due to the constraints of the class loaders, which exist at the server level.
  • Within a clustered environment, the separated WebSphere Commerce EAR and store EAR must remain in the same cluster. This limitation is due to the class loader constraint and the shared libraries that can reference JAR files within the EAR files.
  • Any custom logic that reads or writes directly to files within the store WAR must be updated after store separation to use the new location of the store WAR.
  • Store developers must change their process for deploying store assets. Developers must deploy store assets, including customized assets, into the separated store EAR, and configure the appropriate shared library. Before the store WAR is separated, developers must deploy assets into only the WebSphere Commerce EAR.
  • After you complete the initial store separation, the store WAR within the WebSphere Commerce EAR must be disabled and the context root changed. Either the store WAR within the WebSphere Commerce EAR or within the store EAR can be active, not both. This limitation exists because the store WAR in the separated store EAR uses the same context root as the store WAR within the WebSphere Commerce EAR.
  • There is no support for automated disabling of the store separation. When you separate the store archive into a separate EAR, you can undo the separation only by manually restoring your backup state and configurations. For more information, see Disabling the separation of a separated store archive.

What to do after store separation

After your store administrators enable the store separation, your store developers must deploy any custom assets for your site into the appropriate new location. When your store developers create or change assets, they can package and deploy the assets with the WebSphere Commerce Build and Deployment tool. Administrators can then publish the changed files to the production environment store EAR with existing WebSphere Commerce utilities. For more information, see Deploying new and changed store assets into a separated store EAR.

To ensure that your site and store operate correctly, ensure that site administrators and developers update any store functions and processes that use store assets to reference the new location for the assets in the store EAR or shared libraries.