Deprecated feature

Separating a store EAR into multiple store EAR files

You can separate a store enterprise archive (EAR) file into multiple EAR files. By separating the store EAR into multiple EAR files, you can separate your store web application archive (WAR) files into multiple store WAR files. Separating store contents into multiple WAR files provide developers the capability to create or update assets for different parts of the storefront independently.

Before you begin

Ensure that you complete the following tasks:
  • Enable the separation of the store WAR from the WebSphere Commerce EAR into a new store EAR. You must separate the store WAR into a new store EAR before you can split the archive into multiple EAR files. You must also include all foundation classes for the store in a shared library so that each of the store WAR files you create can reference the classes. For more information about separating the store archive, see
  • Verify that the pages for your store can be isolated with only a minimum set of common pages and assets. Common pages or assets must be deployed within all WAR files that use the pages or assets.
Note: There is no automated deployment or migration available for moving assets into the multiple EAR files. After you separate the EAR into multiple EAR files, you must manually move files and file changes into the appropriate new EAR file

About this task

By separating the store EAR file into multiple EAR files, store assets can be separated into different WAR files by component. If your site has multiple stores, a store EAR can be created for each store. Different development teams can then focus on developing assets for different stores or focus on developing assets for specific components of a store. For example, one team can develop catalog browsing pages, while another team develops shopping cart pages.

When you separate the store EAR into multiple EAR files, you use the initial separated store WAR as a central store WAR file. Each new WAR file that you create can then contain assets for specific store components or new store features. By configuring the extended document root in each new WAR file, you can use a single version of JSP files in the central WAR file. Other WAR files can then reference the JSP file. WebSphere Application Server shared libraries are used to connect the separate EAR files and to include files that files in each EAR can reference and use.

For more detailed examples of setting up multiple EAR files for a sample store, see

Procedure

  1. Create another enterprise archive (EAR) project for your store. The store assets in your initial separated store EAR file can be divided between the new EAR file and the initial separated EAR file.
  2. Create the store WAR file for the new EAR file.
    1. Create an empty WAR file within the new EAR file.
    2. Go to the WebContent\WEB-INF directory in the initial separated store EAR file.
    3. Copy the following files and subfolders from the WEB-INF directory.
      • tiles-def.xml
      • validator-rules.xml
      • *.tld
      • lib/Foundation-TagLib.jar
      • web.xml
    4. Go to the WebContent\WEB-INF directory in the new store WAR and add the copied files and subfolders into this WEB-INF directory. Overwrite the web.xml that exists in your new WAR.
    5. Go to the WebContent/WEB-INF directory in the new store WAR and open the web.xml file for editing.
    6. Update the values for the display-name element, ServletName parameter, and the struts configuration files.
      Each store WAR file that you create must have a unique display-name and ServletName value.
      For example, the following code snippet sets the value for display-name element and ServletName parameter to be Stores1:
      <web-app ...
    <servlet>
         <display-name>Stores1</display-name>
         ......
          <init-param>
            <param-name>config</param-name>
            <param-value>...struts config files...</param-value>
         </init-param>
    </servlet>
    ......
     <filter>
        ......
        <init-param>
            <param-name>ServletName</param-name>
            <param-value>Stores1</param-value>
        </init-param>
    </filter>
   ......
