Downloads  |  Product Documentation  |  Support

   All Blogs Corporate Site CRM On Demand Discussion Forums Documentation Education PartnerNetwork (Public Only) Technology Network Video and Multimedia  

OTN Home      Oracle Forums      Community     

Developing Applications with WebLogic Server

Creating Shared Java EE Libraries and Optional Packages

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

Overview of Shared Java EE Libraries and Optional Packages

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

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

After the shared Java EE library has been registered, you can deploy Enterprise Applications that reference the library. Each referencing application receives a reference to the required library on deployment, and can use the modules that make up the library as if they were packaged as part of the referencing application itself. The library classes are added to the classpath of the referencing application, and the referencing application’s deployment descriptors are merged (in memory) with those of the modules that make up the shared Java EE library.

In general, this topic discusses shared Java EE libraries that can be referenced only by Enterprise Applications. You can also create libraries that can be referenced only by another Web application. The functionality is very similar to application libraries, although the method of referencing them is slightly different. See Web Application Shared Java EE Library Information for details.

Optional Packages

WebLogic Server supports optional packages as described in the Java EE 5.0 Specification, Section 8.2 Optional Package Support, with versioning described in Optional Package Versioning. 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).

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:

As a best practice, Oracle recommends that you always include version information (an implementation version, or both an implementation and specification version) when creating shared Java EE libraries. Creating and updating version information as you develop shared components allows you to deploy multiple versions of those components simultaneously for testing. If you include no version information, or fail to increment the version string, then you must undeploy existing libraries before you can deploy the newer one. See Deploying Shared Java EE Libraries and Dependent Applications.

Versioning information in the referencing application determines the library and package version requirements for that application. Different applications can require different versions of a given library or package. For example, a production application may require a specific version of a library, because only that library has been fully approved for production use. An internal application may be configured to always use a minimum version of the same library. Applications that require no specific version can be configured to use the latest version of the library. Referencing Shared Java EE Libraries in an Enterprise Application.

Shared Java EE Libraries and Optional Packages Compared

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

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

In general, use shared Java EE libraries when you need to share one or more EJB, Web Application or Enterprise Application modules among different Enterprise Applications. Use optional packages when you need to share one or more classes (packaged in a JAR file) among different Java EE modules.

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

Use shared Java EE libraries to share a plain JAR file if you only need to reference the JAR file from one or more Enterprise Applications, and you do not need to maintain strict compliance with the Java EE specification.

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

Creating Shared Java EE Libraries

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

Assembling Shared Java EE Library Files

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

Shared Java EE libraries have the following restrictions:

Oracle recommends packaging shared Java EE libraries as Enterprise Applications, rather than as standalone Java EE modules. This is because the URI of a standalone module is derived from the deployment name, which can change depending on how the module is deployed. By default, WebLogic Server uses the deployment archive filename or exploded archive directory name as the deployment name. If you redeploy a standalone shared Java EE library from a different file or location, the deployment name and URI also change, and referencing applications that use the wrong URI cannot access the deployed library.

If you choose to deploy a shared Java EE library as a standalone Java EE module, always specify a known deployment name during deployment and use that name as the URI in referencing applications.

Assembling Optional Package Class Files

Any set of classes can be organized into an optional package file. The collection of shared classes will eventually be packaged into a standard JAR archive. However, because you will need to edit the manifest file for the JAR, begin by assembling all class files into a working directory:

Editing Manifest Attributes for Shared Java EE Libraries

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

To specify attributes in a manifest file:

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 and Packaging from a Split Development Directory.

Because a shared Java EE library is packaged as a standard Java EE application or standalone module, you may also choose to export a library’s deployment configuration to a deployment plan, as described in Deploying Applications to WebLogic Server. Optional package .JAR files contain no deployment descriptors and cannot be exported.

For development purposes, you may choose to deploy libraries as exploded archive directories to facilitate repeated updates and redeployments.

Referencing Shared Java EE Libraries in an Enterprise Application

A Java EE application can reference a registered shared Java EE library using entries in the application’s weblogic-application.xml deployment descriptor. Table 9-2 describes the XML elements that define a library reference.

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

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

In the above example, WebLogic Server attempts to find a library name myLibrary when deploying the dependent application. If more than one copy of myLibrary is registered, WebLogic Server selects the library with the highest specification version. If multiple copies of the library use the selected specification version, WebLogic Server selects the copy having the highest implementation version.

This example references a shared Java EE library with a requirement for the specification version:

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

