IBM Support

Best Practice for using common application files

White Papers


Abstract

Best Practices for using common application files within IBM WebSphere Application Server Version 7.0, 8.0, 8.5, and 9.0

Content

Table of contents:

Background
Where NOT to place "utility" files
Determining where to place your "utility" files
Keeping different versions of a "utility" JAR
Using a server associated shared library
Using an application associated shared library
Placing "utility" classes or JARs at the root of the EAR file
Placing "utility" classes or JARs within the module
Overriding a WebSphere Application Server included file
Conclusion



Background
IBM WebSphere Application Server administrators and developers often need to know where to put “utility” classes or Java™ archive (JAR) files so that they can be utilized by their application. This document is intended to clarify this issue. Every application and configuration is unique and your implementation might vary. This is a culmination of multiple experiences with client’s configurations and is a best practice document.

Before beginning, here are a couple assumptions. First, assume that the default classloader settings are being used in the WebSphere Application Server environment. These include the following:
  • Application Classloader Policy = Multiple
  • Application Classloader Mode = PARENT_FIRST
  • War Classloader Policy = Module
  • War Classloader Mode = PARENT_FIRST

These can be changed for various reasons but normally the desired behavior can be reached with the default settings. For this reason, these classloader settings are not described in this document. See the appropriate information for your release for additional information on the classloader settings.

In addition, the definition of a “utility” class or JAR file will need to be explained. To be a "utility" JAR or class, the file cannot depend on any application that might be using it. If this is untrue, it cannot be considered a "utility" class or JAR and will greatly alter how it can be located within the WebSphere Application Server environment. It is assumed that each “utility” class or JAR will not depend on each other as this can also introduce complications. How to use a different version of a file for an application than one that is included in the WebSphere Application Server environment will be explained. This is often needed as WebSphere Application Server uses Xerces, Xalan, and other common components that applications might need but require a different version.

Note: If a .jar file contains a Java Extension class (javax.*.class) file which is also provided by WebSphere, then it must not be included in your Shared Library or application, or else a ClassCastException or similar error will occur. If the javax.*.class is NOT provided by WebSphere Application Server, then feel free to use that .jar in your application or Shared Library.






Where NOT to place “utility” files
Before describing where you should place these types of files, the following will quickly explain where NOT to place them. This might cause many of you to pause as you might be using these locations or classpaths in present environments. This is a best practice document and only includes the recommended implementations.

Do NOT add "utility" JARs or classes to the following directories or classpath as this might alter the WebSphere Application Server runtime environment and cause unexpected results:
  • install_root/lib
  • install_root/lib/ext*
  • install_root/java (including any subdirectories)

Note: install_root can refer to a base or network deployment installation.
*This is the recommended location for custom registry code. This is needed as the security component must have visibility to this code during server startup

Using the JVM classpath is also not a preferred way to add “utility” JARs to a WebSphere Application Server environment. It can cause the overwriting of WebSphere Application Server classes and be detrimental to the overall functionality.






Determining where to place your “utility” files
There are a few questions that will help determine where “utility” files should be located. Consider your expected future configurations as changes will be minimized. You might not have more than one enterprise application using a specific “utility” file at this point, but if this is in your future plans take it into consideration when going through the following questions. The initial question is important because often multiple teams use a configuration. Each team might need to use files that are common but they need to be changed for their specific implementation. This is why multiple copies might be required. If you do need to override a file which is included with WebSphere Application Server, step through the following decision tree, then go to Overriding a WebSphere Application Server included file.

Will you need to deploy different versions of this “utility” JAR?
  1. If NO, will this "utility" class or JAR be shared by more than one enterprise application?
    1. If YES, will visibility to this “utility” class or JAR cause any other applications installed to the same server to malfunction?
      1. If YES, see Using an application associated shared library.
      2. If NO, see Using a server associated shared library.

    2. If NO, will multiple modules within the application need this "utility" JAR?
      1. If YES, see Placing "utility" classes or JARs at the root of the EAR file.
      2. If NO, see Placing "utility" classes or JARs within the module.

  2. If YES, see Keeping different versions of a “utility” JAR.

