|
Abstract |
Best Practices for using common application files within
IBM® WebSphere® Application Server Version 5.0 and Version 5.1 |
|
|
|
|
Content |
Table of contents:
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.
Back to top
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.
Back to top
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?
- If NO, will this "utility" class or JAR be shared by more than
one enterprise application?
- If YES, will visibility to this “utility” class or JAR cause
any other applications installed to the same server to malfunction?
- If YES, see Using an
application associated shared library.
- If NO, see Using a
server associated shared library.
- If NO, will multiple modules within the application need this
"utility" JAR?
- If YES, see Placing
"utility" classes or JARs at the root of the EAR file.
- If NO, see Placing
"utility" classes or JARs within the module.
- If YES, see Keeping
different versions of a “utility” JAR.
Examples using the decision tree
- 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.
- 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.
Back to top
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.
Back to top
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:
- Create a shared library:
- Expand Environment and select Shared Libraries.
- Make sure the scope is set appropriately and create a new shared
library.
- Click New and fill out the correct information including the
Name and appropriate Classpath. Click Apply.
- Map the Shared Library to an Application Server:
- Expand Servers and select Application Servers.
- Select the Application Server you want to associate the library to,
and then select Classloader under the Additional Properties.
- Click New.
- Select the appropriate Classloader Mode – This is
Parent_First by default as are all the other classloader modes in
the WebSphere Application Server V5 product. If you are overriding files
that might appear higher in the WebSphere hierarchy, then select
Parent_Last as described in the section Overriding a WebSphere
Application Server included file.
- Click OK.
- At this point, the classloader has been created. Click on the new
classloader that has been created.
- Click on Libraries under Additional Properties.
- Click Add.
- Under the drop-down, select the newly created shared library.
- 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.
Back to top
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:
- Create a shared library:
- Expand Environment and select Shared Libraries.
- Make sure the scope is set appropriately and create a new shared
library.
- Click New and fill out the correct information including the
Name and appropriate Classpath.
- Associate the newly created shared library to the enterprise
application:
- Expand Applications and select Enterprise Applications.
- Select the Enterprise Application you want to modify and then select
Libraries in the Additional Properties.
- Click Add and select the newly created library. Click
OK.
- 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
Back to top
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 the
Application Assembly Tool (AAT) (V5.0 only), 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.
Back to top
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:
- 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.
Back to top
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:
- Select the Enterprise Application.
- Change the Classloader Mode to PARENT_LAST.
- Click Apply.
- 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:
- Select the Application Server the library is associated to.
- Select Classloader under Additional Properties.
- Select the classloader that the shared library is associated to.
- Change the Classloader Mode to PARENT_LAST.
- Click Apply.
- 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:
- Select the Enterprise Application.
- Change the Classloader Mode to PARENT_LAST.
- Click Apply.
- 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:
- Select the Enterprise Application.
- Change the Classloader Mode to PARENT_LAST.
- Click Apply.
- 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:
- Select the Enterprise Application.
- Under Related Items select Web Modules.
- Select the Web module the file has been added to.
- Change the Classloader Mode to PARENT_LAST.
- Save the configuration and restart the application.
Back to top
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.
Back to top
|
|
|
|
|
Cross Reference information |
Segment |
Product |
Component |
Platform |
Version |
Edition |
Application Servers |
Runtimes for Java Technology |
Java SDK |
|
|
|
|
|
|