</web-app>
  3. Configure the extended document root for your store WAR files. The extended document root allows JSP file resources to be shared across WAR files. With the extended document root configured, files in the new store WAR can reference files in the initial separated store WAR.
    For example, common JSP files such as the header and footer for store pages.

    If you intend for the two WAR files to be independent modules, this configuration is not needed.

    If files in the initial separated store WAR references files in the new store WAR, configure the extended document root for the initial separated store WAR to point to the new WAR. For example, if your new store WAR includes all order JSP files, the initial separated store WAR might include files that need to reference the order status JSP file in the new WAR for display on the My Account page.

    1. Go to the WebContent/WEB-INF directory of your new store WAR and open the ibm-web-ext.xml file for editing.
    2. Add the following element to configure the extended document root to point the JSP directory of your new store WAR to the initial separated store WAR file.
      WebSphere Commerce Enterprise
      <jsp-attribute name="extendedDocumentRoot" 
 value="WC_profiledir/installedApps/cell_name/WCStores_instance_name.ear/Stores.war" />
      Where WCStores_instance_name.ear is the name of the initial separated store EAR file.WebSphere Commerce Developer
      <jsp-attribute name="extendedDocumentRoot" value="workspace_dir/Stores/WebContent"/>
      Where Stores is the name of the initial separated store WAR file
    3. In the WebContent/WEB-INF directory of the initial separated store WAR and open the ibm-web-ext.xml file for editing.
    4. Add the following element to configure the extended document root to point the JSP directory of your old store WAR to the Stores1.war in your new store WAR file.
      WebSphere Commerce Enterprise
      <jsp-attribute name="extendedDocumentRoot" 
 value="WC_profiledir/installedApps/cell_name/WCStores1_instance_name.ear/Stores1.war" />
      Where WCStores1_instance_name.ear is the name of the new store EAR file and Stores1.war is the file name of the new store WAR file.WebSphere Commerce Developer
      <jsp-attribute name="extendedDocumentRoot" value="workspace_dir/Stores1/WebContent" />
      Where Stores1 is the name of the new store WAR file
    5. Save and close the files.
      For more information about the extended document root property, see JSP engine configuration parameters.
  4. Copy the EJB references from your initial separated store WAR file into your new store WAR file.
    1. In the Stores\WebContent\WEB-INF directory of the initial separated store EAR, open the ibm-web-bnd.xml file for editing.
    2. Copy the following EJB references: 
      <ejb-ref name="ejb/BusinessContextServiceWrapperLocal" 
  binding-name="ejb/com/ibm/commerce/component/contextservice/objects/BusinessContextServiceWrapperHome" />
<ejb-ref name="ejb/MemberGroupMemberService" 
 binding-name="ejb/com/ibm/commerce/user/objects/service/MemberGroupMemberServiceLocalHome" />
<ejb-ref name="ejb/ContextManagement" 
 binding-name="ejb/com/ibm/commerce/context/objects/ContextManagementHome" />