Examples using the decision tree
  1. You have a "utility" JAR called common.jar that was supplied by a third-party and is shared by multiple applications. The only problem is that you need to change a file within this JAR for your application but the other applications need to use the original.

    DECISION TREE RESPONSES

    Will you need to keep different versions of this “utility” JAR? ANSWER: YES

    Go to the section titled, Keeping different versions of a “utility” JAR, and create a shared library for the original common.jar to be used by the other applications and a shared library containing the updated common.jar to be used by your application. Then it is as simple as confirming the appropriate shared library is associated with the correct application.

  2. You have a "utility" JAR called common.jar that is needed by your Web module currently. However, when an Enterprise JavaBeans™ module is added later this year it will also need to use it. Therefore, you will assume it is already in place when going through the decision tree.

    DECISION TREE RESPONSES

    Will you need to keep different versions of this “utility” JAR? ANSWER: NO

    If NO, will this “utility” JAR be shared by more than one enterprise application? ANSWER: NO, it will only be used within one application.

    If NO, will multiple modules within the application need this “utility” JAR? ANSWER: YES, both the Enterprise JavaBeans and Web modules will need to use it.

    Go to the section titled, Placing “utility” classes or JARs at the root of the EAR file, to set up the application.







Keeping different versions of a “utility” JAR
If you need to keep different versions of a "utility" JAR, using application associated shared libraries is a simple solution. You need to create a shared library for each unique version of the “utility” file, see Using an application associated shared library below. Then associate the shared library to the appropriate application. This will allow you to have only one copy of each unique “utility” JAR and easily allow visibility to it by the needed applications.






Using a server associated shared library
Using a server associated shared library allows all applications running on that server to have visibility to the "utility" classes or JARs set up in it. The shared library can be associated with multiple application servers.

Using the Administration Console you can set up a shared library with the following steps:
  1. Create a shared library:
    1. Expand Environment and select Shared Libraries.

    2. Make sure the scope is set appropriately and create a new shared library.


    3. Click New and fill out the correct information including the Name and appropriate Classpath. Click Apply.


  2. Map the Shared Library to an Application Server:
    1. Expand Servers and select Application Servers.

    2. Select the Application Server you want to associate the library to, and then select Classloader under the Additional Properties.


    3. Click New.

    4. Select the appropriate Classloader Mode – The classloader mode "Classes loaded with parent loader first" is set by default. If you are overriding files that might appear higher in the WebSphere hierarchy, then select Classes loaded with local class loader first (parent_Last) as described in the section Overriding a WebSphere Application Server included file.


    5. Click OK.

    6. At this point, the classloader has been created. Click on the new classloader that has been created.


    7. Click on Shared library references under Additional Properties.


    8. Click Add.


    9. Under the drop-down, select the newly created shared library.


    10. The shared library is now associated with the newly created WebSphere Application Server classloader. Click OK, save the configuration, and then restart the server for the change to take effect.






Using an application associated shared library
An application associated shared library allows only specific applications to utilize its contents. The shared library can be associated with multiple applications.

Using the Administration Console you can set up a shared library with the following steps:
  1. Create a shared library:
    1. Expand Environment and select Shared Libraries.

    2. Make sure the scope is set appropriately and create a new shared library.


    3. Click New and fill out the correct information including the Name and appropriate Classpath.


  2. Associate the newly created shared library to the enterprise application:
    1. Expand Applications and select Enterprise Applications.

    2. Select the Enterprise Application you want to modify and then select Shared library references in the References. Select the EAR or Web module checkbox, then click on Reference shared libraries. In this example, the shared library is associated with the web module. If you want to associate the shared library with the EAR, select the first checkbox (DefaultApplication.ear) instead.


    c. Select the newly created library and click on the right arrow to add the shared library to Selected textbox. Click OK.


    1. The shared library is now associated with the application. Click OK, save the configuration, and then restart the application for the change to take effect






Placing "utility" classes or JARs at the root of the EAR file
The root of the EAR file can be used to place “utility” classes or JARs that any module of the enterprise archive can use. Individual "utility" classes should be included in a JAR file. A "utility" JAR can be placed at the root of the EAR file using multiple utilities including IBM Application Server Toolkit for WebSphere Application Server (Toolkit), WebSphere Studio Application Developer, or with another archive reader.

The JAR then needs to be added to the classpath for any module within the EAR that needs access to it. This can also be done with the utilities mentioned above. It will subsequently update the MANIFEST.MF file under the META-INF directory for the module being updated.

Example MANIFEST.MF file contents:

Manifest-Version:  1.0
Created-By:  1.3.0 (IBM Corporation)
Class-Path:  Common.jar  ./mypath/common2.jar

