Developing Applications with WebLogic Server

Creating Shared J2EE Libraries and Optional Packages

The following sections describe how to share components and classes among applications using shared J2EE libraries and optional packages:

• Overview of Shared J2EE Libraries and Optional Packages
• Creating Shared J2EE Libraries
• Referencing Shared J2EE Libraries in an Enterprise Application
• Referencing Optional Packages from a J2EE Application or Module
• Using weblogic.appmerge to Merge Libraries
• Integrating Shared J2EE Libraries with the Split Development Directory Environment
• Deploying Shared J2EE Libraries and Dependent Applications
• Web Application Shared J2EE Library Information
• Accessing Registered Shared J2EE Library Information with LibraryRuntimeMBean
• Order of Precedence of Modules When Referencing Shared J2EE Libraries
• Best Practices for Using Shared J2EE Libraries

 

---

Overview of Shared J2EE Libraries and Optional Packages

Prior to WebLogic Server 9.0, multiple Enterprise Applications could not easily share a single J2EE module or a collection of modules. Sharing J2EE modules required you to either package a copy of the modules in multiple EARs, or add the paths to the shared modules to the system classpath and add duplicate deployment descriptors for the shared modules into each application that referenced them. Copying modules made subsequent application updates difficult, because an update to a shared module required re-copying and re-packaging all Enterprise Applications that used the module. Adding modules to the system classpath also made updates difficult, because it required rebooting the WebLogic Server instance in order to use an updated module.

The shared J2EE library feature in WebLogic Server 9.0 provides an easy way to share one or more different types of J2EE modules among multiple Enterprise Applications. A shared J2EE library is a single module or collection of modules that is registered with the J2EE application container upon deployment. A shared J2EE library can be any of the following:

• standalone EJB module
• standalone Web application module
• multiple EJB modules packaged in an Enterprise Application
• multiple Web application modules package in an Enterprise Application
• single plain JAR file

BEA recommends that you package a shared J2EE library into its appropriate archive file (EAR, JAR, or WAR). However, for development purposes, you may choose to deploy shared J2EE libraries as exploded archive directories to facilitate repeated updates and redeployments.

After the shared J2EE 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 J2EE library.

In general, this topic discusses shared J2EE 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 J2EE Library Information for details.

Note: WebLogic Server 9.0 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.

Optional Packages

WebLogic Server supports optional packages as described in the J2EE 1.4 Specification, Section 8.2 Optional Package Support, with versioning described in Optional Package Versioning. Optional packages provide similar functionality to J2EE libraries, allowing you to easily share a single JAR file among multiple applications. As with J2EE 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 J2EE modules that reference the package in their manifest files.

