![]() ![]() ![]() ![]() ![]() ![]() ![]() |
The following sections describe how to share components and classes among applications using shared Java EE libraries and optional packages:
The shared Java EE library feature in WebLogic Server provides an easy way to share one or more different types of Java EE modules among multiple Enterprise Applications. A shared Java EE library is a single module or collection of modules that is registered with the Java EE application container upon deployment. A shared Java EE library can be any of the following:
BEA recommends that you package a shared Java EE library into its appropriate archive file (EAR, JAR, or WAR). However, for development purposes, you may choose to deploy shared Java EE libraries as exploded archive directories to facilitate repeated updates and redeployments.
After the shared Java EE library has been registered, you can deploy Enterprise Applications that reference the library. Each referencing application receives a reference to the required library on deployment, and can use the modules that make up the library as if they were packaged as part of the referencing application itself. The library classes are added to the classpath of the referencing application, and the referencing application’s deployment descriptors are merged (in memory) with those of the modules that make up the shared Java EE library.
In general, this topic discusses shared Java EE libraries that can be referenced only by Enterprise Applications. You can also create libraries that can be referenced only by another Web application. The functionality is very similar to application libraries, although the method of referencing them is slightly different. See Web Application Shared Java EE Library Information for details.
Note: | WebLogic Server also provides a simple way to add one or more JAR files to the WebLogic Server System classpath, using the lib subdirectory of the domain directory. See Adding JARs to the System Classpath. |
WebLogic Server supports optional packages as described in the Java EE 5.0 Specification, Section 8.2 Optional Package Support, with versioning described in Optional Package Versioning. Optional packages provide similar functionality to Java EE libraries, allowing you to easily share a single JAR file among multiple applications. As with Java EE libraries, optional packages must first be registered with WebLogic Server by deploy the associated JAR file as an optional package. After registering the package, you can deploy Java EE modules that reference the package in their manifest files.
Optional packages differ from Java EE libraries because optional packages can be referenced from any Java EE module (EAR, JAR, WAR, or RAR archive) or exploded archive directory. Java EE libraries can be referenced only from a valid Enterprise Application.
For example, third-party Web Application Framework classes needed by multiple Web Applications can be packaged and deployed in a single JAR file, and referenced by multiple Web Application modules in the domain. Optional packages, rather than Java EE libraries, are used in this case, because the individual Web Application modules must reference the shared JAR file. (With Java EE libraries, only a complete Enterprise Application can reference the library).
Note: | BEA documentation and WebLogic Server utilities use the term library to refer to both Java EE libraries and optional packages. Optional packages are called out only when necessary. |
The Java EE platform provides several mechanisms for applications to use optional packages and shared libraries. Libraries can be bundled with an application or may be installed separately for use by any application. An EAR file may contain a directory that contains libraries packaged in JAR files. The library-directory
element of the EAR file’s deployment descriptor contains the name of this directory. If a library-directory
element isn’t specified, or if the EAR file does not contain a deployment descriptor, the directory named lib is used. An empty library-directory
element may be used to specify that there is no library directory. All files in this directory (but not in subdirectories) with a .jar
extension must be made available to all components packaged in the EAR file, including application clients. These libraries may reference other libraries, either bundled with the application or installed separately.
This feature is similar to the APP-INF/lib
feature supported in WebLogic Server. If both APP-INF/lib
and library-directory
exist, then the jars in the library-directory
would take precedence; that is, they would be placed before the APP-INF/lib
jar files in the classpath. For more information on APP-INF/lib
, see Resolving Class References Between Modules and Applications and Organizing Shared Classes in a Split Development Directory.
WebLogic Server supports versioning of shared Java EE libraries, so that referencing applications can specify a required minimum version of the library to use, or an exact, required version. WebLogic Server supports two levels of versioning for shared Java EE libraries, as described in the Optional Package Versioning document:
As a best practice, BEA recommends that you always include version information (an implementation version, or both an implementation and specification version) when creating shared Java EE libraries. Creating and updating version information as you develop shared components allows you to deploy multiple versions of those components simultaneously for testing. If you include no version information, or fail to increment the version string, then you must undeploy existing libraries before you can deploy the newer one. See Deploying Shared Java EE Libraries and Dependent Applications.
Versioning information in the referencing application determines the library and package version requirements for that application. Different applications can require different versions of a given library or package. For example, a production application may require a specific version of a library, because only that library has been fully approved for production use. An internal application may be configured to always use a minimum version of the same library. Applications that require no specific version can be configured to use the latest version of the library. Referencing Shared Java EE Libraries in an Enterprise Application.
Optional packages and shared Java EE libraries have the following features in common:
Optional packages differ from shared Java EE Libraries in the following basic ways:
META-INF/MANIFEST.MF
), whereas only Enterprise Applications and Web applications can reference a shared Java EE library (using weblogic-application.xml
or weblogic.xml
)In general, use shared Java EE libraries when you need to share one or more EJB, Web Application or Enterprise Application modules among different Enterprise Applications. Use optional packages when you need to share one or more classes (packaged in a JAR file) among different Java EE modules.
Plain JAR files can be shared either as libraries or optional packages. Use optional packages if you want to:
Use shared Java EE libraries to share a plain JAR file if you only need to reference the JAR file from one or more Enterprise Applications, and you do not need to maintain strict compliance with the Java EE specification.
Note: | BEA documentation and WebLogic Server utilities use the term shared Java EE library to refer to both libraries and optional packages. Optional packages are called out only when necessary. |
For information about deploying and managing shared Java EE libraries, optional packages, and referencing applications from the Administrator’s perspective, see Deploying Shared Java EE Libraries and Dependent Applications in Deploying Applications to WebLogic Server.
To create a new shared Java EE library that you can share with multiple applications:
See Assembling Shared Java EE Library Files.
See Assembling Optional Package Class Files.
MANIFEST.MF
file for the shared Java EE library to specify the name and version string information.See Editing Manifest Attributes for Shared Java EE Libraries.
See Packaging Shared Java EE Libraries for Distribution and Deployment.
The following types of Java EE modules can be deployed as a shared Java EE library:
Shared Java EE libraries have the following restrictions:
BEA recommends packaging shared Java EE libraries as Enterprise Applications, rather than as standalone Java EE modules. This is because the URI of a standalone module is derived from the deployment name, which can change depending on how the module is deployed. By default, WebLogic Server uses the deployment archive filename or exploded archive directory name as the deployment name. If you redeploy a standalone shared Java EE library from a different file or location, the deployment name and URI also change, and referencing applications that use the wrong URI cannot access the deployed library.
If you choose to deploy a shared Java EE library as a standalone Java EE module, always specify a known deployment name during deployment and use that name as the URI in referencing applications.
Any set of classes can be organized into an optional package file. The collection of shared classes will eventually be packaged into a standard JAR archive. However, because you will need to edit the manifest file for the JAR, begin by assembling all class files into a working directory:
mkdir /apps/myOptPkg
mkdir -p /apps/myOptPkg/org/myorg/myProduct
cp /build/classes/myOptPkg/org/myOrg/myProduct/*.class /apps/myOptPkg/org/myOrg/myProduct
cd /apps/myOptPkg
jar xvf /build/libraries/myLib.jar
The name and version information for a shared Java EE library are specified in the META-INF/MANIFEST.MF
file. Table 9-1 describes the valid shared Java EE library manifest attributes.
An optional string value that identifies the name of the shared Java EE library. Referencing applications must use the exact
Extension-Name value to use the library.
As a best practice, always specify an
Extension-Name value for each library. If you do not specify an extension name, one is derived from the deployment name of the library. Default deployment names are different for archive and exploded archive deployments, and they can be set to arbitrary values in the deployment command.
|
|
An optional String value that defines the specification version of the shared Java EE library. Referencing applications can optionally specify a required Specification-Version for a library; if the exact specification version is not available, deployment of the referencing application fails.
Major/minor version format, with version and revision numbers separated by periods (such as “9.0.1.1”)
Referencing applications can be configured to require either an exact version of the shared Java EE library, a minimum version, or the latest available version.
The specification version for a shared Java EE library can also be set at the command-line when deploying the library, with some restrictions. See Deploying Shared Java EE Libraries and Dependent Applications.
|
|
An optional String value that defines the code implementation version of the shared Java EE library. You can provide an Implementation-Version only if you have also defined a Specification-Version.
If you use the major/minor version format, referencing applications can be configured to require either an exact version of the shared Java EE library, a minimum version, or the latest available version. If you use the text format, referencing applications must specify the exact version of the library.
The implementation version for a shared Java EE library can also be set at the command-line when deploying the library, with some restrictions. See Deploying Shared Java EE Libraries and Dependent Applications.
|
To specify attributes in a manifest file:
cd /apps/myLibrary
mkdir META-INF
emacs META-INF/MANIFEST.MF
For the optional package example, use:
cd /apps/myOptPkg
mkdir META-INF
emacs META-INF/MANIFEST.MF
Extension-Name: myExtension
Applications that reference the library must specify the exact Extension-Name
in order to use the shared files.
Extension-Name: myExtension
Specification-Version: 2.0
Implementation-Version: 9.0.0
Using the major/minor format for the version identifiers provides the most flexibility when referencing the library from another application (see Table )
Note: | Although you can optionally specify the Specification-Version and Implementation-Version at the command-line during deployment, BEA recommends that you include these strings in the MANIFEST.MF file. Including version strings in the manifest ensures that you can deploy new versions of the library alongside older versions. See Deploying Shared Java EE Libraries and Dependent Applications. |
If you are delivering the shared Java EE Library or optional package for deployment by an Administrator, package the deployment files into an archive file (an .EAR
file or standalone module archive file for shared Java EE libraries, or a simple .JAR
file for optional packages) for distribution. See Deploying and Packaging from a Split Development Directory.
Because a shared Java EE library is packaged as a standard Java EE application or standalone module, you may also choose to export a library’s deployment configuration to a deployment plan, as described in Deploying Applications to WebLogic Server. Optional package .JAR
files contain no deployment descriptors and cannot be exported.
For development purposes, you may choose to deploy libraries as exploded archive directories to facilitate repeated updates and redeployments.
A Java EE application can reference a registered shared Java EE library using entries in the application’s weblogic-application.xml
deployment descriptor. Table 9-2 describes the XML elements that define a library reference.
A required string value that specifies the name of the shared Java EE library to use.
library-name must exactly match the value of the Extension-Name attribute in the library’s manifest file. (See
Table 9-4.)
|
|
An optional String value that defines the required specification version of the shared Java EE library. If this element is not set, the application uses a matching library with the highest specification version. If you specify a string value using major/minor version format, the application uses a matching library with the highest specification version that is not below the configured value. If all available libraries are below the configured
specification-version , the application cannot be deployed. The required version can be further constrained by using the exact-match element, described below.
If you specify a String value that does not use major/minor versioning conventions (for example, 9.2BETA) the application requires a shared Java EE library having the exact same string value in the
Specification-Version attribute in the library’s manifest file. (See
Table 9-4.)
|
|
An optional String value that specifies the required implementation version of the shared Java EE library. If this element is not set, the application uses a matching library with the highest implementation version. If you specify a string value using major/minor version format, the application uses a matching library with the highest implementation version that is not below the configured value. If all available libraries are below the configured
implementation-version , the application cannot be deployed. The required implementation version can be further constrained by using the exact-match element, described below.
If you specify a String value that does not use major/minor versioning conventions (for example, 9.2BETA) the application requires a shared Java EE library having the exact same string value in the
Implementation-Version attribute in the library’s manifest file. (See
Table 9-4.)
|
|
An optional boolean value that determines whether the application should use a shared Java EE library with a higher specification or implementation version than the configured value, if one is available. By default this element is false, which means that WebLogic Server uses higher-versioned libraries if they are available. Set this element to true to require the exact matching version as specified in the
specification-version and implementation-version elements.
|
|
An optional String value that provides an alternate context root to use for a Web application shared Java EE library. Use this element if the context root of a library conflicts with the context root of a Web Application in the referencing Java EE application.
Web application shared Java EE library refers to special kind of library: a Web application that is referenced by another Web application. See Web Application Shared Java EE Library Information.
|
For example, this simple entry in the weblogic-application.xml
descriptor references a shared Java EE library, myLibrary
:
<library-ref>
<library-name>myLibrary</library-name>
</library-ref>
In the above example, WebLogic Server attempts to find a library name myLibrary
when deploying the dependent application. If more than one copy of myLibrary
is registered, WebLogic Server selects the library with the highest specification version. If multiple copies of the library use the selected specification version, WebLogic Server selects the copy having the highest implementation version.
This example references a shared Java EE library with a requirement for the specification version:
<library-ref>
<library-name>myLibrary</library-name>
<specification-version>2.0</specification-version>
</library-ref>
In the above example, WebLogic Server looks for matching libraries having a specification version of 2.0 or higher. If multiple libraries are at or above version 2.0, WebLogic Server examines the selected libraries that use Float values for their implementation version and selects the one with the highest version. Note that WebLogic Server ignores any selected libraries that have a non-Float value for the implementation version.
This example references a shared Java EE library with both a specification version and a non-Float value implementation version:
<library-ref>
<library-name>myLibrary</library-name>
<specification-version>2.0</specification-version>
<implementation-version>81Beta</implementation-version>
</library-ref>
In the above example, WebLogic Server searches for a library having a specification version of 2.0 or higher, and having an exact match of 81Beta
for the implementation version.
The following example requires an exact match for both the specification and implementation versions:
<library-ref>
<library-name>myLibrary</library-name>
<specification-version>2.0</specification-version>
<implementation-version>8.1</implementation-version>
<exact-match>true</exact-match>
</library-ref>
The following example specifies a context-root-override
, which in turn, refers to the old context-root
specified in one of its libraries and the new context-root
that should be used instead. (override):
<library-ref>
<library-name>myLibrary</library-name>
<library-context-root-override>
<library-context-root>webapp</library-context-root>
<override-value>mywebapp</override-value>
</library-context-root-override>
</library-ref>
A Java EE application can override context-roots
within a referenced EAR library using entries in the application’s weblogic-application.xml
deployment descriptor. Table 9-3 describes the XML elements that override context-roots
in a library reference.
The following example specifies a context-root-override
, which in turn, refers to the old context-root
specified in one of its libraries and the new context-root
that should be used instead. (override):
<library-ref>
<library-name>myLibrary</library-name>
<specification-version>2.0</specification-version>
<implementation-version>8.1</implementation-version>
<exact-match>true</exact-match>
</library-ref>
<library-context-root-override>
<library-context-root>webapp</library-context-root>
<override-value>mywebapp</override-value>
</library-context-root-override>
In the above example, the current application refers to myLibrary
, which contains a Web application with a context-root
of webapp
. The only way to override this reference is to declare a library-context-root-override
that maps webapp
to mywebapp
.
When referencing the URI of a shared Java EE library that was deployed as a standalone module (EJB or Web Application), note that the module URI corresponds to the deployment name of the shared Java EE library. This can be a name that was manually assigned during deployment, the name of the archive file that was deployed, or the name of the exploded archive directory that was deployed. If you redeploy the same module using a different file name or from a different location, the default deployment name also changes and referencing applications must be updated to use the correct URI.
To avoid this problem, deploy all shared Java EE libraries as Enterprise Applications, rather than as standalone modules. If you choose to deploy a library as a standalone Java EE module, always specify a known deployment name and use that name as the URI in referencing applications.
Any Java EE archive (JAR, WAR, RAR, EAR) can reference one or more registered optional packages using attributes in the archive’s manifest file.
A required string value that identifies the name of an optional package dependency. This value must match the
Extension-Name attribute defined in the optional package’s manifest file.
|
|
An optional String value that defines the required specification version of an optional package. If this element is not set, the archive uses a matching package with the highest specification version. If you include a
specification-version value using the major/minor version format, the archive uses a matching package with the highest specification version that is not below the configured value. If all available package are below the configured specification-version , the archive cannot be deployed.
If you specify a String value that does not use major/minor versioning conventions (for example, 9.2BETA) the archive requires a matching optional package having the exact same string value in the
Specification-Version attribute in the package’s manifest file. (See
Table on page 8.)
|
|
An optional String value that specifies the required implementation version of an optional package. If this element is not set, the archive uses a matching package with the highest implementation version. If you specify a string value using the major/minor version format, the archive uses a matching package with the highest implementation version that is not below the configured value. If all available libraries are below the configured
implementation-version , the application cannot be deployed.
If you specify a String value that does not use major/minor versioning conventions (for example, 9.2BETA) the archive requires a matching optional package having the exact same string value in the
Implementation-Version attribute in the package’s manifest file. (See
Table on page 8.)
|
For example, this simple entry in the manifest file for a dependent archive references two optional packages, myAppPkg
and my3rdPartyPkg
:
Extension-List: internal 3rdparty
internal-Extension-Name: myAppPkg
3rdparty-Extension-Name: my3rdPartyPkg
This example requires a specification version of 2.0 or higher for myAppPkg
:
Extension-List: internal 3rdparty
internal-Extension-Name: myAppPkg
3rdparty-Extension-Name: my3rdPartyPkg
internal-Specification-Version: 2.0
This example requires a specification version of 2.0 or higher for myAppPkg
, and an exact match for the implementation version of my3rdPartyPkg
:
Extension-List: internal 3rdparty
internal-Extension-Name: myAppPkg
3rdparty-Extension-Name: my3rdPartyPkg
internal-Specification-Version: 2.0
3rdparty-Implementation-Version: 8.1GA
By default, when WebLogic Server deploys an application or module and it cannot resolve a reference in the application’s manifest file to an optional package, WebLogic Server prints a warning, but continues with the deployment anyway. You can change this behavior by setting the system property weblogic.application.RequireOptionalPackages
to true
when you start WebLogic Server, either at the command line or in the command script file from which you start the server. Setting this system property to true
means that WebLogic Server does not attempt to deploy an application or module if it cannot resolve an optional package reference in its manifest file.
weblogic.appmerge is a tool that is used to merge libraries into an application, with merged contents and merged descriptors. It also has the ability to write a merged application to disk. You can then use weblogic.appmerge to understand a library merge by examining the merged application you have written to disk.
Invoke weblogic.appmerge using the following syntax:
java weblogic.appmerge [options] <ear, jar, war file, or directory>
where valid options are shown in Table 9-5:
$ java weblogic.appmerge -output CompleteSportsApp.ear -library Weather.war,Calendar.ear SportsApp.ear
The ant task provides similar functionality as the command line utility. It supports source, output, libraryDir, plan and verbose attributes as well as multiple <library> sub-elements. Here is an example:
<taskdef name="appmerge" classname="weblogic.ant.taskdefs.j2ee.AppMergeTask"/>
<appmerge source="SportsApp.ear" output="CompleteSportsApp.ear">
<library file="Weather.war"/>
<library file="Calendar.ear"/>
</appmerge>
The BuildXMLGen
includes a -librarydir
option to generate build targets that include one or more shared Java EE library directories. See Generating a Basic build.xml File Using weblogic.BuildXMLGen.
The wlcompile
and wlappc
Ant tasks include a librarydir
attribute and library
element to specify one or more shared Java EE library directories to include in the classpath for application builds. See Building Applications in a Split Development Directory.
Shared Java EE libraries are registered with one or more WebLogic Server instances by deploying them to the target servers and indicating that the deployments are to be shared. Shared Java EE libraries must be targeted to the same WebLogic Server instances you want to deploy applications that reference the libraries. If you try to deploy a referencing application to a server instance that has not registered a required library, deployment of the referencing application fails. See Registering Libraries with WebLogic Server in Deploying Applications to WebLogic Server for more information.
See Install a Java EE Library for detailed instructions on installing (deploying) a shared Java EE library using the Administration Console. See Target a Shared Java EE Library to a Server or Cluster for instructions on using the Administration Console to target the library to the server or cluster to which the application that is referencing the library is also targeted.
If you use the wldeploy
Ant task as part of your iterative development process, use the library
, libImplVer
, and libSpecVer
attributes to deploy a shared Java EE library. See wldeploy Ant Task Reference, for details and examples.
After registering a shared Java EE library, you can deploy applications and archives that depend on the library. Dependent applications can be deployed only if the target servers have registered all required libraries, and the registered deployments meet the version requirements of the application or archive. See Deploying Applications that Reference Libraries in Deploying Applications to WebLogic Server for more information.
In general, this topic discusses shared Java EE libraries that can be referenced only by Enterprise Applications. You can also create libraries that can be referenced only by another Web application. The functionality is very similar to application libraries, although the method of referencing them is slightly different.
Note: | For simplicity, this section uses the term Web application library when referring to a shared Java EE library that is referenced only by another Web application. |
weblogic-application.xml
file, Web applications reference Web application libraries by updating the weblogic.xml
deployment descriptor file. The elements are almost same as those described in Referencing Shared Java EE Libraries in an Enterprise Application; the only difference is that the <context-root>
child element of <library-ref>
is ignored in this case.weblogic.xml
deployment descriptor file of a Web Application. Other than these differences in how they are referenced, the way to create, package, and deploy a Web application library is the same as that of a standard shared Java EE library.
Just as standard shared Java EE applications can be deployed to WebLogic Server as application-libraries
, a standard Web application can be deployed to WebLogic Server as a webapp-library
so that other Web applications can refer to these libraries.
Web application libraries facilitate the reuse of code and resources. Such libraries also help you separate out third-party Web applications or frameworks that your Web application might be using. Furthermore, common resources can be packaged separately as libraries and referenced in different Web applications, so that you don’t have to bundle them with each Web application. When you include a webapp-library
in your Web application, at deployment time the container merges all the static resources, classes, and JAR
files into your Web application.
The first step in using a WebApp library is to register a Web application as a webapp-library
. This can be accomplished by deploying a Web application using either the Administration Console or the weblogic.Deployer
tool as a library. To make other Web applications refer to this library, their weblogic.xml
file must have a library-ref
element pointing to the webapp-library
, as follows:
<library-ref>
<library-name>BaseWebApp</library-name>
<specification-version>2.0</specification-version>
<implementation-version>8.1beta</implementation-version>
<exact-match>false</exact-match>
</library-ref>
When multiple libraries are present, the CLASSPATH/resource
path precedence order follows the order in which the library-refs
elements appear in the weblogic.xml
file.
Each deployed shared Java EE library is represented by a LibraryRuntimeMBean
. You can use this MBean to obtain information about the library itself, such as its name or version. You can also obtain the ApplicationRuntimeMBean
s associated with deployed applications. ApplicationRuntimeMBean
provides two methods to access the libraries that the application is using:
For more information, see the WebLogic Server 10.0 API Reference.
When an Enterprise Application references one or more shared Java EE libraries, and the application is deployed to WebLogic Server, the server internally merges the information in the weblogic-application.xml
file of the referencing Enterprise Application with the information in the deployment descriptors of the referenced libraries. The order in which this happens is as follows:
weblogic-application.xml
deployment descriptor.weblogic-application.xml
, weblogic.xml
, weblogic-ejb-jar.xml
, and so on. weblogic-application.xml
file of the referencing Enterprise application on top of the library descriptor files.
As a result of the way the descriptor files are merged, the elements in the descriptors of the shared Java EE libraries referenced first in the weblogic-application.xml
file have precedence over the ones listed last. The elements of the Enterprise application’s descriptor itself have precedence over all elements in the library descriptors.
For example, assume that an Enterprise application called myApp
references two shared Java EE libraries (themselves packaged as Enterprise applications): myLibA
and myLibB
, in that order. Both the myApp
and myLibA
applications include an EJB module called myEJB
, and both the myLibA
and myLibB
applications include an EJB module called myOtherEJB
.
Further assume that once the myApp
application is deployed, a client invokes, via the myApp
application, the myEJB
module. In this case, WebLogic Server actually invokes the EJB in the myApp
application (rather than the one in myLibA
) because modules in the referencing application have higher precedence over modules in the referenced applications. If a client invokes the myOtherEJB
EJB, then WebLogic Server invokes the one in myLibA
, because the library is referenced first in the weblogic-application.xml
file of myApp
, and thus has precedence over the EJB with the same name in the myLibB
application.
Keep in mind these best practices when developing shared Java EE libraries and optional packages:
/lib
subdirectory rather than using shared Java EE libraries or optional packages. Classes in the /lib
subdirectory are added to the system classpath at server start-up time.Extension-Name
value for each shared Java EE library. If you do not specify an extension name, one is derived from the deployment name of the library. Default deployment names are different for archive and exploded archive deployments, and they can be set to arbitrary values in the deployment commandcontext-root
element in the EAR’s weblogic-application.xml
deployment descriptor to override the library’s context root.
![]() ![]() ![]() |