By-reference sharing of Java binaries, XML schemas, and interface definitions in WebSphere Process Server (using Shared Libraries)

Technote (FAQ)


Question

How can I share my assets (Java™ binaries, XML schemas, and WSDL definitions) by-reference between Service Component Architecture (SCA) modules in the WebSphere Process Server runtime environment?

Cause

In WebSphere Integration Developer, the default sharing behavior for assets is share-by-copy. That is, at build time, SCA library projects containing shared SCA module assets become Java™ archive (.jar) files that are included in each SCA module application enterprise archive (.ear) file. Shared Java library artifacts are also included in each SCA module application .ear file.
Depending on the size of the libraries, number of assets, and number of deployed modules, the share-by-copy module can result in a large memory footprint. Sharing these assets by-reference can reduce this memory footprint.


Answer

The solution that is documented here can cause different behavior after the application is configured to use a WebSphere shared library (SL) instead of the default share-by-copy method.


The WebSphere shared library is a feature in the WebSphere Application Server product that allows you to add resources to the server class loader hierarchy. This solution describes how you can use the SCA library and Java projects with WebSphere shared libraries for by-reference sharing, such that only one instance of the library exists in the run time instead of a library instance that is packaged with each SCA module that references it.

For XML schema and interface definitions, the solution presented here for sharing these artifacts by-reference is simple, but it requires proper use of the target namespace and object names to ensure predictable results at run time:

    • You must constrain the use of target namespaces so that they do not exist in both the WebSphere shared library and the SCA modules that are scoped to the WebSphere Application Server shared library.
    • SCA modules cannot define, redefine, extend, or restrict artifacts of an existing namespace that is contained in a WebSphere shared library.
    • Assets that are contained in a WebSphere shared library cannot define, redefine, extend, or restrict artifacts that are contained in the SCA modules that are scoped to it.

For Java binaries, the server run-time environment relies on the inherent class-loading strategies in the Java virtual machine (JVM), and duplication of Java binaries can result in unpredictable behavior or a run-time exception. SCA modules exist in their own class loader and delegate to the class loader for the WebSphere shared library. Therefore, Java binaries that are included in the WebSphere shared library have preference in loading.

Follow the procedures in this document to override the default behavior of sharing Java binaries, XML schemas, and interface definitions by-copy, enabling them to be shared-by-reference using a WebSphere shared library.

Business Object Parsing Mode Considerations for Shared Java Code in V7.0.0 Fix Pack 3 and
beyond:


If you plan to share Java code across applications running with different business object (BO) parsing modes, you must be aware of incompatible differences between the two BO modes: Eager and Lazy.

In this case, the shared Java code should be BO mode-agnostic. That is, the code should be independent of behavior differences between the two BO parsing modes. If this separation cannot be achieved, then the shared Java code can use a published BOMode API to inquire the actual mode. Depending on the response (“Eager parsing” or “Lazy parsing”), a dedicated code path can be taken, dealing with BO mode-specific behavior.

Build the archive using WebSphere Integration Developer

Archives that are shared using WebSphere shared libraries are in the form of Java archive (JAR) files. You can create a library archive JAR file in one of several ways:

Option 1: Create an SCA library project
An SCA library project is used in WebSphere Integration Developer for creating and sharing XML schemas and interface definitions between SCA modules. WebSphere Integration Developer V7.0 introduces the Sharing Across Runtime Environments in the Dependency editor for a library to specify by-reference usage of the library:


    1. Create the SCA library in WebSphere Integration Developer by clicking File > New > Other > Business Integration > Library.

    2. (WebSphere Integration Developer v7.x only) Declare the SCA library as a Global library :

    1. In the Dependencies editor, mark the Sharing Across Runtime Environments as 'Global'.
    2. Right-click the library and click Properties.
    3. Click Business Integration > Business Object Parsing Mode and select the parsing mode that you want to use (WebSphere Integration Developer V7.0.0 Fix Pack 3 or later). If you select both, the library can be shared with applications that run in both BO modes.

    3. Author or import the XML schemas (XSD) and interface definitions (WSDL) into the SCA library.

    4. Create the SCA module and specify a dependency from the SCA module for the SCA library using the Dependencies editor.

    5. (WebSphere Integration Developer v6.x ONLY): Declare the SCA library as a by-reference dependency. In the Dependency editor, clear the Deploy with Module check box to specify share-by-reference use of the assets in the SCA library from the SCA module.

    6. Export the SCA library as a .jar file:

    • In WebSphere Integration Developer V6.x, click File > Export > Java > JAR file to create a JAR file to deploy to the run time using a WebSphere shared library.
    • In WebSphere Integration Developer V7.x, click to File > Export > Business Integration > Integration modules and libraries. On the Select the Content to Export page, click Files for server deployment and the library to create a JAR file to deploy to the run time using a WebSphere shared library.