In the above example, WebLogic Server looks for matching libraries having a specification version of 2.0 or higher. If multiple libraries are at or above version 2.0, WebLogic Server examines the selected libraries that use Float values for their implementation version and selects the one with the highest version. Note that WebLogic Server ignores any selected libraries that have a non-Float value for the implementation version.

This example references a shared Java EE library with both a specification version and a non-Float value implementation version:

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

In the above example, WebLogic Server searches for a library having a specification version of 2.0 or higher, and having an exact match of 81Beta for the implementation version.

The following example requires an exact match for both the specification and implementation versions:

<library-ref>
   <library-name>myLibrary</library-name>
   <specification-version>2.0</specification-version>
   <implementation-version>8.1</implementation-version>
   <exact-match>true</exact-match>
</library-ref>

The following example specifies a context-root-override, which in turn, refers to the old context-root specified in one of its libraries and the new context-root that should be used instead. (override):

<library-ref>
   <library-name>myLibrary</library-name>
   <library-context-root-override>
   <library-context-root>webapp</library-context-root>
   <override-value>mywebapp</override-value>
   </library-context-root-override>
</library-ref>

Overriding context-roots Within a Referenced Enterprise Library

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

The following example specifies a context-root-override, which in turn, refers to the old context-root specified in one of its libraries and the new context-root that should be used instead. (override):

<library-ref>
   <library-name>myLibrary</library-name>
   <specification-version>2.0</specification-version>
   <implementation-version>8.1</implementation-version>
   <exact-match>true</exact-match>

</library-ref>

<library-context-root-override>
   <library-context-root>webapp</library-context-root>
   <override-value>mywebapp</override-value>
</library-context-root-override>

In the above example, the current application refers to myLibrary, which contains a Web application with a context-root of webapp. The only way to override this reference is to declare a library-context-root-override that maps webapp to mywebapp.

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.

For example, this simple entry in the manifest file for a dependent archive references two optional packages, myAppPkg and my3rdPartyPkg:

Extension-List: internal 3rdparty
internal-Extension-Name: myAppPkg
3rdparty-Extension-Name: my3rdPartyPkg

This example requires a specification version of 2.0 or higher for myAppPkg:

Extension-List: internal 3rdparty
internal-Extension-Name: myAppPkg
3rdparty-Extension-Name: my3rdPartyPkg
internal-Specification-Version: 2.0

This example requires a specification version of 2.0 or higher for myAppPkg, and an exact match for the implementation version of my3rdPartyPkg:

Extension-List: internal 3rdparty
internal-Extension-Name: myAppPkg
3rdparty-Extension-Name: my3rdPartyPkg
internal-Specification-Version: 2.0
3rdparty-Implementation-Version: 8.1GA

By default, when WebLogic Server deploys an application or module and it cannot resolve a reference in the application’s manifest file to an optional package, WebLogic Server prints a warning, but continues with the deployment anyway. You can change this behavior by setting the system property weblogic.application.RequireOptionalPackages to true when you start WebLogic Server, either at the command line or in the command script file from which you start the server. Setting this system property to true means that WebLogic Server does not attempt to deploy an application or module if it cannot resolve an optional package reference in its manifest file.

Using weblogic.appmerge to Merge Libraries

weblogic.appmerge is a tool that is used to merge libraries into an application, with merged contents and merged descriptors. It also has the ability to write a merged application to disk. You can then use weblogic.appmerge to understand a library merge by examining the merged application you have written to disk.

Using weblogic.appmerge from the CLI

Invoke weblogic.appmerge using the following syntax:

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

where valid options are shown in Table 9-5:

Example:

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

Using weblogic.appmerge as an Ant Task

The ant task provides similar functionality as the command line utility. It supports source, output, libraryDir, plan and verbose attributes as well as multiple <library> sub-elements. Here is an example:

<taskdef name="appmerge" classname="weblogic.ant.taskdefs.j2ee.AppMergeTask"/>
<appmerge source="SportsApp.ear" output="CompleteSportsApp.ear">
   <library file="Weather.war"/>
   <library file="Calendar.ear"/>
</appmerge>

Integrating Shared Java EE Libraries with the Split Development Directory Environment

The BuildXMLGen includes a -librarydir option to generate build targets that include one or more shared Java EE library directories. See Generating a Basic build.xml File Using weblogic.BuildXMLGen.

The wlcompile and wlappc Ant tasks include a librarydir attribute and library element to specify one or more shared Java EE library directories to include in the classpath for application builds. See Building Applications in a Split Development Directory.

Deploying Shared Java EE Libraries and Dependent Applications

