12 Creating Shared Java EE Libraries and Optional Packages
This chapter includes the following sections:
-
Referencing Shared Java EE Libraries in an Enterprise Application
-
Referencing Optional Packages from a Java EE Application or Module
-
Integrating Shared Java EE Libraries with the Split Development Directory Environment
-
Deploying Shared Java EE Libraries and Dependent Applications
-
Accessing Registered Shared Java EE Library Information with LibraryRuntimeMBean
-
Order of Precedence of Modules When Referencing Shared Java EE Libraries
- 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 libraries can be referenced by enterprise applications and you can also create libraries that can be referenced only by another Web application. - Creating Shared Java EE Libraries
You can deploy the Java EE modules such as an EJB, a Web application, an enterprise application, a plain Java class, and others as a shared Java EE library. These modules can be shared among multiple enterprise applications in WebLogic Server. - 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'sweblogic-application.xml
deployment descriptor. - 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. - Using weblogic.appmerge to Merge Libraries
You can useweblogic.appmerge
to understand a library merge by examining the merged application you have written to disk. - Integrating Shared Java EE Libraries with the Split Development Directory Environment
You can generate a basic build.xml file in the shared Java EE library directories and then build the 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. - Web Application Shared Java EE Library Information
Some of the shared Java EE libraries 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. - Using WebApp Libraries With Web Applications
Just as standard shared Java EE applications can be deployed to WebLogic Server asapplication-libraries
, a standard Web application can be deployed to WebLogic Server as awebapp-library
so that other Web applications can refer to these libraries. - Accessing Registered Shared Java EE Library Information with LibraryRuntimeMBean
You can use different types of MBeans to obtain information about the shared Java EE library and access the libraries that the applications use. - 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 theweblogic-application.xml
file of the referencing enterprise application with the information in the deployment descriptors of the referenced libraries. - Best Practices for Using Shared Java EE Libraries
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 libraries can be referenced by enterprise applications and you can also create libraries that can be referenced only by another Web application.
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 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 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 Domain /lib Directory.
- Optional Packages
- Library Directories
- Versioning Support for Libraries
- Shared Java EE Libraries and Optional Packages Compared
- Additional Information
Parent topic: Creating Shared Java EE Libraries and Optional Packages
Optional Packages
WebLogic Server supports optional packages as described at http://docs.oracle.com/javase/6/docs/technotes/guides/extensions/extensions.html
with versioning described in Optional Package Versioning (see http://docs.oracle.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://docs.oracle.com/javase/7/docs/technotes/guides/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 (usingweblogic-application.xml
orweblogic.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 Deploying Applications to Oracle WebLogic Server.
Creating Shared Java EE Libraries
You can deploy the Java EE modules such as an EJB, a Web application, an enterprise application, a plain Java class, and others as a shared Java EE library. These modules can be shared among multiple enterprise applications in WebLogic Server.
To create a new shared Java EE library:
- Assembling Shared Java EE Library Files
- Assembling Optional Package Class Files
- Editing Manifest Attributes for Shared Java EE Libraries
- Packaging Shared Java EE Libraries for Distribution and Deployment
Parent topic: Creating Shared Java EE Libraries and Optional Packages
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 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.
Parent topic: Creating Shared Java EE Libraries
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:
Parent topic: Creating Shared Java EE Libraries
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 12-1 describes the valid shared Java EE library manifest attributes.
Table 12-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 As a best practice, always specify an |
Specification-Version |
An optional String value that defines the specification version of the shared Java EE library. Referencing applications can optionally specify a required The 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
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:
Parent topic: Creating Shared Java EE Libraries
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 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.
Parent topic: Creating Shared Java EE Libraries
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 12-2 describes the XML elements that define a library reference.
Table 12-2 weblogic-application.xml Elements for Referencing a Shared Java EE Library
Element | Description |
---|---|
|
|
library-name |
A required string value that specifies the name of the shared Java EE library to use. |
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 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 |
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 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 |
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 |
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
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
- URIs for Shared Java EE Libraries Deployed As a Standalone Module
Parent topic: Creating Shared Java EE Libraries and Optional Packages
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 12-3 describes the XML elements that override context-root
in a library reference.
Table 12-3 weblogic-application.xml Elements for Overriding a Shared Java EE Library
Element | Description |
---|---|
context-root |
An optional String value that overrides the Only a referencing application (for example, a user application) can override the |
override-value |
An optional String value that specifies the value of the |
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 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 12-4 Manifest Attributes for Referencing Optional Packages
Attribute | Description |
---|---|
|
A required String value that defines a logical name
for an optional package dependency. You can use multiple values in
the 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 If you are referencing multiple optional packages from a single archive, prepend the appropriate logical name to the
|
[ 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 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 If you are referencing multiple optional packages from a single archive, prepend the appropriate logical name to the |
[ 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 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 If you are referencing multiple optional packages from a single archive, prepend the appropriate logical name to the |
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.
Parent topic: Creating Shared Java EE Libraries and Optional Packages
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.
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.
Parent topic: Creating Shared Java EE Libraries and Optional Packages
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 12-5:
Table 12-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:
|
-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
Parent topic: Using weblogic.appmerge to Merge Libraries
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>
Parent topic: Using weblogic.appmerge to Merge Libraries
Integrating Shared Java EE Libraries with the Split Development Directory Environment
You can generate a basic build.xml file in the shared Java 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 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.
Parent topic: Creating Shared Java EE Libraries and Optional Packages
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 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 WebLogic Server Administration Console. See Target a Shared Java EE Library to a Server or Cluster for instructions on using the WebLogic Server Administration Console to target the library to the server or cluster to which the application that is referencing the library is also targeted.
If you use the wldeploy
Ant task as part of your iterative development process, use the library
, libImplVer
, and libSpecVer
attributes to deploy a shared Java EE library. See wldeploy Ant Task Reference, for details and examples.
After registering a shared Java EE library, you can deploy applications and archives that depend on the library. Dependent applications can be deployed only if the target servers have registered all required libraries, and the registered deployments meet the version requirements of the application or archive. See Deploying Applications that Reference Libraries in Deploying Applications to Oracle WebLogic Server for more information.
Parent topic: Creating Shared Java EE Libraries and Optional Packages
Web Application Shared Java EE Library Information
Some of the shared Java EE libraries 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 theweblogic.xml
deployment descriptor file. The elements are almost the 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.
Parent topic: Creating Shared Java EE Libraries and Optional Packages
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 WebLogic Server 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.
Parent topic: Creating Shared Java EE Libraries and Optional Packages
Accessing Registered Shared Java EE Library Information with LibraryRuntimeMBean
You can use different types of MBeans to obtain information about the shared Java EE library and access the libraries that the applications use.
Each deployed shared Java EE library is represented by a LibraryRuntimeMBean
. You can use this MBean to obtain information about the library itself, such as its name or version. You can also obtain the ApplicationRuntimeMBean
s associated with deployed applications. ApplicationRuntimeMBean
provides two methods to access the libraries that the application is using:
-
getLibraryRuntimes()
returns the shared Java EE libraries referenced in theweblogic-application.xml
file. -
getOptionalPackageRuntimes()
returns the optional packages referenced in the manifest file.
Parent topic: Creating Shared Java EE Libraries and Optional Packages
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 WebLogic Server internally merges the information is as follows:
-
When the enterprise application is deployed, WebLogic Server reads its
weblogic-application.xml
deployment descriptor. -
WebLogic Server reads the deployment descriptors of any referenced shared 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. -
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.
Parent topic: Creating Shared Java EE Libraries and Optional Packages
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 made available (within a separate system level classloader) to all Java 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 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'sweblogic-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.
Parent topic: Creating Shared Java EE Libraries and Optional Packages