14 Creating Shared Jakarta EE Libraries and Optional Packages

You can share components and classes among applications using shared Jakarta EE libraries supported in WebLogic Server.

Overview of Shared Jakarta EE Libraries and Optional Packages

The shared Jakarta EE library feature in WebLogic Server provides an easy way to share one or more different types of Jakarta EE modules among multiple enterprise applications. A shared Jakarta EE libraries can be referenced by enterprise applications and you can also create libraries that can be referenced only by another Web application.

A shared Jakarta EE library is a single module or collection of modules that is registered with the Jakarta EE application container upon deployment. A shared Jakarta 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 Jakarta EE library into its appropriate archive file (EAR, JAR, or WAR). However, for development purposes, you may choose to deploy shared Jakarta EE libraries as exploded archive directories to facilitate repeated updates and redeployments.

After the shared Jakarta 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 class path of the referencing application, and the primary deployment descriptors of the referencing application or module are merged (in memory) with those of the modules that make up the shared Jakarta EE library.

In general, this topic discusses shared Jakarta 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 Jakarta 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 Domain /lib Directory.

Library Directories

The Jakarta 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 specification and implementation versioning for registered libraries. The manifest names have historical roots in Optional Package Versioning; the WebLogic version-selection rules for this release are given below. Historical background: https://docs.oracle.com/javase/8/docs/technotes/guides/extensions/versioning.html

  • Specification Version—Identifies the version number of the specification (for example, the Jakarta EE specification version) to which a shared Jakarta 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 Jakarta 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 Jakarta 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 Jakarta EE Libraries in an Enterprise Application.

Shared Jakarta EE Libraries and Optional Packages Compared

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

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

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

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

  • Any Jakarta 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 Jakarta EE library (using weblogic-application.xml or weblogic.xml).

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

Use WebLogic registered optional packages for manifest-declared dependencies on server-registered JARs. For portable libraries bundled with an application, use the Jakarta EE mechanisms described in Library Directories and Manifest Class-Path. Use WebLogic shared libraries when separately registered modules or JARs need the library-ref deployment model.

Note:

Oracle documentation and WebLogic Server utilities use the term shared Jakarta 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 Jakarta EE libraries, optional packages, and referencing applications from the administrator's perspective, see Deploying Shared Jakarta EE Libraries and Dependent Applications in Deploying Applications to Oracle WebLogic Server.

Creating Shared Jakarta EE Libraries

You can deploy the Jakarta EE modules such as an EJB, a Web application, an enterprise application, a plain Java class, and others as a shared Jakarta EE library. These modules can be shared among multiple enterprise applications in WebLogic Server.

Create a shared library from an EAR, EJB JAR, WAR, or plain library JAR using the packaging appropriate to its contents.

  1. For an EAR, EJB or WAR library, assemble a valid module/application and include the descriptors required by its metadata and configuration. For a plain JAR library or optional package, assemble the compiled classes in their package directories. See Assembling Shared Jakarta EE Library Files or Assembling Optional Package Class Files, as appropriate.
  2. Create and edit the MANIFEST.MF file for the shared Jakarta EE library to specify the name and version string information.
  3. Package the shared Jakarta EE library for distribution and deployment.

Assembling Shared Jakarta EE Library Files

The following types of Jakarta EE modules can be deployed as a shared Jakarta 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 Jakarta EE library referenced from another library. (See Web Application Shared Jakarta EE Library Information.)

Shared Jakarta EE libraries have the following restrictions:

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

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

  • Target the library to the servers or clusters that will host its consumers. Include valid standard or WebLogic descriptors when required by the module type or selected configuration; use a deployment plan when needed. A plain library JAR or optional package does not need application/module deployment descriptors.

Oracle recommends packaging shared Jakarta EE libraries as enterprise applications, rather than as standalone Jakarta 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 Jakarta 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 Jakarta EE library as a standalone Jakarta 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 subdirectories as necessary. For example:

    The sample class package is org.myOrg.myProduct. Replace the root paths with your actual work and compiled-class directories.

    OPT_PKG_WORK="/apps/myOptPkg"