Shared Java EE libraries are registered with one or more WebLogic Server instances by deploying them to the target servers and indicating that the deployments are to be shared. Shared Java EE libraries must be targeted to the same WebLogic Server instances you want to deploy applications that reference the libraries. If you try to deploy a referencing application to a server instance that has not registered a required library, deployment of the referencing application fails. See Registering Libraries with WebLogic Server in Deploying Applications to WebLogic Server for more information.

See Install a Java EE Library for detailed instructions on installing (deploying) a shared Java EE library using the Administration Console. See Target a Shared Java EE Library to a Server or Cluster for instructions on using the Administration Console to target the library to the server or cluster to which the application that is referencing the library is also targeted.

If you use the wldeploy Ant task as part of your iterative development process, use the library, libImplVer, and libSpecVer attributes to deploy a shared Java EE library. See wldeploy Ant Task Reference, for details and examples.

After registering a shared Java EE library, you can deploy applications and archives that depend on the library. Dependent applications can be deployed only if the target servers have registered all required libraries, and the registered deployments meet the version requirements of the application or archive. See Deploying Applications that Reference Libraries in Deploying Applications to WebLogic Server for more information.

Web Application Shared Java EE Library Information

In general, this topic discusses shared Java EE libraries that can be referenced only by Enterprise Applications. You can also create libraries that can be referenced only by another Web application. The functionality is very similar to application libraries, although the method of referencing them is slightly different.

In particular:

Other than these differences in how they are referenced, the way to create, package, and deploy a Web application library is the same as that of a standard shared Java EE library.

Using WebApp Libraries With Web Applications

Just as standard shared Java EE applications can be deployed to WebLogic Server as application-libraries, a standard Web application can be deployed to WebLogic Server as a webapp-library so that other Web applications can refer to these libraries.

Web application libraries facilitate the reuse of code and resources. Such libraries also help you separate out third-party Web applications or frameworks that your Web application might be using. Furthermore, common resources can be packaged separately as libraries and referenced in different Web applications, so that you don’t have to bundle them with each Web application. When you include a webapp-library in your Web application, at deployment time the container merges all the static resources, classes, and JAR files into your Web application.

The first step in using a WebApp library is to register a Web application as a webapp-library. This can be accomplished by deploying a Web application using either the Administration Console or the weblogic.Deployer tool as a library. To make other Web applications refer to this library, their weblogic.xml file must have a library-ref element pointing to the webapp-library, as follows:

  <library-ref>
  <library-name>BaseWebApp</library-name>
  <specification-version>2.0</specification-version>
  <implementation-version>8.1beta</implementation-version>
  <exact-match>false</exact-match>
  </library-ref>

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

Accessing Registered Shared Java EE Library Information with LibraryRuntimeMBean

Each deployed shared Java EE library is represented by a LibraryRuntimeMBean. You can use this MBean to obtain information about the library itself, such as its name or version. You can also obtain the ApplicationRuntimeMBeans associated with deployed applications. ApplicationRuntimeMBean provides two methods to access the libraries that the application is using:

For more information, see the WebLogic Server API Reference.

Order of Precedence of Modules When Referencing Shared Java EE Libraries

When an Enterprise Application references one or more shared Java EE libraries, and the application is deployed to WebLogic Server, the server internally merges the information in the weblogic-application.xml file of the referencing Enterprise Application with the information in the deployment descriptors of the referenced libraries. The order in which this happens is as follows:

As a result of the way the descriptor files are merged, the elements in the descriptors of the shared Java EE libraries referenced first in the weblogic-application.xml file have precedence over the ones listed last. The elements of the Enterprise application’s descriptor itself have precedence over all elements in the library descriptors.

For example, assume that an Enterprise application called myApp references two shared Java EE libraries (themselves packaged as Enterprise applications): myLibA and myLibB, in that order. Both the myApp and myLibA applications include an EJB module called myEJB, and both the myLibA and myLibB applications include an EJB module called myOtherEJB.

Further assume that once the myApp application is deployed, a client invokes, via the myApp application, the myEJB module. In this case, WebLogic Server actually invokes the EJB in the myApp application (rather than the one in myLibA) because modules in the referencing application have higher precedence over modules in the referenced applications. If a client invokes the myOtherEJB EJB, then WebLogic Server invokes the one in myLibA, because the library is referenced first in the weblogic-application.xml file of myApp, and thus has precedence over the EJB with the same name in the myLibB application.

Best Practices for Using Shared Java EE Libraries

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

Copyright © 1994, 2016, Oracle and/or its affiliates. All rights reserved.