<ejb-ref name="ejb/ContextData" 
 binding-name="ejb/com/ibm/commerce/context/objects/ContextDataHome" /></web-bnd>
    3. Go to the corresponding directory in your new store EAR and open the ibm-web-bnd.xml file for editing.
    4. Add the copied EJB references into the file. Then, save and close the file.
  5. Add store contents to the new WAR file.
    1. Compose the struts entries to be handled by the new store WAR file. Add these struts entries to the struts configuration files within the new store WAR file. If the initial separated store WAR no longer needs these struts entries, remove the entries from the struts configuration files in the initial separated store WAR.
    2. Add the store assets that belong to the components that you want to include in the new store WAR file. If the initial separated store WAR no longer needs any of these files, remove the files the initial separated store WAR file.

      When you are deploying files into multiple store WAR files, consider how store assets are connected to ensure that the assets can function correctly within each store WAR. You can choose to deploy assets within each WAR file, within specific WAR files, within the shared library, or keep the files within the initial separated store WAR file. For instance, consider adding store assets to your new store WAR files based on the following suggested deployments. The following file paths are relative to the WebContent folder within the initial separated store WAR file.

      Keep the following types of files deployed within the initial separated store WAR file.
      • store_name/Common/* - Reference these files by the extended document root.
      • store_name/css/* - Reference these files by the fixed asset path.
      • store_name/EmailTemplates/* - Reference these files by the fixed asset path. These templates are referenced by using the context root of the initial separated store WAR file. If you do move a template into another store WAR file, you must customize any related messaging classes so the context root of the appropriate WAR file is used.
      • store_name/images/* - Reference these files by the fixed asset path.
      • store_name/javascript/* - Reference these files by the fixed asset path.
      • store_name/nls/* - Reference these files by the fixed asset path.
      • store_name/rwdWebAssets/* - Reference these files by the fixed asset path.
      • store_name/StaticContent/* - Reference these files by the fixed asset path.
      • store_name/
      • WEB-INF/stores/store_name/data/ForeignKeys.dtd
      • WEB-INF/stores/store_name/data/ibm-wc-load.xml
      • WEB-INF/stores/StoreAssetsDir/data/accesscontrol.xml
      • WEB-INF/xml/seo/*
      • WEB-INF/classes/ - You can include custom classes that are within this directory in each store WAR file. Keep the classes that are provided by WebSphere Commerce in the initial separated store WAR.
      • WEB-INF/config/* - You can also include custom files in this directory within each store WAR file.
      • dojo*/* - Reference these files by the fixed asset path.
      • images/* - Reference these files by the fixed asset path.
      • SampleDistributors/* - Reference these files by the fixed asset path.
      • tools/* - Reference these files by the fixed asset path.
      • include/* - Reference these files by the extended document root. You can also include these files within each store WAR file and reference the files through a view.
      • Widgets/* - Reference these files by the extended document root. You can also include these files within each store WAR file and reference the files through the relative path to the file or through a view.
      • config/commerce/store/propertiesViews/store_name/StoreFlexFlowPropertiesView.def
      Deploy the following files into each individual WAR file that needs to reference or use the file.
      • WEB-INF/tiles-defs.xml
      • WEB-INF/validator-rules.xml
      • WEB-INF/xsd/get-data-config.xsd
      • WEB-INF/cachespec.xml - Include this file in each WAR file. This file should include the cache entries for the store pages that are in that WAR file.
      • WEB-INF/config/* - You can deploy the custom files within the config directory into each WAR file. Keep the files that are provided with WebSphere Commerce in the initial separated store WAR file or the shared library.
      • store_name/Container/* - Reference these files through the relative path to the file.
      • store_name/ShoppingArea/* - Reference these files through the relative path to the file.
      • store_name/LandingPages/* - Reference these files through a view.
      • store_name/Layouts/* - Reference these files through a view.
      • store_name/include/* - Reference these files through a view. You can also keep the files in this directory in the initial separated store WAR file.
      • store_name/Snippets/* - Reference these files through the relative path to the file or through a view.
      • store_name/StoreInfoArea/* - Reference these files through the relative path to the file or through a view.
      • store_name/UserArea/* - Reference these files through the relative path to the file or through a view.
      • store_name/other *.jsp* files - Reference these files through the relative path to the file or through a view.
      • store_name/Widgets/* - Reference these files through the relative path to the file or through a view. You can also keep the files in this directory in the initial separated store WAR file.
      • other *.jsp* - Reference these files through the relative path to the file.
      • webservices/* - Reference these files through the relative path to the file or through a view.
      Deploy the following files into the shared library if the file is referenced by multiple WAR files. You can deploy the file into each WAR file that needs to reference or use the asset. If the file is used by only a single WAR file, include the file within the individual WAR file.
      • Resource bundles
    3. Configure the cache entries for the new store WAR.

      You can use dynamic caching for all store WAR files. The WebSphere Application Server can differentiate cache entries in each WAR file by using the context roots. For files that exist within more than one WAR file, such as headers and footers, you can create a cache entry for the page in each WAR.

      1. Go to the WebContent/WEB-INF directory in the new store WAR and open the cachespec.xml file for editing.
      2. Add the cache entries for the store pages that you added into the new store WAR file. If any store page in the initial separatedStores.war file is referenced by the new WAR file and needs to be cached, add entries for the pages to the cachespec.xml file.
      3. Save and close the file.
      4. If the initial separated store WAR no longer needs the cache entries for the actions and views that are handled by the new WAR file, remove the cache entries from cachespec.xml file in the initial separated store WAR.
  6. Enable multiple store WAR files for your WebSphere Commerce instance in the wc-server.xml for your site:
    1. Go to the following directory and open the wc-server.xml file for editing.
      • SolarisLinuxAIXWC_eardir/xml/config
      • WebSphere Commerce DeveloperWindowsWC_eardir\xml\config
    2. Search for StoreWebModuleName="Stores" in the file. Add the configuration MultipleStoreWARs="true" to the file
      For example, 
      <Instance
  ...
  StoreWebModuleName="Stores"
  MultipleStoreWARs="true"
  .../>
    3. Save and close the file. You must republish the WebSphere Commerce application before the change takes effect.
  7. Optional: Register the new WAR file in WebSphere Commerce by adding a web module to the wc-server.xml file for your WebSphere Commerce instance. Add the web module if the store module in the new store WAR has its own parameters.
    For example, the following code adds a web module for a new store WAR that is called Stores1.
    <Module contextPath="/webapp/wcs/stores1" fileServletEnabled="false" name="Stores1" 
 urlMappingPath="/servlet" webAlias="/wcsstore">
  <InitParameters adapters="XML/HTTP, BrowserAdapter" contextSetName="Store" handleDoubleClick="true"/>
  <URLRedirectFilter enable="false"/>
</Module>

    If any new store module is not registered in the wc-server.xml file, a web module is automatically created for the new servlet. The parameters for the new servlets are the same as the parameters of the initial separated store WAR file.

  8. Deploy the new store WAR module by adding the module to your new store EAR. For more information, see Deploying a WAR module.
  9. Configure the context roots for the new store WAR within the new store EAR.
    1. Go to the META-INF directory in the new store EAR and open the application.xml file for editing.
    2. Add the context root information for the new WAR.
      For example, the updated file can resemble the following code snippet.
      <?xml version="1.0" encoding="UTF-8"?>
<application id="Application_ID" version="5" xmlns="http://java.sun.com/xml/ns/javaee" 
 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
 xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/application_5.xsd">
...
 <display-name>WCStore1_instance_name</display-name>
 <module id="Module_1396511150409">
  <web>
    <web-uri>Stores1.war</web-uri>
    <context-root>/webapp/wcs/Stores1</context-root>
  </web>
 </module>
...
</application>
      Where WCStore1_instance_name is the name of the new store EAR and Stores1.war is the file name for the new store WAR file.
    3. Save and close the file.
  10. Configure the order that the new EAR starts within the WebSphere Commerce application. The WebSphere Commerce EAR application must start before any store EAR application.
    WebSphere Commerce Enterprise
    1. In the WebSphere Application Server administration console, expand Applications > Application Types and click WebSphere enterprise applications.
    2. In the list of available applications, click the new store EAR application.
    3. In the Detail Properties section, click Startup behavior.
    4. Set the value for Startup order to be higher than the value for the WebSphere Commerce EAR. For example, you can set the value to be 100.
    WebSphere Commerce Developer
    1. Go to the following directory and open the deployment.xml file for editing.

      WCDE_installdir\wasprofile\config\cells\localhost\applications\WCStores1_instance_name.ear\deployments\WCStores1_instance_name

      Where WCStores1_instance_name is the name of the new store EAR.
    2. In the <appdeployment configuration, search for the startingWeight attribute. Set the value for the attribute to be higher than the value for the WebSphere Commerce EAR. For example, set the value to be "100".
      <appdeployment:Deployment ... >
  <deployedObject... startingWeight="100" ... >
    3. Save and close the file.
  11. Publish the new store EAR to the application server.
  12. Optional: If you want to prevent the new store EAR application from taking on traffic, remove the context roots from the web server plug-in for the new store WAR in the new store EAR application.
    • IBM HTTP Server
      1. Go to the following directory:
        • For IBM i OS operating systemSolarisLinuxAIXWC_installdir/instance/instance_name/httpconf
        • WindowsWC_installdir\instance\instance_name\httpconf
      2. Open the httpd.conf configuration file for editing.
      3. Locate and remove the context root configuration for the store WAR file in the new store EAR.
    • Sun ONE web server
      1. Locate and open the obj.conf web server configuration file for editing.
      2. Locate and remove the context root configuration for the store WAR file in the new store EAR.
    • WindowsInternet Information Services (IIS) Manager web server

      In the IIS Manager, Locate and either disable or remove the context root configuration for the store WAR file in the new store EAR.