OPT_PKG_CLASSES="/build/classes/myOptPkg"
mkdir -p "$OPT_PKG_WORK/org/myOrg/myProduct"
cp "$OPT_PKG_CLASSES"/org/myOrg/myProduct/*.class \
  "$OPT_PKG_WORK/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 Jakarta EE Libraries

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

Table 14-1 Manifest Attributes for Jakarta EE Libraries

Attribute Description
Extension-Name

An optional string value that identifies the name of the shared Jakarta 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 library specification version consisting of nonnegative integer components separated by periods, for example 2.0 or 9.0.1.1. Referencing descriptors can require a minimum version or, with exact-match=true, the supplied exact version. Deployment needs a matching registered library under those rules; an exact 2.0 provider is not required when a higher specification version is allowed. 2.0 and 2.0.0 compare as the same specification version.

The specification version for a shared Jakarta EE library can also be set at the command-line when deploying the library, with some restrictions. See Deploying Shared Jakarta EE Libraries and Dependent Applications.

Implementation-Version An implementation version requires a specification version when registering a library. Versions such as 1.9 and 1.10 are compared as integer components, so 1.10 is higher; they are not floating-point numbers. Resolution first selects the highest permitted specification version, or the supplied exact specification when exact-match=true. It then resolves an implementation at that selected specification. When all implementations there are numeric component versions, an omitted implementation selects the highest, and a non-exact numeric requirement selects the highest not below it. For a text or mixed implementation set, specify the required implementation explicitly; a text requirement matches that exact text. An omitted implementation can select a sole text implementation, but multiple unrankable implementations leave the reference unresolved. With exact-match=true, only the version fields actually supplied are pinned. Failure at the chosen specification does not cause fallback to a lower specification.

The implementation version for a shared Jakarta EE library can also be set at the command-line when deploying the library, with some restrictions. See Deploying Shared Jakarta 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 Jakarta EE library, you would use the commands:

    Any text editor may be used; emacs below is only an example.

    cd /apps/myLibrary
mkdir -p META-INF
emacs META-INF/MANIFEST.MF

    For the optional package example, use:

    cd /apps/myOptPkg
mkdir -p META-INF
emacs META-INF/MANIFEST.MF
  2. In the text editor, add a string value to specify the name of the shared Jakarta 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 Jakarta 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 14-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 Jakarta EE Libraries and Dependent Applications.

    For the optional package assembled at /apps/myOptPkg, save the following complete manifest as /apps/myOptPkg/META-INF/MANIFEST.MF, including the final blank line.

    Manifest-Version: 1.0
Extension-Name: myOptPkg
Specification-Version: 2.0
Implementation-Version: 9.0.0

Packaging Shared Jakarta EE Libraries for Distribution and Deployment

If you are delivering the shared Jakarta 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 Jakarta EE libraries, or a simple .JAR file for optional packages) for distribution. See Deploying Applications Using wldeploy.

Because a shared Jakarta EE library is packaged as a standard Jakarta 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 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 Jakarta EE Libraries in an Enterprise Application

A Jakarta EE application can reference a registered shared Jakarta EE library using entries in the application's weblogic-application.xml deployment descriptor.

Table 14-2 describes the XML elements that define a library reference.

Table 14-2 weblogic-application.xml Elements for Referencing a Shared Jakarta EE Library

Element Description

library-ref

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

library-name

A required string value that specifies the name of the shared Jakarta EE library to use. library-name must exactly match the value of the Extension-Name attribute in the library's manifest file. (See Table 14-1.)

specification-version

An optional String value that defines the required specification version of the shared Jakarta 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.

Specification versions must use the numeric component format; 9.2BETA is invalid as a specification version. 2.0 and 2.0.0 compare as the same specification version.
implementation-version Versions such as 1.9 and 1.10 are compared as integer components, so 1.10 is higher; they are not floating-point numbers. Resolution first selects the highest permitted specification version, or the supplied exact specification when exact-match=true. It then resolves an implementation at that selected specification. When all implementations there are numeric component versions, an omitted implementation selects the highest, and a non-exact numeric requirement selects the highest not below it. For a text or mixed implementation set, specify the required implementation explicitly; a text requirement matches that exact text. An omitted implementation can select a sole text implementation, but multiple unrankable implementations leave the reference unresolved. With exact-match=true, only the version fields actually supplied are pinned. Failure at the chosen specification does not cause fallback to a lower specification.
exact-match

An optional Boolean value that determines whether the application should use a shared Jakarta 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 alternate context root for a WAR library referenced by an EAR. An EAR can reference a WAR library and use this element to supply that WAR module’s context root. When a WAR references another WAR through weblogic.xml, this child is ignored.

For example, this simple entry in the weblogic-application.xml descriptor references a shared Jakarta EE library, myLibrary: 

<library-ref>
   <library-name>myLibrary</library-name>
</library-ref>

In the above example, WebLogic Server attempts to find a library named 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 Jakarta EE library with a requirement for the specification version:

<library-ref>
   <library-name>myLibrary</library-name>
   <specification-version>2.0</specification-version>
</library-ref>

Versions such as 1.9 and 1.10 are compared as integer components, so 1.10 is higher; they are not floating-point numbers. Resolution first selects the highest permitted specification version, or the supplied exact specification when exact-match=true. It then resolves an implementation at that selected specification. When all implementations there are numeric component versions, an omitted implementation selects the highest, and a non-exact numeric requirement selects the highest not below it. For a text or mixed implementation set, specify the required implementation explicitly; a text requirement matches that exact text. An omitted implementation can select a sole text implementation, but multiple unrankable implementations leave the reference unresolved. With exact-match=true, only the version fields actually supplied are pinned. Failure at the chosen specification does not cause fallback to a lower specification.

This example references a shared Jakarta EE library with both a specification version and a text implementation version:

<library-ref>
   <library-name>myLibrary</library-name>
   <specification-version>2.0</specification-version>
   <implementation-version>81Beta</implementation-version>
</library-ref>

The selected specification must contain implementation 81Beta; use exact-match=true with both versions if a specific known pair is required.

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 with the library reference. When a WAR library reference is made from weblogic-application.xml, the context-root may be specified with the reference: 

<library-ref>
   <library-name>myLibrary</library-name>
   <context-root>mywebapp</context-root>
</library-ref>

Overriding context-roots Within a Referenced Enterprise Library

A Jakarta EE application can override context-roots within a referenced EAR library using entries in the application's weblogic-application.xml deployment descriptor. Table 14-3 describes the XML elements that override context-root in a library reference.

Table 14-3 weblogic-application.xml Elements for Overriding a Shared Jakarta EE Library

Element Description
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 (for example, 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>
   <context-root>webapp</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 Jakarta EE Libraries Deployed As a Standalone Module

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

Referencing Optional Packages from a Jakarta EE Application or Module

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

Table 14-4 Manifest Attributes for Referencing Optional Packages

Attribute Description

Extension-List logical_name [...]

Extension-List contains a space-separated list of dependency tokens.

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.

For every dependency, including a single dependency, prepend its token from Extension-List followed by a hyphen.

dependency1-Extension-Name: myOptPkg
logical_name-Specification-Version An optional numeric specification-version requirement. Select the highest specification version not below the requirement; 2.0 and 2.0.0 compare as the same version. Specification versions must use the numeric component format; 9.2BETA is invalid as a specification version. Invalid optional-package specification metadata may be warned about and ignored by the manifest parser. The optional-package reference is unresolved when no permitted provider exists; the deployment outcome follows the policy below. For every dependency, including a single dependency, prepend its token from Extension-List followed by a hyphen.
logical_name-Implementation-Version Versions such as 1.9 and 1.10 are compared as integer components, so 1.10 is higher; they are not floating-point numbers. Resolution first selects the highest permitted specification version, or the supplied exact specification when exact-match=true. It then resolves an implementation at that selected specification. When all implementations there are numeric component versions, an omitted implementation selects the highest, and a non-exact numeric requirement selects the highest not below it. For a text or mixed implementation set, specify the required implementation explicitly; a text requirement matches that exact text. An omitted implementation can select a sole text implementation, but multiple unrankable implementations leave the reference unresolved. With exact-match=true, only the version fields actually supplied are pinned. Failure at the chosen specification does not cause fallback to a lower specification. The optional-package reference is unresolved when these rules cannot be satisfied; the deployment outcome follows the policy below. For every dependency, including a single dependency, prepend its token from Extension-List followed by a hyphen. 
Manifest-Version: 1.0
Extension-List: dependency1
dependency1-Extension-Name: myOptPkg
dependency1-Specification-Version: 2.0

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, unresolved registered optional-package references produce a warning and deployment continues. To make unresolved optional-package references fail deployment, set -Dweblogic.application.RequireOptionalPackages=true on each relevant server JVM at startup. This switch controls unresolved optional-package references; it is not a library deployment command or a validator for malformed manifest attributes.

Using weblogic.appmerge to Merge Libraries

You can use weblogic.appmerge to understand a library merge by examining the merged application you have written to disk.

Use weblogic.appmerge to inspect an application with its referenced libraries merged into the output. It merges application contents and descriptors and can write the result to an archive or directory. Run it after setting the WebLogic Server development environment and preparing the application and library files.

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 14-5:

Table 14-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 Writes deployment descriptors containing information inferred from annotations.

-altappdd <file>

Uses an alternate descriptor file; supported for both application and single-module inputs.

Example:

Run this example in a work directory containing SportsApp.ear, Weather.war and Calendar.ear. The library names and versions must satisfy the references in SportsApp.ear. CompleteSportsApp.ear is the merged output. Choose an output path distinct from your input to retain the original application; without -output the tool writes to the source location.

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>

For archive-file inputs and outputs, this task can skip the merge when the output file is newer than the source file. This shortcut does not check whether referenced libraries or the deployment plan have changed. When those inputs change, remove the generated merged output before rerunning the task, or use a clean target that removes that generated output. Keep the original application and libraries separate from the generated output.

Integrating Shared Jakarta EE Libraries with the Split Development Directory Environment

You can generate a basic build.xml file in the shared Jakarta EE library directories and then build the applications in a split development directory.

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

The librarydir/library inputs make library contents available to the build tools. They do not deploy or register those libraries on a running server. Before deploying the dependent application, register its required libraries on every target server as described in Deploying Shared Jakarta EE Libraries and Dependent Applications.Deploying Shared Jakarta EE Libraries and Dependent Applications

Deploying Shared Jakarta EE Libraries and Dependent Applications

Shared Jakarta 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 Jakarta 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 Oracle WebLogic Server for more information.

See Deploying Applications the Oracle WebLogic Remote Console Online Help for detailed instructions on installing (deploying) a shared Jakarta EE library using the WebLogic Remote Console and for targeting 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 Jakarta EE library. See wldeploy Ant Task Reference, for details and examples.

Required shared-library references must resolve on every target server to a registered library meeting the reference’s version rules. Manifest optional-package references follow the warning/failure policy described in Referencing Optional Packages from a Jakarta EE Application or Module.Referencing Optional Packages from a Jakarta EE Application or Module

Web Application Shared Jakarta EE Library Information

This section describes library references from a Web application’s weblogic.xml. A Web application can reference registered WAR libraries and plain-JAR libraries. A WAR library can also be referenced by an EAR through weblogic-application.xml.

Note:

This section describes library references from a Web application’s weblogic.xml. A Web application can reference registered WAR libraries and plain-JAR libraries. A WAR library can also be referenced by an EAR through weblogic-application.xml.

In particular:

  • WAR libraries supply Web resources and classes; plain-JAR libraries supply classes.

  • 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 the same as those described in Referencing Shared Jakarta EE Libraries in an Enterprise Application; the only difference is that the <context-root> child element of <library-ref> is ignored in this case.

  • A Web application cannot use weblogic.xml to reference an EJB module library or an EAR library.

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 Jakarta EE library.

Using WebApp Libraries With Web Applications

Just as standard shared Jakarta 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 WebLogic Remote 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>

8.1beta is a text implementation identifier and must match exactly even though exact-match is false; specification selection still follows the permitted specification rule.

When multiple libraries are present, the CLASSPATH/resource path precedence order follows the order in which the library-ref elements appear in the weblogic.xml file.

Accessing Registered Shared Jakarta EE Library Information with LibraryRuntimeMBean

You can use different types of MBeans to obtain information about the shared Jakarta EE library and access the libraries that the applications use.

Each deployed shared Jakarta 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 Jakarta EE libraries referenced in the weblogic-application.xml file.

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

See the Java API Reference for Oracle WebLogic Server.

Order of Precedence of Modules When Referencing Shared Jakarta EE Libraries

When an enterprise application references one or more shared Jakarta 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 WebLogic Server internally merges the information 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 Jakarta 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 Jakarta 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 Jakarta 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 Jakarta 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 Jakarta EE Libraries

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

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

  • If you need to deploy a standalone Jakarta EE module, such as an EJB JAR file, as a shared Jakarta 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 Jakarta EE library as a standalone Jakarta 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 Jakarta 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 Jakarta EE libraries or optional packages. Classes in the /lib subdirectory are made available (through the separate domain-lib classloader) to all Jakarta EE applications running on WebLogic Server instances in the domain.

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

  • Always specify an Extension-Name value for each shared Jakarta 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 Jakarta EE library, use a unique context root. If the context root conflicts with the context root in a dependent Jakarta 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 Jakarta 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 libraries to the same targets as their consumers. Required shared-library references must resolve on every target server to a registered library meeting the reference’s version rules. Manifest optional-package references follow the warning/failure policy described in Referencing Optional Packages from a Jakarta EE Application or Module.Referencing Optional Packages from a Jakarta EE Application or Module