9 Creating Shared Java EE Libraries and Optional Packages

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

Overview of 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:

  • 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

Oracle 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.

Optional Packages

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 (see http://java.sun.com/javase/6/docs/technotes/guides/extensions/versioning.html). 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 deploying 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 are also supported as Java EE shared libraries in weblogic.BuildXMLGen, whereby all manifests of an application and its modules are scanned to look for optional package references. If optional package references are found they are added to the wlcompile and appc tasks in the generated build.xml file.

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:

Oracle 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.

Library Directories

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.

Versioning Support for Libraries

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 at http://java.sun.com/j2se/1.4.2/docs/guide/extensions/versioning.html:

  • Specification Version—Identifies the version number of the specification (for example, the Java EE specification version) to which a shared Java EE 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, Oracle recommends that you always include version information (a specification 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.

Shared Java EE Libraries and Optional Packages Compared

Optional packages and shared Java EE 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 Java EE libraries and optional packages can specify required versions for the shared files.

  • Optional packages can reference other optional packages, and shared Java EE libraries can reference other shared Java EE libraries.

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

  • Optional packages are plain JAR files, whereas shared Java EE libraries can be plain JAR files, Java EE Enterprise Applications, or standalone Java EE modules (EJB and Web applications). This means that libraries can have valid Java EE and WebLogic Server deployment descriptors. Any deployment descriptors in an optional package JAR file are ignored.

  • Any Java EE application or module can reference an optional package (using 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:

  • Share a plain JAR file among multiple Java EE modules

  • Reference shared JAR files from other shared JARs

  • Share plain JARs as described by the Java EE 5.0 specification

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:

Oracle 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.

Additional Information

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 Oracle Fusion Middleware Deploying Applications to Oracle WebLogic Server.

Creating Shared Java EE Libraries

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

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

    See Assembling Shared Java EE Library Files.

  2. Assemble optional package classes into a working directory.

    See Assembling Optional Package Class Files.

  3. Create and edit the 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.

  4. Package the shared Java EE library for distribution and deployment.

    See Packaging Shared Java EE Libraries for Distribution and Deployment.

Assembling Shared Java EE Library Files

The following types of Java EE modules can be deployed as a shared Java EE 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.

  • A shared Java EE library referenced from another library. (See Web Application Shared Java EE Library Information.)

Shared Java EE libraries have the following restrictions:

  • You must ensure that context roots in Web application modules of the shared Java EE 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 Java EE Libraries in an Enterprise Application.

  • Shared Java EE libraries cannot be nested. For example, if you are deploying an EAR as a shared Java EE library, the entire EAR must be designated as the library. You cannot designate individual Java EE modules within the EAR as separate, named libraries.

  • As with any other Java EE module or Enterprise Application, a shared Java EE library must be configured for deployment to the target servers or clusters in your domain. This means that a library requires valid Java EE deployment descriptors as well as WebLogic Server-specific deployment descriptors and an optional deployment plan. See Oracle Fusion Middleware Deploying Applications to Oracle WebLogic Server.

Oracle 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.

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:

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

    mkdir /apps/myOptPkg
    
  2. 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
    
  3. 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 Java EE Libraries

The name and version information for a shared Java EE library are specified in the META-INF/MANIFEST.MF file. Table 9-2 describes the valid shared Java EE library manifest attributes.

Table 9-1 Manifest Attributes for Java EE Libraries

Attribute Description
Extension-Name

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.

Specification-Version

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.

The Specification-Version uses the following format:

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.

Implementation-Version

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.

Implementation-Version uses the following formats:

  • Major/minor version format, with version and revision numbers separated by periods (such as "9.0.1.1")

  • Text format, with named versions (such as "9011Beta" or "9.0.1.1.B")

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:

  1. Open (or create) the manifest file using a text editor. For the example shared Java EE 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
    
  2. In the text editor, add a string value to specify the name of the shared Java EE library. For example:

    Extension-Name: myExtension
    

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

  3. As a best practice, enter the optional version information for the shared Java EE 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 9-2)

    Note:

    Although you can optionally specify the Specification-Version and Implementation-Version at the command line during deployment, Oracle 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.

Packaging Shared Java EE Libraries for Distribution and Deployment

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 Applications Using wldeploy.

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 Oracle Fusion Middleware Deploying Applications to Oracle 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 Java EE Libraries in an Enterprise Application

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.

Table 9-2 weblogic-application.xml Elements for Referencing a Shared Java EE Library

Element Description

library-ref

library-ref is the parent element in which you define a reference to a shared Java EE library. Enclose all other elements within library-ref.

library-name

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-2.)

specification-version

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-2.)