In the preceding example, Common.jar is at the root of the EAR file and has no path. The common2.jar resides within a folder at the root of the EAR. BE CAREFUL when manually editing this file as there are line length constraints. Use of an editing tool is recommended.






Placing "utility" classes or JARs within the module
Even if classes and JARs can be considered "utility" by the description in this article, if they are not needed outside the visibility of an individual module they should be included within it. Depending on the module, the classes or JARs should be included in their default location.

For example:
  • Enterprise JavaBean Module:

  • <EAR File>/<EJB jar>/

  • WAR Module:

  • <EAR File>/<WAR File>/WEB-INF/lib/

No additional classpaths will need to be set as long as that module is the only one that needs visibility to it.






Overriding a WebSphere Application Server included file
Now that you have placed your utility JAR in the correct location by using the decision tree discussed earlier in this document, you might need to alter the classloader settings to have your application use a different version of a “utility” file is included with WebSphere Application Server. This can be done by changing the delegation mode of the classloader where the “utility” file has been added. There are two possible delegation modes for each classloader:
  • PARENT_FIRST causes the class loader to delegate the loading of classes to its parent class loader before attempting to load the class from its local classpath.

  • PARENT_LAST causes the class loader to attempt to load classes from its local classpath before delegating the class loading to its parent.

PARENT_FIRST is the default for all classloaders within the WebSphere Application Server environment. These can be changed for most classloaders by altering the classloader mode. For all the locations specified in this document, the classloader mode can be changed.

The following steps you through changing the classloader mode for each location described in this document. Refer to the description for the location where you have placed the “utility” class or JAR.
  • Using an application associated shared library
    With an application associated shared library, the files are loaded along with the Enterprise JavaBeans and dependency JARs within the application. In the administration console do the following:
    1. Select the Enterprise Application.
    2. Change the Classloader Mode to PARENT_LAST.
    3. Click Apply.
    4. Save the configuration and restart the application.

  • Using a server associated shared library
    With a server associated shared library, the “utility” class or JAR will loaded within its own classloader created during creation of the shared library. In the administration console do the following:
    1. Select the Application Server the library is associated to.
    2. Select Classloader under Additional Properties.
    3. Select the classloader that the shared library is associated to.
    4. Change the Classloader Mode to PARENT_LAST.
    5. Click Apply.
    6. Save the configuration and restart the application server.

  • Placing "utility" classes or JARs at the root of the EAR file
    With the “utility” class or JARs at the root of the EAR, the files are loaded along with the Enterprise JavaBeans and dependency JARs within the application. In the administration console do the following:
    1. Select the Enterprise Application.
    2. Change the Classloader Mode to PARENT_LAST.
    3. Click Apply.
    4. Save the configuration and restart the application.

  • Placing "utility" classes or JARs within the module
    With the “utility” class or JARs within the module, they will be loaded along with other files within the same module. What type of module you are using will determine which classloader mode to alter.

    If the “utility” class or JAR is added to an Enterprise JavaBeans module in the console, do the following:
    1. Select the Enterprise Application.
    2. Change the Classloader Mode to PARENT_LAST.
    3. Click Apply.
    4. Save the configuration and restart the application.

    If the “utility” class or JAR is added to a Web module in the console do the following:
    1. Select the Enterprise Application.
    2. Under Related Items select Web Modules.
    3. Select the Web module the file has been added to.
    4. Change the Classloader Mode to PARENT_LAST.
    5. Save the configuration and restart the application.






Conclusion
Utility JARs are very useful. They can increase reusability, reduce reprogramming as well as simplify the complexity of an application environment. Knowing where to place these files can be very important; if they are not positioned wisely it can greatly alter the expected behavior.





[{"Product":{"code":"SSEQTP","label":"WebSphere Application Server"},"Business Unit":{"code":"BU053","label":"Cloud & Data Platform"},"Component":"--","Platform":[{"code":"PF002","label":"AIX"},{"code":"PF010","label":"HP-UX"},{"code":"PF016","label":"Linux"},{"code":"PF027","label":"Solaris"},{"code":"PF033","label":"Windows"}],"Version":"9.0;8.5.5;8.5;8.0;7.0","Edition":"Base;Network Deployment","Line of Business":{"code":"LOB45","label":"Automation"}}]

Document Information

Modified date:
17 June 2018

UID

swg27006159