Caution: Be aware of namespace conflicts. You must constrain the use of target namespaces so that they do not exist in both the WebSphere shared library and an SCA module. SCA modules cannot be allowed to define, redefine, extend, or restrict artifacts of an existing namespace that is scoped to or placed in a WebSphere shared library. Similarly, a WebSphere shared library cannot define, redefine, extend, or restrict artifacts that are scoped to an SCA module.

Option 2: Create a new Java project
An Eclipse Java project is used for creating and sharing Java binaries between SCA modules.
  1. In WebSphere Integration Developer, click File > New > Other > Java > Java Project.
  2. Create a Java project and author the Java code.
  3. Create the SCA module and declare the Java project as a by-reference dependency:
    1. In the Dependencies editor, add the Java project to specify a dependency from the SCA module for the Java project.
    2. Clear the Deploy with Module check box to specify share-by-reference use of the Java assets in the Java project from the SCA module.
  4. Export the Java project as a JAR file. Click File > Export > Java > JAR file to create a JAR file to deploy to the run time using a WebSphere shared library.
    Option 3: Use an existing Java project
    If you have existing Java projects, you can reuse the Java binaries between SCA modules. You do not create any Java source. You already have a JAR file that contains fine-grained Java services, interfaces, and beans that SCA modules can reuse.
    1. In WebSphere Integration Developer, click File > New > Other > Java > Java Project and create a Java project.
    2. Import the existing JAR file into the Java project using either of the following methods:
      • In WebSphere Integration Developer, click File > Import > General > File System, browse to the existing JAR file (containing Java binaries), and import it into the Java project.
      • Drag and drop the JAR file into the Java project.
    3. Right-click the Java project and click Properties > Java Build Path > Libraries > Add JARs and select the JAR file in the Java project.
    4. Create the SCA module and declare the Java project as a by-reference dependency:
      1. In the Dependencies editor, add the Java project to specify a dependency from the SCA module for the Java project.
      2. Clear the Deploy with Module check box to specify share-by-reference use of the Java assets in the Java project from the SCA module.

    Install and configure the library in WebSphere Process Server
    This section includes procedures for installing and configuring WebSphere shared libraries in a WebSphere Application Server Network Deployment environment, a Unit Test Environment (UTE), and a stand-alone server environment.

    Network Deployment environment
      Deployment Manager
      You must configure the deployment manager to support the WebSphere shared library dependency during application deployment:
      1. In the WebSphere Process Server installation, on the deployment manager, and across all the nodes that contain WebSphere Process Server installations, copy the archive JAR files that contain the assets that you exported from WebSphere Integration Developer to the <WPS_HOME>/lib/ext directory,
      2. Install the SCA modules to the appropriate run-time target, see note2 below
      3. For each cluster in which the application will run, create the module-libraries directory on the deployment manager for the archives and copy the archive JAR file that contains the assets that you exported from WebSphere Integration Developer to the <WPS_HOME>/profiles/<dmgr_profile>/config/cells/<cell_name>/clusters/<cluster_name>/module-libraries directory. Libraries that are copied to this directory are replicated to other nodes in the cell.
      4. In the administrative console, click Environment > Shared Libraries and configure the run time to include a WebSphere shared library named ModuleSharedLibraries with a class path set to the WebSphere variable ${MODULE_LIB_PATH}.
      5. Restart the deployment manager to clear the class cache and index the newly added JAR files for the class path.
      6. Configure the shared libraries on Network Deployment managed clusters, listed in the following sections.
      7. Stop the deployment manager.
      8. Delete the WebSphere shared library from the <WPS_HOME>/lib/ext directory.
      9. Start the deployment manager to register the changes in the class path.


      Note: Different set of shared libraries are potentially 'incompatible' with each other. For example, this scenario might occurs if you have different implementations for the same Java class in different shared libraries. If that is the case, you must remove these archives from the deployment manager run time after deploying and configuring the applications to avoid problems. Each cluster or server must be configured in isolation. This note applies to step 8 for UTE as well.

      IMPORTANT: It is mandatory to have the files in lib/ext directory each time applications that use it are being installed. This requirement exists because at that time the shared libraries, even if they were not previously configured, are not visible to the application. Every time you install an application, even an existing one that has the shared library configured, you need to have the shared library in the lib/ext directory. You need to use this directory even if the shared library is previously configured and used by an already deployed module. After application installation, this library must be removed from the lib/ext directory and the server restarted to avoid future problems regarding duplicate libraries.

      Network Deployment managed clusters
      1. For each cluster in which the application will run, in the administrative console, navigate to Environment > WebSphere Variables. Select the scope as Node and configure the run time to have a WebSphere variable named MODULE_LIB_PATH with a value of ${USER_INSTALL_ROOT}/config/cells/<cell_name>/clusters/<cluster_name>/module-libraries. For example, if a node has two clusters, then create two WebSphere variables with unique names and value as the corresponding location on the cluster.
      2. Add the shared library either to the server or to the applications. If the shared library contains business objects, add the shared library to the applications so that the Failed Event Manager can show business object details.
        1. Add the shared library to the server.
          • For each application server in the cluster in which the application will run, in the administrative console, click Servers > Application Server > server_name> Java and Process Management > Class loader. Use a new class loader to configure the class path to include the class loader that contains the ModuleSharedLibraries shared library.
          • For each application server in the cluster in which the application will run, in the administrative console, click Servers > Application Server > server_name > Java and Process Management > Class loader > class_loader_name > Shared library references. Select ModuleSharedLibraries from list to configure the run-time class path to include the library.
        2. Add the shared library reference to the applications. While installing the applications that depend on the library, choose the option to map modules to the shared library. You might have to choose detailed steps to go to this mapping step. Alternately, if you already have applications installed, you can update them to use a shared library by clicking Enterprise Applications> application_name > Shared library reference > Shared library mapping in the administrative console
      3. In the administration console, click System administration > Nodes and perform a full resynchronization on all nodes (except the deployment manager).
      4. Restart the cluster to restart all cluster member servers.

        Network Deployment managed stand-alone servers
        1. For each stand-alone server in which the application will run, create the module-libraries directory on the deployment manager for the libraries and copy the archive JAR file containing the library content that was exported from WebSphere Integration Developer to the <WPS_HOME>/profiles/<dmgr_profile>/config/cells/<cell_name>/nodes/<node_name>/servers/<server_name>/module-libraries directory.
          Libraries that are copied to this directory are replicated to other nodes in the cell.
        2. For each stand-alone server where an application using this WebSphere shared library runs, in the administrative console, navigate to Environment > WebSphere Variables. Set the scope as server and configure the run time to have a WebSphere variable named MODULE_LIB_PATH with a value of ${USER_INSTALL_ROOT}/config/cells/cell_name/nodes/node_name/servers/server_name/module-libraries.
        3. Add the shared library either to the server or to the applications. If the shared library contains business objects, add the shared library to the applications so that the Failed Event Manager can show business object details.
          1. Add the shared library to the server
            • For each application server in the cluster in which the application will run, in the administrative console, click Servers > Application Server > server_name > Java and Process Management > Class loader. Use a new class loader to configure the class path to include the class loader that contains the ModuleSharedLibraries shared library.
            • For each application server in the cluster in which the application will run, in the administrative console, click Servers > Application Server > server_name > Java and Process Management > Class loader > class_loader_name > Shared library references. Select ModuleSharedLibraries from list to configure the class path to include the library.
          2. Add the shared library reference to the applications. While installing the applications that depend on the library, choose the option to map modules to the shared library. You might have to choose detailed steps to go to this mapping step. Alternately, if you already have applications installed, you can update them to use the shared library by clicking Enterprise Applications> application_name > Shared library reference > Shared library mapping in the administrative console.
        4. In the administration console, click System administration > Nodes and perform a full resynchronization on all nodes (except the deployment manager).
        5. Restart the stand-alone server.

      UTE and servers in a stand-alone profile

        1. In the WebSphere Process Server run-time installation, copy the archive JAR files that contain the assets that you exported from WebSphere Integration Developer to one of the following directories (the choice of directory depend on which server type you use):
          • Stand-alone: <WPS_HOME>/lib/ext
          • UTE: <WID_HOME>/runtimes/bi_<WPS_VERSION>/lib/ext
        2. Restart the stand-alone server to make the class cache cleared and the newly added classes and schemas can be indexed by the class loader.
        3. Install all the applications.
        4. In the WebSphere Process Server run-time installation location for the UTE or stand-alone server profile, create the directory for the libraries and copy the archive JAR file that contains the library content to one of the following directories (the choice of directory depends on which server type you use):
          • Stand-alone: <WPS_HOME>/profiles/<server_profile>/module-libraries
          • UTE: <WID_HOME>/pf/<server_profile>/module-libraries
        5. In the administrative console, click Environment > WebSphere Variables to configure the run time to have a WebSphere variable named MODULE_LIB_PATH with a value of ${USER_INSTALL_ROOT}/module-libraries.
        6. In the administrative console, configure the run time to have a shared library named ModuleSharedLibraries with class path set to the ${MODULE_LIB_PATH} WebSphere variable.
        7. Add the shared library either to the server or to the applications. If the shared library contains business objects, add the shared library to the applications so that the Failed Event Manager can show business object details.
          1. Add the shared library to the server.
            • For the standalone server in which the application will run, in the administrative console, navigate to Servers > Application Server > server_name > Java and Process Management > Class loader and select new class loader to configure the run-time class path to include a class loader that contains the ModuleSharedLibraries shared library.
            • For the standalone server in which the application will run, in the administrative console, navigate to Servers > Application Server > [server_name] > Java and Process Management > Class loader > class_loader > Shared library references and select ModuleSharedLibraries from list to configure the run-time class path to include the library.
            • Install the applications.
          2. Add the shared library reference to the applications. While installing the applications that depend on the library, choose the option to map modules to the shared library. You might have to choose detailed steps to go to this mapping step. Alternately, if you already have applications installed, you can update them to use the shared library by clicking Enterprise Applications> application_name > Shared library reference > Shared library mapping in the administrative console.
        8. Stop the application server.
        9. Remove the WebSphere shared library from the <WPS_HOME>/lib/ext directory.
        10. Start the application server to register the changes to the class path.

        IMPORTANT: Mediation Subflows are normally used over several mediations. Shared libraries do not support Subflows containing any Business Object Map (BOMap), If a BOMap needs to be shared across mediations, then it needs to be implemented using an SCA library as explained previously.


      WebSphere Process Server client installations
      For client applications such as Business Process Choreographer Explorer, you must install the WebSphere shared libraries on the servers and clusters that host these applications. If you do not use this approach, the client applications cannot locate the WebSphere shared library content. Follow the same previously listed instructions to install WebSphere shared libraries on each server or cluster that acts as a WebSphere Process Server client application. You do not have to install the remote applications on the client with which the client will communicate. You only need to install the remote application WebSphere shared libraries.

      IMPORTANT: Mediation Subflows are normally used over several mediations. Shared libraries do not support Subflows that contain any Business Object Map (BOMap), If you need to share a BOMap across mediations, then you need to implement it using an SCA library as explained previously. See CWLAS0002E: Configuring a shared library to support a business object map as a possible work around for this restriction.


      Related APARs

      Cross reference information
      Segment Product Component Platform Version Edition
      Business Integration WebSphere Integration Developer Service Component Architecture (SCA) 7.0, 6.2, 6.1
      Business Integration IBM Business Process Manager Advanced Service Component Architecture (SCA) AIX, Linux, Solaris, Windows 8.5, 8.0.1, 8.0, 7.5.1, 7.5

      Product Alias/Synonym

      BPM

      Rate this page:

      (0 users)Average rating

      Add comments

      Document information


      More support for:

      WebSphere Process Server
      Service Component Architecture

      Software version:

      6.1.2, 6.2, 7.0

      Operating system(s):

      AIX, HP-UX, Linux, Solaris, Windows, i5/OS

      Reference #:

      1322617

      Modified date:

      2013-10-14

      Translate my page

      Machine Translation

      Content navigation