implementation-version

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-2.)

exact-match

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.

context-root

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>

Overriding context-roots Within a Referenced Enterprise Library

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-2 describes the XML elements that override context-roots in a library reference.

Table 9-3 weblogic-application.xml Elements for Overriding a Shared Java EE Library

Element Description
library-context-root

An optional String value that overrides the context-root elements declared in libraries. In the absence of this element, the library's context-root is used.

Only a referencing application (i.e., a user application) can override the context-root elements declared in its libraries.

override-value

An optional String value that specifies the value of the library-context-root-override element when overriding the context-root elements declared in libraries. In the absence of these elements, the library's context-root is used.


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.

URIs for Shared Java EE Libraries Deployed As a Standalone Module

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.

Referencing Optional Packages from a Java EE Application or Module

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

Table 9-4 Manifest Attributes for Referencing Optional Packages

Attribute Description

Extension-List logical_name [...]

A required String value that defines a logical name for an optional package dependency. You can use multiple values in the Extension-List attribute to designate multiple optional package dependencies. For example:

Extension-List: dependency1 dependency2
[logical_name-]Extension-Name

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.

If you are referencing multiple optional packages from a single archive, prepend the appropriate logical name to the Extension-Name attribute. For example:

dependency1-Extension-Name: myOptPkg

[logical_name-]Specification-Version

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 9-2.)

If you are referencing multiple optional packages from a single archive, prepend the appropriate logical name to the Specification-Version attribute.

[logical_name-]Implementation-Version

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 9-2.)

If you are referencing multiple optional packages from a single archive, prepend the appropriate logical name to the Implementation-Version attribute.


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

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-2:

Table 9-5 weblogic.appmerge Options

Option Comment
 -help 

Print the standard usage message.

-version 

Print version information.

-output <file> 

Specifies an alternate output archive or directory. If not set, output is placed in the source archive or directory.

-plan <file>

Specifies an optional deployment plan.

-verbose

Provide more verbose output.

-library <file>

Comma-separated list of libraries. Each library may optionally set its name and versions, if not already set in its manifest, using the following syntax:

<file> [@name=<string>@libspecver=<version> @libimplver=<version|string>].
-librarydir <dir>

Registers all files in specified directory as libraries.

-writeInferredDescriptors

Specifies that the application or module contains deployment descriptors with annotation information.


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 Java EE Libraries with the Split Development Directory Environment

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.

Deploying Shared Java EE Libraries and Dependent Applications

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 Oracle Fusion Middleware Deploying Applications to Oracle 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 Appendix B, "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 Oracle Fusion Middleware Deploying Applications to Oracle WebLogic Server for more information.

Web Application Shared Java EE Library 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.

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 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.

  • You cannot reference any other type of shared Java EE 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 Java EE library.

Using WebApp Libraries With Web Applications

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.

Accessing Registered Shared Java EE Library Information with LibraryRuntimeMBean

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

  • getLibraryRuntimes() returns the shared Java EE libraries referenced in the weblogic-application.xml file.

  • getOptionalPackageRuntimes() returns the optional packages referenced in the manifest file.

For more information, see the Oracle Fusion Middleware Oracle WebLogic Server API Reference.

Order of Precedence of Modules When Referencing Shared Java EE Libraries

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:

  1. When the Enterprise Application is deployed, WebLogic Server reads its weblogic-application.xml deployment descriptor.

  2. WebLogic Server reads the deployment descriptors of any referenced shared Java EE 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.

  3. WebLogic Server first merges the referenced shared Java EE 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 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.

Best Practices for Using Shared Java EE Libraries

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

  • Use shared Java EE Libraries when you want to share one or more Java EE modules (EJBs, Web Applications, Enterprise Applications, or plain Java classes) with multiple Enterprise Applications.

  • If you need to deploy a standalone Java EE module, such as an EJB JAR file, as a shared Java EE 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 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.

  • Use optional packages when multiple Java EE 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 Java EE 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 Java EE libraries enables you to deploy multiple versions of the shared files for testing.

  • Always specify an 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 command

  • When developing a Web Application for deployment as a shared Java EE library, use a unique context root. If the context root conflicts with the context root in a dependent Java EE application, use the context-root element in the EAR's weblogic-application.xml deployment descriptor to override the library's context root.

  • Package shared Java EE 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 Java EE 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.