Optional packages differ from J2EE libraries because optional packages can be referenced from any J2EE module (EAR, JAR, WAR, or RAR archive) or exploded archive directory. J2EE 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 J2EE libraries, are used in this case, because the individual Web Application modules must reference the shared JAR file. (With J2EE 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 J2EE libraries and optional packages. Optional packages are called out only when necessary.

Versioning Support for Libraries

WebLogic Server supports versioning of shared J2EE 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 J2EE libraries, as described in the Optional Package Versioning document:

• Specification Version—Identifies the version number of the specification (for example, the J2EE specification version) to which a shared J2EE library or optional package conforms.
• Implementation Version—Identifies the version number of the actual code implementation for the library or package. For example, this would correspond to the actual revision number or release number of your code. Note that you must also provide a specification version in order to specify an implementation version.

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 J2EE 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 J2EE 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 J2EE Libraries in an Enterprise Application.

Shared J2EE Libraries and Optional Packages Compared

Optional packages and shared J2EE libraries have the following features in common:

• Both are registered with WebLogic Server instances at deployment time.
• Both support an optional implementation version and specification version string.
• Applications that reference shared J2EE libraries and optional packages can specify required versions for the shared files.

Optional packages differ from shared J2EE Libraries in the following basic ways:

• Optional packages are plain JAR files, whereas shared J2EE libraries can be plain JAR files, J2EE Enterprise Applications, or standalone J2EE modules (EJB and Web applications). This means that libraries can have valid J2EE and WebLogic Server deployment descriptors. Any deployment descriptors in an optional package JAR file are ignored.
• Any J2EE application or module can reference an optional package (using META-INF/MANIFEST.MF), whereas only Enterprise Applications and Web applications can reference a shared J2EE library (using weblogic-application.xml or weblogic.xml)
• Optional packages can reference other optional packages, but shared J2EE libraries cannot reference other shared J2EE libraries.

In general, use shared J2EE 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 J2EE modules.

Plain JAR files can be shared either as libraries or optional packages. Use optional packages if you want to:

• Share a plain JAR file among multiple J2EE modules
• Reference shared JAR files from other shared JARs
• Share plain JARs as described by the J2EE 1.4 specification

Use shared J2EE 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 J2EE specification.

Note: BEA documentation and WebLogic Server utilities use the term shared J2EE library to refer to both libraries and optional packages. Optional packages are called out only when necessary.

Additional Information

For information about deploying and managing shared J2EE libraries, optional packages, and referencing applications from the Administrator's perspective, see Deploying Shared J2EE Libraries and Dependent Applications in Deploying Applications to WebLogic Server.

 

---

Creating Shared J2EE Libraries

To create a new shared J2EE library that you can share with multiple applications:

Assemble the shared J2EE library into a valid, deployable J2EE module or Enterprise Application. The library must have the required J2EE deployment descriptors for the J2EE module or for an Enterprise Application.

See Assembling Shared J2EE Library Files.

Assemble optional package classes into a working directory.

See Assembling Optional Package Class Files.

Create and edit the MANIFEST.MF file for the shared J2EE library to specify the name and version string information.

See Editing Manifest Attributes for Shared J2EE Libraries.

Package the shared J2EE library for distribution and deployment.

See Packaging Shared J2EE Libraries for Distribution and Deployment.

Assembling Shared J2EE Library Files

The following types of J2EE modules can be deployed as a shared J2EE library:

• An EJB module, either an exploded directory or packaged in a JAR file.
• A Web Application module, either an exploded directory or packaged in a WAR file.
• An Enterprise application, either an exploded directory or packaged in an EAR file.
• A plain Java class or classes packaged in a JAR file.

Shared J2EE libraries have the following restrictions:

• You cannot reference a shared J2EE library from another library.
• You must ensure that context roots in Web application modules of the shared J2EE library do not conflict with context roots in the referencing Enterprise Application. If necessary, you can configure referencing applications to override a library's context root. See Referencing Shared J2EE Libraries in an Enterprise Application.
• Shared J2EE libraries cannot be nested. For example, if you are deploying an EAR as a shared J2EE library, the entire EAR must be designated as the library. You cannot designate individual J2EE modules within the EAR as separate, named libraries.
• As with any other J2EE module or Enterprise Application, a shared J2EE library must be configured for deployment to the target servers or clusters in your domain. This means that a library requires valid J2EE deployment descriptors as well as WebLogic Server-specific deployment descriptors and an optional deployment plan. See Deploying Applications to WebLogic Server.

BEA recommends packaging shared J2EE libraries as Enterprise Applications, rather than as standalone J2EE 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 J2EE 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 J2EE library as a standalone J2EE module, always specify a known deployment name during deployment and use that name as the URI in referencing applications.

Assembling Optional Package Class Files

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:

Create a working directory for the new optional package. For example:

mkdir /apps/myOptPkg

Copy the compiled class files into the working directory, creating the appropriate package sudirectories as necessary. For example:

mkdir -p /apps/myOptPkg/org/myorg/myProduct
cp /build/classes/myOptPkg/org/myOrg/myProduct/*.class /apps/myOptPkg/org/myOrg/myProduct

If you already have a JAR file that you want to use as an optional package, extract its contents into the working directory so that you can edit the manifest file:

cd /apps/myOptPkg
jar xvf /build/libraries/myLib.jar

Editing Manifest Attributes for Shared J2EE Libraries

The name and version information for a shared J2EE library are specified in the META-INF/MANIFEST.MF file. Table 8-1describes the valid shared J2EE library manifest attributes.

Table 8-1 Manifest Attributes for J2EE Libraries

To specify attributes in a manifest file:

Open (or create) the manifest file using a text editor. For the example shared J2EE library, you would use the commands:

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

In the text editor, add a string value to specify the name of the shared J2EE library. For example:

Extension-Name: myExtension

Applications that reference the library must specify the exact Extension-Name in order to use the shared files.

As a best practice, enter the optional version information for the shared J2EE library. For example:

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 8-1 on page 8)

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 J2EE Libraries and Dependent Applications.

Packaging Shared J2EE Libraries for Distribution and Deployment

If you are delivering the shared J2EE 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 J2EE libraries, or a simple .JAR file for optional packages) for distribution. See Deploying and Packaging from a Split Development Directory.

Because a shared J2EE library is packaged as a standard J2EE 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.

 

---

Referencing Shared J2EE Libraries in an Enterprise Application

A J2EE application can reference a registered shared J2EE library using entries in the application's weblogic-application.xml deployment descriptor. Table 8-2 describes the XML elements that define a library reference.

Table 8-2 weblogic-application.xml Elements for Referencing a Shared J2EE Library

For example, this simple entry in the weblogic-application.xml descriptor references a shared J2EE 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 J2EE 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 J2EE 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>

URIs for Shared J2EE Libraries Deployed As a Standalone Module

When referencing the URI of a shared J2EE 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 J2EE 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 J2EE libraries as Enterprise Applications, rather than as standalone modules. If you choose to deploy a library as a standalone J2EE module, always specify a known deployment name and use that name as the URI in referencing applications.

 

---

Referencing Optional Packages from a J2EE Application or Module

Any J2EE archive (JAR, WAR, RAR, EAR) can reference one or more registered optional packages using attributes in the archive's manifest file.

Table 8-3 Manifest Attributes for Referencing Optional Packages

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.

 

---

Using weblogic.appmerge to Merge Libraries

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.

• Using weblogic.appmerge from the CLI
• Using weblogic.appmerge as an Ant Task

Using weblogic.appmerge from the CLI

Invoke weblogic.appmerge using the following syntax:

   java weblogic.appmerge [options] <ear, jar, war file, or directory>

where valid options are shown in Table 8-4:

 

Example:

   $ java weblogic.appmerge -output CompleteSportsApp.ear -library Weather.war,Calendar.ear SportsApp.ear

Using weblogic.appmerge as an Ant Task

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>

 

---

Integrating Shared J2EE Libraries with the Split Development Directory Environment

The BuildXMLGen includes a -librarydir option to generate build targets that include one or more shared J2EE 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 J2EE library directories to include in the classpath for application builds. See Building Applications in a Split Development Directory.

 

---

Deploying Shared J2EE Libraries and Dependent Applications

Shared J2EE 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 J2EE 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 Shared J2EE Library for detailed instructions on installing (deploying) a shared J2EE library using the Administration Console. See Target a Shared J2EE 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 J2EE library. See wldeploy Ant Task Reference, for details and examples.

After registering a shared J2EE 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.

 

---

Web Application Shared J2EE Library Information

In general, this topic discusses shared J2EE 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 J2EE library that is referenced only by another Web application.

In particular:

• Web application libraries can only be referenced by other Web applications.
• Rather than update the 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 J2EE Libraries in an Enterprise Application; the only difference is that the <context-root> child element of <library-ref> is ignored in this case.
• You cannot reference any other type of shared J2EE library (EJB, Enterprise application, or plain JAR file) from the 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 J2EE library.

 

---

Accessing Registered Shared J2EE Library Information with LibraryRuntimeMBean

Each deployed shared J2EE 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 ApplicationRuntimeMBeans associated with deployed applications. ApplicationRuntimeMBean provides two methods to access the libraries that the application is using:

• getLibraryRuntimes() returns the shared J2EE libraries referenced in the weblogic-application.xml file.
• getOptionalPackageRuntimes() returns the optional packages referenced in the manifest file.

For more information, see the WebLogic Server 9.0 API Reference.

 

---

Order of Precedence of Modules When Referencing Shared J2EE Libraries

When an Enterprise Application references one or more shared J2EE 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:

When the Enterprise Application is deployed, WebLogic Server reads its weblogic-application.xml deployment descriptor.
WebLogic Server reads the deployment descriptors of any referenced shared J2EE libraries. Depending on the type of library (Enterprise Application, EJB, or Web application), the read file might be weblogic-application.xml, weblogic.xml, weblogic-ejb-jar.xml, and so on.
WebLogic Server first merges the referenced shared J2EE library deployment descriptors (in the order in which they are referenced, one at a time) and then merges the 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 J2EE 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 J2EE 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.

 

---

Best Practices for Using Shared J2EE Libraries

Keep in mind these best practices when developing shared J2EE libraries and optional packages:

• Use shared J2EE Libraries when you want to share one or more J2EE modules (EJBs, Web Applications, Enterprise Applications, or plain Java classes) with multiple Enterprise Applications.
• If you need to deploy a standalone J2EE module, such as an EJB JAR file, as a shared J2EE library, package the module within an Enterprise Application. Doing so avoids potential URI conflicts, because the library URI of a standalone module is derived from the deployment name.
• If you choose to deploy a shared J2EE library as a standalone J2EE module, always specify a known deployment name during deployment and use that name as the URI in referencing applications.
• Use optional packages when multiple J2EE archive files need to share a set of Java classes.
• If you have a set of classes that must be available to applications in an entire domain, and you do not frequently update those classes (for example, if you need to share 3rd party classes in a domain), use the domain /lib subdirectory rather than using shared J2EE libraries or optional packages. Classes in the /lib subdirectory are added to the system classpath at server start-up time.
• Always specify a specification version and implementation version, even if you do not intend to enforce version requirements with dependent applications. Specifying versions for shared J2EE libraries enables you to deploy multiple versions of the shared files for testing.
• Always specify an Extension-Name value for each shared J2EE 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
• When developing a Web Application for deployment as a shared J2EE library, use a unique context root. If the context root conflicts with the context root in a dependent J2EE application, use the context-root element in the EAR's weblogic-application.xml deployment descriptor to override the library's context root.
• Package shared J2EE libraries as archive files for delivery to Administrators or deployers in your organization. Deploy libraries from exploded archive directories during development to allow for easy updates and repeated redeployments.
• Deploy shared J2EE libraries to all WebLogic Server instances on which you want to deploy dependent applications and archives. If a library is not registered with a server instance on which you want to deploy a referencing application, deployment of the referencing application fails.

Contact BEA |  Feedback |  Privacy  |  © 2025 BEA Systems