Packaging Java EE assets for a partial application

Before you deploy your partial application, you must package it in a format that WebSphere Application Server understands. In a partial application update, many single file assets are combined into a compressed file in a structure that matches the final deployment. Depending on the type of files, you must take a different approach to packaging the assets for deployment. The result of this package is a compressed file of all the changed assets that are packaged for deployment.

Packaging for a partial application involves three stages:
  • First, you create a directory to contain all of the assets. This directory represents the root of the EAR
  • Next, you collect all of the assets you want to deploy and place them underneath this directory. The structure underneath this directory must match the structure that you want in the Java EE application to which you are deploying. The assets can be any combination of the following assets:
    • JAR files that contain controller commands, data beans, or Java code
    • Store assets
    • Assets that are stored outside of the WebSphere Commerce development environment workspace, such as the assets in the /xml or /properties directories
  • Finally, you package all assets as a single compressed file.

About this task

Note: All .xmi files must not be included when packaging Java EE assets for a partial application.

The following is more details on each stage. In the examples, c:\ExportTemp\partialApp is used as the directory to collect the partial application assets. You can use any directory name that you like.

Procedure

  1. Collect controller commands, data beans, or Java code.

    If you are deploying controller commands, data beans, or Java code:

    1. Export and package the files as a JAR file. You cannot deploy custom commands, data beans, and Java code unless the files are first packaged into a JAR file.
    2. Place the JAR file in the directory that you are using to build your deployment package, such as, c:\ExportTemp\partialApp. This directory represents the root of the target EAR file. Underneath this directory, the file must be in the correct path as it would be in the EAR.
  2. Collect store assets.

    If you are deploying store assets JSP files, HTML files, images, property files, and other store assets), export the file from your WebSphere Commerce development environment:

    1. Open WebSphere Commerce Developer and switch to the Enterprise Explorer view.
    2. Right-click the Stores folder then click Export > Export.
    3. In the Export wizard:
      1. Select General > File system and click Next.
      2. Select all of the resources that you want to deploy; that is, select all of the JSP files, HTML files, images, property files, and other store assets that must be deployed.
      3. Select Create directory structure for files.
      4. In the Directory field, enter a temporary directory where you want the resources to be placed. For example, enter C:\ExportTemp\partialApp
      5. Click Finish.
    4. On the file system, make the following changes:
      1. Rename the Stores directory to Stores.war.
      2. Move the contents of the WebContent directory up into the Stores.war directory. For example, move this directory and file: Stores.war\WebContent\ ConsumerDirect_name\MyNewJSPTemplate.jsp into Stores.war\ConsumerDirect_name\MyNewJSPTemplate.jsp
      3. Delete the now empty WebContent directory.
      4. Ensure the name of the store directory, for example, ConsumerDirect, matches the name of the store on the target machine.
  3. Collect assets that are stored outside of the WebSphere Commerce Developer environment workspace.

    In WebSphere Commerce Developer, all store-related assets are stored in the Stores web module and any Java or EJB assets are stored in the Rational Application Developer workspace. Some assets are not stored in the workspace at all. For instance, XML configuration files and properties files are not stored inside the workspace; these files are used for customizing the tools framework. The following table illustrates the location in WebSphere Commerce Developer and the corresponding location inside the WebSphere Commerce Enterprise Application:

    Development environment path EAR path
    workspace_dir/WC/xml/ xml/
    workspace_dir/WC/properties/ properties/

    If you customized a file in these directories, you must copy these assets to the directory you are using to build your deployment package. The structure under this directory must match the structure that you want inside the EAR, as indicated in the preceding table. For example, if you customized workspace_dir/WC/xml/messaging/user_template.xml, deploy it as xml/messaging/user_template.xml.

    Deleting assets from the EAR and including META-INF/ibm-partialapp-delete.props in the compressed file

    You can use either the WebSphere Application Server administrative console to add or update assets. However, deleting application files in a partial application update deployment scenario is accomplished by supplying a special metadata file that is called META-INF/ibm-partialapp-delete.props in the partial application compressed file. This file can exist at the application scope or at any embedded archive scope, including modules.
    Note: When you use META-INF/ibm-partialapp-delete.props to delete file assets from the EAR, you delete only the files. The file directory structure remains. Ensure that you manually delete the remaining folders and subfolders to remove these directories for your store from the EAR.

    For example, to delete files at the application level (outside of any module), add a file /META-INF/ibm-partialapp-delete.props in the partial application compressed file. Similarly, to delete files from a module (for example, MyWeb.war), add a file /MyWeb.war/META-INF/ibm-partialapp-delete.props in the partial application compressed file. To delete files from util.jar inside MyWeb.war, add a file /MyWeb.war/util.jar/META-INF/ ibm-partialapp-delete.props.

    To delete assets, you must first create and include the metadata file that is called META-INF/ibm-partialapp-delete.props in the partial application compressed file:
    1. Identify the files and the modules that contain the files that you want to delete.
    2. Create a temporary directory on your file system for the assets to delete, for example, C:\exportTemp\partialApp.
    3. For any EAR level files that you want to delete:
      1. Create a file that is called META-INF/ibm-partialapp-delete.props
      2. For each file you want to delete, add a line to that file that gives the relative path to the file, including the file name. For example, to delete WC_demo.ear/mydir/myfile.txt, put mydir/myfile.txt in the file on a line by itself.
    4. For each module that contains files you want to delete:
      1. Create a file that is called module/META-INF/ibm-partialapp-delete.props
      2. For each file you want to delete from that module, add a line to that file that gives the relative path (relative to module) to the file, including the file name. For example, to delete WC_demo.ear/Stores.war/mystore/file.txt, put mystore/file.txt in the file on a line by itself.
  4. Package the assets in a compressed file.

    After you collect all of the assets, you have a directory that has a structure underneath it that matches the production EAR file. The structure might be similar to the following example:

    C:\exportTemp\partialApp\
    C:\exportTemp\partialApp\WebSphereCommerceServerExtensionsLogic.jar
    C:\exportTemp\partialApp\Stores.war\myStore\index.jsp
    C:\exportTemp\partialApp\Stores.war\WEB-INF\lib\myUtilities.jar
    C:\exportTemp\partialApp\xml\messaging\user_template.xml

    The directory C:\exportTemp\partialApp\ represents the root of the production EAR file.

    Use a compressed file (ZIP) utility to create a compressed file of all of the files and directories under C:\exportTemp\partialApp\. This compressed file is used to update your WebSphere Commerce application.

    For more information about how to prepare the compressed file, see the section "Replace, add, or delete multiple files" in Preparing for application update settings topic.