PK
%J1Eoa, mimetypeapplication/epub+zipPK %J1E iTunesMetadata.plisth
This chapter describes how to share components and classes among applications using shared Java EE libraries and optional packages supported in WebLogic Server.
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
The shared Java EE library feature in WebLogic Server provides an easy way to share one or more different types of Java EE modules among multiple enterprise applications. A shared Java EE library is a single module or collection of modules that is registered with the Java EE application container upon deployment. A shared Java EE library can be any of the following:
standalone EJB module
standalone Web application module
multiple EJB modules packaged in an enterprise application
multiple Web application modules package in an enterprise application
single plain JAR file
Oracle recommends that you package a shared Java EE library into its appropriate archive file (EAR, JAR, or WAR). However, for development purposes, you may choose to deploy shared Java EE libraries as exploded archive directories to facilitate repeated updates and redeployments.
After the shared Java EE library has been registered, you can deploy enterprise applications that reference the library. Each referencing application receives a reference to the required library on deployment, and can use the modules that make up the library as if they were packaged as part of the referencing application itself. The library classes are added to the classpath of the referencing application, and the referencing application's deployment descriptors are merged (in memory) with those of the modules that make up the shared Java EE library.
In general, this topic discusses shared Java EE libraries that can be referenced only by enterprise applications. You can also create libraries that can be referenced only by another Web application. The functionality is very similar to application libraries, although the method of referencing them is slightly different. See Web Application Shared Java EE Library Information for details.
Note: WebLogic Server also provides a simple way to add one or more JAR files to the WebLogic Server System classpath, using the |
WebLogic Server supports optional packages as described at http://docs.oracle.com/javase/7/docs/technotes/guides/extensions/extensions.html
with versioning described in Optional Package Versioning (see http://docs.oracle.com/javase/7/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. |
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.
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.
Optional packages and shared Java EE libraries have the following features in common:
Both are registered with WebLogic Server instances at deployment time.
Both support an optional implementation version and specification version string.
Applications that reference shared Java EE libraries and optional packages can specify required versions for the shared files.
Optional packages can reference other optional packages, and shared Java EE libraries can reference other shared Java EE libraries.
Optional packages differ from shared Java EE Libraries in the following basic ways:
Optional packages are plain JAR files, whereas shared Java EE libraries can be plain JAR files, Java EE enterprise applications, or standalone Java EE modules (EJB and Web applications). This means that libraries can have valid Java EE and WebLogic Server deployment descriptors. Any deployment descriptors in an optional package JAR file are ignored.
Any Java EE application or module can reference an optional package (using META-INF/MANIFEST.MF
), whereas only enterprise applications and Web applications can reference a shared Java EE library (using weblogic-application.xml
or weblogic.xml
).
In general, use shared Java EE libraries when you need to share one or more EJB, Web application or enterprise application modules among different enterprise applications. Use optional packages when you need to share one or more classes (packaged in a JAR file) among different Java EE modules.
Plain JAR files can be shared either as libraries or optional packages. Use optional packages if you want to:
Share a plain JAR file among multiple Java EE modules
Reference shared JAR files from other shared JARs
Share plain JARs as described by the Java EE 5.0 specification
Use shared Java EE libraries to share a plain JAR file if you only need to reference the JAR file from one or more enterprise applications, and you do not need to maintain strict compliance with the Java EE specification.
Note: Oracle documentation and WebLogic Server utilities use the term shared Java EE library to refer to both libraries and optional packages. Optional packages are called out only when necessary. |
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.
To create a new shared Java EE library that you can share with multiple applications:
Assemble the shared Java EE library into a valid, deployable Java EE module or enterprise application. The library must have the required Java EE deployment descriptors for the Java EE module or for an enterprise application.
Assemble optional package classes into a working directory.
Create and edit the MANIFEST.MF
file for the shared Java EE library to specify the name and version string information.
See Editing Manifest Attributes for Shared Java EE Libraries.
Package the shared Java EE library for distribution and deployment.
See Packaging Shared Java EE Libraries for Distribution and Deployment.
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.
Any set of classes can be organized into an optional package file. The collection of shared classes will eventually be packaged into a standard JAR archive. However, because you will need to edit the manifest file for the JAR, begin by assembling all class files into a working directory:
Create a working directory for the new optional package. For example:
mkdir /apps/myOptPkg
Copy the compiled class files into the working directory, creating the appropriate package sudirectories as necessary. For example:
mkdir -p /apps/myOptPkg/org/myorg/myProduct cp /build/classes/myOptPkg/org/myOrg/myProduct/*.class /apps/myOptPkg/org/myOrg/myProduct
If you already have a JAR file that you want to use as an optional package, extract its contents into the working directory so that you can edit the manifest file:
cd /apps/myOptPkg jar xvf /build/libraries/myLib.jar
The name and version information for a shared Java EE library are specified in the META-INF/MANIFEST.MF
file. Table 11-1 describes the valid shared Java EE library manifest attributes.
Table 11-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:
Open (or create) the manifest file using a text editor. For the example shared Java EE library, you would use the commands:
cd /apps/myLibrary mkdir META-INF emacs META-INF/MANIFEST.MF
For the optional package example, use:
cd /apps/myOptPkg mkdir META-INF emacs META-INF/MANIFEST.MF
In the text editor, add a string value to specify the name of the shared Java EE library. For example:
Extension-Name: myExtension
Applications that reference the library must specify the exact Extension-Name
in order to use the shared files.
As a best practice, enter the optional version information for the shared Java EE library. For example:
Extension-Name: myExtension Specification-Version: 2.0 Implementation-Version: 9.0.0
Using the major/minor format for the version identifiers provides the most flexibility when referencing the library from another application (see Table 11-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 |
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.
A Java EE application can reference a registered shared Java EE library using entries in the application's weblogic-application.xml
deployment descriptor. Table 11-2 describes the XML elements that define a library reference.
Table 11-2 weblogic-application.xml Elements for Referencing a Shared Java EE Library
Element | Description |
---|---|
library-ref |
|
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>
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 11-3 describes the XML elements that override context-root
in a library reference.
Table 11-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
.
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.
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 11-4 Manifest Attributes for Referencing Optional Packages
Attribute | Description |
---|---|
Extension-List |
A required String value that defines a logical name for an optional package dependency. You can use multiple values in the
|
|
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
|
|
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 |
|
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.
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.
Invoke weblogic.appmerge
using the following syntax:
java weblogic.appmerge [options] <ear, jar, war file, or directory>
where valid options are shown in Table 11-5:
Table 11-5 weblogic.appmerge Options
Option | Comment |
---|---|
-help |
Print the standard usage message. |
-version |
Print version information. |
-output <file> |
Specifies an alternate output archive or directory. If not set, output is placed in the source archive or directory. |
-plan <file> |
Specifies an optional deployment plan. |
-verbose |
Provide more verbose output. |
-library <file> |
Comma-separated list of libraries. Each library may optionally set its name and versions, if not already set in its manifest, using the following syntax: <file> [@name=<string>@libspecver=<version> @libimplver=<version|string>]. |
-librarydir <dir> |
Registers all files in specified directory as libraries. |
-writeInferredDescriptors |
Specifies that the application or module contains deployment descriptors with annotation information. |
Example:
$ java weblogic.appmerge -output CompleteSportsApp.ear -library Weather.war,Calendar.ear SportsApp.ear
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>
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.
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 Administration Console. See "Target a Shared Java EE Library to a Server or Cluster" for instructions on using the Administration Console to target the library to the server or cluster to which the application that is referencing the library is also targeted.
If you use the wldeploy
Ant task as part of your iterative development process, use the library
, libImplVer
, and libSpecVer
attributes to deploy a shared Java EE library. See Appendix B, "wldeploy Ant Task Reference," for details and examples.
After registering a shared Java EE library, you can deploy applications and archives that depend on the library. Dependent applications can be deployed only if the target servers have registered all required libraries, and the registered deployments meet the version requirements of the application or archive. See "Deploying Applications that Reference Libraries" in Deploying Applications to Oracle WebLogic Server for more information.
In general, this topic discusses shared Java EE libraries that can be referenced only by enterprise applications. You can also create libraries that can be referenced only by another Web application. The functionality is very similar to application libraries, although the method of referencing them is slightly different.
Note: For simplicity, this section uses the term Web application library when referring to a shared Java EE library that is referenced only by another Web application. |
In particular:
Web application libraries can only be referenced by other Web applications.
Rather than update the weblogic-application.xml
file, Web applications reference Web application libraries by updating the weblogic.xml
deployment descriptor file. The elements are almost 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.
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.
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 the weblogic-application.xml
file.
getOptionalPackageRuntimes()
returns the optional packages referenced in the manifest file.
For more information, see the Java API Reference for Oracle WebLogic Server.
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:
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.
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's weblogic-application.xml
deployment descriptor to override the library's context root.
Package shared Java EE libraries as archive files for delivery to administrators or deployers in your organization. Deploy libraries from exploded archive directories during development to allow for easy updates and repeated redeployments.
Deploy shared Java EE libraries to all WebLogic Server instances on which you want to deploy dependent applications and archives. If a library is not registered with a server instance on which you want to deploy a referencing application, deployment of the referencing application fails.
This chapter describes how to use threads in WebLogic Server as well as how to program applications for use in WebLogic Server clusters.
This chapter includes the following sections:
WebLogic Server is a sophisticated, multi-threaded application server and it carefully manages resource allocation, concurrency, and thread synchronization for the modules it hosts. To obtain the greatest advantage from WebLogic Server's architecture, construct your application modules created according to the standard Java EE APIs.
In most cases, avoid application designs that require creating new threads in server-side modules:
Applications that create their own threads do not scale well. Threads in the JVM are a limited resource that must be allocated thoughtfully. Your applications may break or cause WebLogic Server to thrash when the server load increases. Problems such as deadlocks and thread starvation may not appear until the application is under a heavy load.
Multithreaded modules are complex and difficult to debug. Interactions between application-generated threads and WebLogic Server threads are especially difficult to anticipate and analyze.
In some situations, creating threads may be appropriate, in spite of these warnings. For example, an application that searches several repositories and returns a combined result set can return results sooner if the searches are done asynchronously using a new thread for each repository instead of synchronously using the main client thread.
If you must use threads in your application code, create a pool of threads so that you can control the number of threads your application creates. Like a JDBC connection pool, you allocate a given number of threads to a pool, and then obtain an available thread from the pool for your runnable class. If all threads in the pool are in use, wait until one is returned. A thread pool helps avoid performance issues and allows you to optimize the allocation of threads between WebLogic Server execution threads and your application.
Be sure you understand where your threads can deadlock and handle the deadlocks when they occur. Review your design carefully to ensure that your threads do not compromise the security system.
To avoid undesirable interactions with WebLogic Server threads, do not let your threads call into WebLogic Server modules. For example, do not use enterprise beans or servlets from threads that you create. Application threads are best used for independent, isolated tasks, such as conversing with an external service with a TCP/IP connection or, with proper locking, reading or writing to files. A short-lived thread that accomplishes a single purpose and ends (or returns to the thread pool) is less likely to interfere with other threads.
Avoid creating daemon threads in modules that are packaged in applications deployed on WebLogic Server. When you create a daemon thread in an application module such as a servlet, you will not be able to redeploy the application because the daemon thread created in the original deployment will remain running.
Be sure to test multithreaded code under increasingly heavy loads, adding clients even to the point of failure. Observe the application performance and WebLogic Server behavior and then add checks to prevent failures from occurring in production.
The Work Manager provides a simple API for concurrent execution of work items. This enables Java EE-based applications (including servlets and EJBs) to schedule work items for concurrent execution, which will provide greater throughput and increased response time. After an application submits work items to a Work Manager for concurrent execution, the application can gather the results. The Work Manager provides common "join" operations, such as waiting for any or all work items to complete. The Work Manager for Application Servers specification provides an application-server-supported alternative to using lower-level threading APIs, which are inappropriate for use in managed environments such as servlets and EJBs, as well as being too difficult to use for most applications.
For more information, see "Using Work Managers to Optimize Scheduled Work".
JSPs and servlets that will be deployed to a WebLogic Server cluster must observe certain requirements for preserving session data. See "Requirements for HTTP Session State Replication" in Administering Clusters for Oracle WebLogic Server for more information.
EJBs deployed in a WebLogic Server cluster have certain restrictions based on EJB type. See "Understanding WebLogic Enterprise JavaBeans" in Developing Enterprise JavaBeans, Version 2.1, for Oracle WebLogic Serverfor information about the capabilities of different EJB types in a cluster. EJBs can be deployed to a cluster by setting clustering properties in the EJB deployment descriptor.
If you are developing either EJBs or custom RMI objects for deployment in a cluster, also refer to "Using WebLogic JNDI in a Clustered Environment" in Developing JNDI Applications for Oracle WebLogic Server to understand the implications of binding clustered objects in the JNDI tree.
This chapter provides an overview of WebLogic Server applications and basic concepts.
This chapter includes the following sections:
This document is written for application developers who want to build WebLogic Server e-commerce applications using the Java Platform, Enterprise Edition 6. It is assumed that readers know Web technologies, object-oriented programming techniques, and the Java programming language.
WebLogic Server applications are created by Java programmers, Web designers, and application assemblers. Programmers and designers create modules that implement the business and presentation logic for the application. Application assemblers assemble the modules into applications that are ready to deploy on WebLogic Server.
WebLogic Server implements Java Platform, Enterprise Edition (Java EE) Version 6.0 technologies (see http://www.oracle.com/technetwork/java/javaee/overview/index.html
). Java EE is the standard platform for developing multi-tier enterprise applications based on the Java programming language. The technologies that make up Java EE were developed collaboratively by several software vendors.
An important aspect of the Java EE programming model is the introduction of metadata annotations. Annotations simplify the application development process by allowing a developer to specify within the Java class itself how the application component behaves in the container, requests for dependency injection, and so on. Annotations are an alternative to deployment descriptors that were required by older versions of enterprise applications (Java EE 1.4 and earlier).
Starting in Java EE 5 and continuing in Java EE 6, the focus has been ease of development. There is less code to write – much of the boilerplate code has been removed, defaults are used whenever possible, and annotations are used extensively to reduce the need for deployment descriptors.
EJB 3.1 provides simplified programming and packaging model changes. The mandatory use of Java interfaces from previous versions has been removed, allowing plain old Java objects to be annotated and used as EJB components. The simplification is further enhanced through the ability to place EJB modules directly inside of Web applications, removing the need to produce archives to store the Web and EJB components and combine them together in an EAR file.
Java EE 6 includes simplified Web services support and the latest Web services APIs, making it an ideal implementation platform for Service-Oriented Architectures (SOA).
Constructing Web applications is made easier with JavaServer Faces (JSF) technology and the JSP Standard Tag Library (JSTL). Java EE 6 supports rich thin-client technologies such as AJAX, for building applications for Web 2.0.
WebLogic Server Java EE applications are based on standardized, modular components. WebLogic Server provides a complete set of services for those modules and handles many details of application behavior automatically, without requiring programming. Java EE defines module behaviors and packaging in a generic, portable way, postponing run-time configuration until the module is actually deployed on an application server.
Java EE includes deployment specifications for Web applications, EJB modules, Web services, enterprise applications, client applications, and connectors. Java EE does not specify how an application is deployed on the target server—only how a standard module or application is packaged. For each module type, the specifications define the files required and their location in the directory structure.
Java is platform independent, so you can edit and compile code on any platform, and test your applications on development WebLogic Servers running on other platforms. For example, it is common to develop WebLogic Server applications on a PC running Windows or Linux, regardless of the platform where the application is ultimately deployed.
For more information, refer to the Java EE specification at: http://www.oracle.com/technetwork/java/javaee/tech/index-jsp-142185.html
.
A WebLogic Server Java EE application consists of one of the following modules or applications running on WebLogic Server:
Web application modules—HTML pages, servlets, JavaServer Pages, and related files. See Web Application Modules.
Enterprise JavaBeans (EJB) modules—entity beans, session beans, and message-driven beans. See Enterprise JavaBean Modules.
Connector modules—resource adapters. See Connector Modules.
Enterprise applications—Web application modules, EJB modules, resource adapters and Web services packaged into an application. See Enterprise Applications.
Web services—See WebLogic Web Services.
A WebLogic application can also include the following WebLogic-specific modules:
JDBC and JMS modules—See JMS and JDBC Modules.
WebLogic Diagnostic FrameWork (WLDF) modules—See WebLogic Diagnostic Framework Modules.
Coherence Grid Archive (GAR) Modules—See Coherence Grid Archive (GAR) Modules.
A Web application on WebLogic Server includes the following files:
At least one servlet or JSP, along with any helper classes.
Optionally, a web.xml
deployment descriptor, a Java EE standard XML document that describes the contents of a WAR file.
Optionally, a weblogic.xml
deployment descriptor, an XML document containing WebLogic Server-specific elements for Web applications.
A Web application can also include HTML and XML pages with supporting files such as images and multimedia files.
Servlets are Java classes that execute in WebLogic Server, accept a request from a client, process it, and optionally return a response to the client. An HttpServlet
is most often used to generate dynamic Web pages in response to Web browser requests.
JavaServer Pages (JSPs) are Web pages coded with an extended HTML that makes it possible to embed Java code in a Web page. JSPs can call custom Java classes, known as tag libraries, using HTML-like tags. The appc
compiler compiles JSPs and translates them into servlets. WebLogic Server automatically compiles JSPs if the servlet class file is not present or is older than the JSP source file. See Building Modules and Applications Using wlappc.
You can also precompile JSPs and package the servlet class in a Web application (WAR) file to avoid compiling in the server. Servlets and JSPs may require additional helper classes that must also be deployed with the Web application.
Enterprise JavaBeans (EJB) 3.1 technology is the server-side component architecture for the development and deployment of component-based business applications. EJB technology enables rapid and simplified development of distributed, transactional, secure, and portable applications based on Java EE 6 technology.
The EJB 3.1 specification provides simplified programming and packaging model changes. The mandatory use of Java interfaces from previous versions has been removed, allowing plain old Java objects to be annotated and used as EJB components. The simplification is further enhanced through the ability to place EJB modules directly inside of Web applications, removing the need to produce archives to store the Web and EJB components and combine them together in an EAR file.
For more information about using EJBs with WebLogic Server, see:
For information about all the new features in EJB 3.1, see "Enterprise Java Beans (EJBs)" in What's New in Oracle WebLogic Server.
For information about basic EJB concepts and components, see "Enterprise Java Beans (EJBs)" in Understanding Oracle WebLogic Server.
For instructions on how to program, package, and deploy 3.1 EJBs on WebLogic Server, see Developing Enterprise JavaBeans for Oracle WebLogic Server.
For instructions on how to organize and build WebLogic Server EJBs in a split directory environment, see Developing Applications for Oracle WebLogic Server.
For more information on how to program and package 2.x EJBs, see Developing Enterprise JavaBeans, Version 2.1, for Oracle WebLogic Server.
To learn more about EJB concepts, such as the benefits of enterprise beans, the types of enterprise beans, and their life cycles, then visit the following Web sites:
Enterprise JavaBeans 3.1 Specification (JSR-318) at http://jcp.org/en/jsr/summary?id=318
The "Enterprise Beans" chapter of the Java EE 6 Tutorial at http://docs.oracle.com/javaee/6/tutorial/doc/bnblr.html
Introducing the Java EE 6 Platform: Part 3 (EJB Technology, Even Easier to Use) at http://www.oracle.com/technetwork/articles/javaee/javaee6overview-part3-139660.html#ejbeasy
Connectors (also known as resource adapters) contain the Java, and if necessary, the native modules required to interact with an Enterprise Information System (EIS). A resource adapter deployed to the WebLogic Server environment enables Java EE applications to access a remote EIS. WebLogic Server application developers can use HTTP servlets, JavaServer Pages (JSPs), Enterprise JavaBeans (EJBs), and other APIs to develop integrated applications that use the EIS data and business logic.
To deploy a resource adapter to WebLogic Server, you must first create and configure WebLogic Server-specific deployment descriptor, weblogic-ra.xml
file, and add this to the deployment directory. Resource adapters can be deployed to WebLogic Server as standalone modules or as part of an enterprise application. See Enterprise Applications.
For more information on connectors, see Developing Resource Adapters for Oracle WebLogic Server.
An enterprise application consists of one or more Web application modules, EJB modules, and resource adapters. It might also include a client application. An enterprise application can be optionally defined by an application.xml
file, which was the standard Java EE deployment descriptor for enterprise applications.
An important aspect of the Java EE programming model is the introduction of metadata annotations. Annotations simplify the application development process by allowing a developer to specify within the Java class itself how the application behaves in the container, requests for dependency injection, and so on. Annotations are an alternative to deployment descriptors that were required by older versions of enterprise applications (1.4 and earlier).
With Java EE annotations, the standard application.xml
and web.xml
deployment descriptors are optional. The Java EE programming model uses the JDK annotations feature (see http://docs.oracle.com/javaee/6/api/
) for Web containers, such as EJBs, servlets, Web applications, and JSPs. See Chapter 8, "Using Java EE Annotations and Dependency Injection."
If the application includes WebLogic Server-specific extensions, the application is further defined by a weblogic-application.xml
file. Enterprise applications that include a client module will also have a client-application.xml
deployment descriptor and a WebLogic run-time client application deployment descriptor. See Appendix A, "Enterprise Application Deployment Descriptor Elements."
For both production and development purposes, Oracle recommends that you package and deploy even standalone Web applications, EJBs, and resource adapters as part of an enterprise application. Doing so allows you to take advantage of Oracle's split development directory structure, which greatly facilitates application development. See Chapter 4, "Creating a Split Development Directory Environment."
An enterprise application consists of Web application modules, EJB modules, and resource adapters. It can be packaged as follows:
For development purposes, Oracle recommends the WebLogic split development directory structure. Rather than having a single archived EAR file or an exploded EAR directory structure, the split development directory has two parallel directories that separate source files and output files. This directory structure is optimized for development on a single WebLogic Server instance. See Chapter 4, "Creating a Split Development Directory Environment." Oracle provides the wlpackage
Ant task, which allows you to create an EAR without having to use the JAR utility; this is exclusively for the split development directory structure. See Packaging Applications Using wlpackage.
For development purposes, Oracle further recommends that you package standalone Web applications and Enterprise JavaBeans (EJBs) as part of an enterprise application, so that you can take advantage of the split development directory structure. See Organizing Java EE Components in a Split Development Directory.
For production purposes, Oracle recommends the exploded (unarchived) directory format. This format enables you to update files without having to redeploy the application. To update an archived file, you must unarchive the file, update it, then rearchive and redeploy it.
You can choose to package your application as a JAR archived file using the jar
utility with an .ear
extension. Archived files are easier to distribute and take up less space. An EAR file contains all of the JAR, WAR, and RAR module archive files for an application and an XML descriptor that describes the bundled modules. See Packaging Applications Using wlpackage.
The optional META-INF/application.xml
deployment descriptor contains an element for each Web application, EJB, and connector module, as well as additional elements to describe security roles and application resources such as databases. If this descriptor is present the WebLogic deployer picks the list of modules from this descriptor. However if this descriptor is not present, the container guesses the modules from the annotations defined on the POJO (plain-old-Java-object) classes. See Appendix A, "Enterprise Application Deployment Descriptor Elements."
Web services can be shared by and used as modules of distributed Web-based applications. They commonly interface with existing back-end applications, such as customer relationship management systems, order-processing systems, and so on. Web services can reside on different computers and can be implemented by vastly different technologies, but they are packaged and transported using standard Web protocols, such as HTTP, thus making them easily accessible by any user on the Web.
A Web service consists of the following modules, at a minimum:
A Web service implementation hosted by a server on the Web. WebLogic Web services are hosted by WebLogic Server. A Web service module may include either Java classes or EJBs that implement the Web service. Web services are packaged either as Web application archives (WARs) or EJB modules (JARs), depending on the implementation.
A standard for transmitting data and Web service invocation calls between the Web service and the user of the Web service. WebLogic Web services use Simple Object Access Protocol (SOAP) 1.1 as the message format and HTTP as the connection protocol.
A standard for describing the Web service to clients so they can invoke it. WebLogic Web services use Web services Description Language (WSDL) 1.1, an XML-based specification, to describe themselves.
A standard for clients to invoke Web services—JAX-WS or JAX-RPC. See Developing JAX-WS Web Services for Oracle WebLogic Server or Developing JAX-RPC Web Services for Oracle WebLogic Server, respectively.
A standard for finding and registering the Web service (UDDI).
For more information about WebLogic Web services and the standards that are supported, see Understanding WebLogic Web Services for Oracle WebLogic Server.
JMS and JDBC configurations are stored as modules, defined by an XML file that conforms to the weblogic-jms.xsd
and jdbc-data-source.xsd
schema, respectively. These modules are similar to standard Java EE modules. An administrator can create and manage JMS and JDBC modules as global system resources, as modules packaged with a Java EE application (as a packaged resource), or as standalone modules that can be made globally available.
With modular deployment of JMS and JDBC resources, you can migrate your application and the required JMS or JDBC configuration from environment to environment, such as from a testing environment to a production environment, without opening an enterprise application file (such as an EAR file) or a JMS or JDBC standalone module, and without extensive manual JMS or JDBC reconfiguration.
Application developers create application modules in an enterprise-level IDE or another development tool that supports editing of XML files, then package the JMS or JDBC modules with an application and pass the application to a WebLogic administrator to deploy.
For more information, see:
The WebLogic Diagnostic Framework (WLDF) provides features for generating, gathering, analyzing, and persisting diagnostic data from WebLogic Server instances and from applications deployed to server instances. For server-scoped diagnostics, some WLDF features are configured as part of the configuration for the domain. Other features are configured as system resource descriptors that can be targeted to servers (or clusters). For application-scoped diagnostics, diagnostic features are configured as resource descriptors for the application.
Application-scoped instrumentation is configured and deployed as a diagnostic module, which is similar to a diagnostic system module. However, an application module is configured in an XML configuration file named weblogic-diagnostics.xml
which is packaged with the application archive.
For detailed instructions for configuring instrumentation for applications, see "Configuring Application-Scoped Instrumentation".
WebLogic Server also supports the use of an external diagnostics descriptor so you can integrate diagnostic functionality into an application that has not imported diagnostic descriptors. This feature supports the deployment view and deployment of an application or a module, detecting the presence of an external diagnostics descriptor if the descriptor is defined in your deployment plan (plan.xml
).
First, define the diagnostic descriptor as external and configure its URI in the plan.xml
file. For example:
<module-override> <module-name>reviewService.ear</module-name> <module-type>ear</module-type> </module-descriptor> <module-descriptor external="true"> <root-element>wldf-resource</root-element> <uri>META-INF/weblogic-diagnostics.xml</uri> ... ... </module-override> <config-root>D:\plan</config-root>
Then place the external diagnostic descriptor file under the URI. Using the example above, you would place the descriptor file under d:\plan\ META-INF
.
A Coherence GAR module provides distributed in-memory caching and data grid computing that allows applications to increase their availability, scalability, and performance. GAR modules are deployed as both standalone modules and packaged with Java EE applications (as a packaged resource). A GAR module may also be made globally available.
A GAR module is defined by the coherence-application.xml deployment descriptor and must conform to the coherence-application.xsd
XML schema. The GAR contains the artifacts that comprise a Coherence application: Coherence configuration files, application classes (such as entry processors, aggregators, filters), and any dependencies that are required.
The Bean Validation specification (JSR 316) defines a metadata model and API for validating data in JavaBeans components. It is supported on both the server and Java EE 6 client; therefore, instead of distributing validation of data over several layers, such as the browser and the server side, you can define the validation constraints in one place and share them across the different layers. Further, bean validation is not only for validating beans. In fact, it can also be used to validate any Java object.
Bean Validation and JNDI
Where required by the Java EE 6 specifications, the default Validator
and ValidatorFactory
are located using JNDI under the names java:comp/Validator
and java:comp/ValidatorFactory
. These two artifacts reflect the validation descriptor that is in scope.
Bean Validation Configuration
Bean validation can be configured by using XML descriptors or annotation.
Descriptors:
Descriptor elements override corresponding annotations.
Weblogic Server allows one descriptor per module. Therefore, an application can have several validation descriptors but only one is allowed per module scope.
Validation descriptors are named validation.xml
and are packaged in the META-INF
directory, except for Web modules, where the descriptor is packaged in the WEB-INF
directory.
Annotations:
Injection of the default Validator
and ValidatorFactory
is requested using the @Resource
annotation. However, not all source files are scanned for this annotation.
The WebLogic Connector uses bean validation internally to validate the connector descriptors.
Once bean validation is configured, the standard set of container managed classes for a given container will be scanned. For example, for EJBs, bean and interceptor classes are scanned. Web application classes and ManagedBeans also support the injection of Validator
and ValidatorFactories
.
For more information about the classes that support bean validation, please see the related component specifications for the list of classes that support dependency injection.
A deployment configuration refers to the process of defining the deployment descriptor values required to deploy an enterprise application to a particular WebLogic Server domain. The deployment configuration for an application or module is stored in three types of XML document: Java EE deployment descriptors, WebLogic Server descriptors, and WebLogic Server deployment plans. This section describes the Java EE and WebLogic-specific deployment descriptors. See Deployment Plans for information on deployment plans.
The Java EE programming model uses the JDK annotations feature for Web containers (see http://docs.oracle.com/javaee/6/api/
), such as EJBs, servlets, Web applications, and JSPs. Annotations simplify the application development process by allowing a developer to specify within the Java class itself how the component behaves in the container, requests for dependency injection, and so on. Annotations are an alternative to deployment descriptors tha t were required by older versions of Web applications (2.4 and earlier), enterprise applications (1.4 and earlier), and Enterprise JavaBeans (2.x and earlier). See Chapter 8, "Using Java EE Annotations and Dependency Injection."
However, enterprise applications fully support the use of deployment descriptors, even though the standard Java EE ones are not required. For example, you may prefer to use the old EJB 2.x programming model, or might want to allow further customizing of the EJB at a later development or deployment stage; in these cases you can create the standard deployment descriptors in addition to, or instead of, the metadata annotations.
Modules and applications have deployment descriptors—XML documents—that describe the contents of the directory or JAR file. Deployment descriptors are text documents formatted with XML tags. The Java EE specifications define standard, portable deployment descriptors for Java EE modules and applications. Oracle defines additional WebLogic-specific deployment descriptors for deploying a module or application in the WebLogic Server environment.
Table 1-1 lists the types of modules and applications and their Java EE-standard and WebLogic-specific deployment descriptors.
Note: The XML schemas for the WebLogic deployment descriptors listed in the following table include elements from the For the most current schema information, see: |
Table 1-1 Java EE and WebLogic Deployment Descriptors
When you package a module or application, you create a directory to hold the deployment descriptors—WEB-INF
or META-INF
—and then create the XML deployment descriptors in that directory.
WebLogic Server provides a variety of tools for automatically generating deployment descriptors. These are discussed in the sections that follow.
EJBGen is an Enterprise JavaBeans 2.x code generator or command-line tool that uses Javadoc markup to generate EJB deployment descriptor files. You annotate your Bean class file with Javadoc tags and then use EJBGen to generate the Remote and Home classes and the deployment descriptor files for an EJB application, reducing to a single file you need to edit and maintain your EJB .java
and descriptor files. See "EJBGen Reference" in Developing Enterprise JavaBeans, Version 2.1, for Oracle WebLogic Server.
WebLogic Server includes a set of Java-based command-line utilities that automatically generate both standard Java EE and WebLogic-specific deployment descriptors for Web applications and enterprise applications.
These command-line utilities examine the classes you have assembled in a staging directory and build the appropriate deployment descriptors based on the servlet classes, and so on. These utilities include:
java weblogic.marathon.ddinit.EarInit
— automatically generates the deployment descriptors for enterprise applications.
java weblogic.marathon.ddinit.WebInit
— automatically generates the deployment descriptors for Web applications.
For an example of DDInit
, assume that you have created a directory called c:\stage
that contains the JSP files and other objects that make up a Web application but you have not yet created the web.xml
and weblogic.xml
deployment descriptors. To automatically generate them, execute the following command:
prompt> java weblogic.marathon.ddinit.WebInit c:\stage
The utility generates the web.xml
and weblogic.xml
deployment descriptors and places them in the WEB-INF
directory, which DDInit
will create if it does not already exist.
So that your applications can take advantage of the features in the current Java EE specification and release of WebLogic Server, Oracle recommends that you always upgrade deployment descriptors when you migrate applications to a new release of WebLogic Server.
To upgrade the deployment descriptors in your Java EE applications and modules, first use the weblogic.DDConverter
tool to generate the upgraded descriptors into a temporary directory. Once you have inspected the upgraded deployment descriptors to ensure that they are correct, repackage your Java EE module archive or exploded directory with the new deployment descriptor files.
Invoke weblogic.DDConverter
with the following command:
prompt> java weblogic.DDConverter [options] archive_file_or_directory
where archive_file_or_directory
refers to the archive file (EAR, WAR, JAR, or RAR) or exploded directory of your enterprise application, Web application, EJB, or resource adapter.
The following table describes the weblogic.DDConverter
command options.
Option | Description |
---|---|
|
Specifies the directory to which descriptors are written. |
-help |
Prints the standard usage message. |
-quiet |
Turns off output messages except error messages. |
-verbose |
Turns on additional output used for debugging. |
The following example shows how to use the weblogic.DDConverter
command to generate upgraded deployment descriptors for the my.ear
enterprise application into the subdirectory tempdir
in the current directory:
prompt> java weblogic.DDConverter -d tempdir my.ear
A deployment plan is an XML document that defines an application's WebLogic Server deployment configuration for a specific WebLogic Server environment. A deployment plan resides outside of an application's archive file, and can apply changes to deployment properties stored in the application's existing WebLogic Server deployment descriptors. Administrators use deployment plans to easily change an application's WebLogic Server configuration for a specific environment without modifying existing Java EE or WebLogic-specific deployment descriptors. Multiple deployment plans can be used to reconfigure a single application for deployment to multiple, differing WebLogic Server environments.
After programmers have finished programming an application, they export its deployment configuration to create a custom deployment plan that administrators later use for deploying the application into new WebLogic Server environments. Programmers distribute both the application deployment files and the custom deployment plan to deployers (for example, testing, staging, or production administrators) who use the deployment plan as a blueprint for configuring the application for their environment.
WebLogic Server provides the following tools to help programmers export an application's deployment configuration:
weblogic.PlanGenerator
creates a template deployment plan with null variables for selected categories of WebLogic Server deployment descriptors. This tool is recommended if you are beginning the export process and you want to create a template deployment plan with null variables for an entire class of deployment descriptors.
The Administration Console updates or creates new deployment plans as necessary when you change configuration properties for an installed application. You can use the Administration Console to generate a new deployment plan or to add or override variables in an existing plan. The Administration Console provides greater flexibility than weblogic.PlanGenerator
, because it allows you to interactively add or edit individual deployment descriptor properties in the plan, rather than export entire categories of descriptor properties.
For complete and detailed information about creating and using deployment plans, see:
This section describes required and optional tools for developing WebLogic Server applications.
Oracle provides the Oracle Fusion Middleware Java API Reference for Oracle WebLogic Server, which defines all of the supported Java classes available for use when developing Java EE applications for WebLogic Server. See the Java API Reference for Oracle WebLogic Server.
In conjunction with the Java API Reference for Oracle WebLogic Server, Oracle recommends using the wls-api.jar
file to develop and compile Java EE applications for your WebLogic Server environment. The wls-api.jar
file is located in the wlserver/server/lib
directory of your WebLogic Server distribution and offers the following benefits:
developing more performant code based on tested best practices
avoiding deprecated or unsupported code paths
Use the wls-api.jar
file and the api.jar
file to develop and compile your Java EE applications in Integrated Development Environments (IDEs), such as Oracle JDeveloper. IDEs provide an array of tools to simplify development of Java-based applications. The wls-api.jar
file provides a clean and concise API jar to develop and run Java EE applications for WebLogic environments.
Note: The |
You may need to include the weblogic.jar
file in the classpath of your development environment to access tools such as WLST, the weblogic.Deployer
utilty, and weblogic.appc
.
The preferred Oracle method for building applications with WebLogic Server is Apache Ant. Ant is a Java-based build tool. One of the benefits of Ant is that is it is extended with Java classes, rather than shell-based commands. Oracle provides numerous Ant extension classes to help you compile, build, deploy, and package applications using the WebLogic Server split development directory environment.
Another benefit is that Ant is a cross-platform tool. Developers write Ant build scripts in eXtensible Markup Language (XML). XML tags define the targets to build, dependencies among targets, and tasks to execute in order to build the targets. Ant libraries are bundled with WebLogic Server to make it easier for our customers to build Java applications out of the box.
To use Ant, you must first set your environment by executing either the setExamplesEnv.cmd
(Windows) or setExamplesEnv.sh
(UNIX) commands located in the WL_SERVER
\samples\domains\wl_server
directory, where WL_SERVER
is your WebLogic Server installation directory.
For a complete explanation of ant capabilities, see: http://jakarta.apache.org/ant/manual/index.html
Note: The Apache Jakarta Web site publishes online documentation for only the most current version of Ant, which might be different from the version of Ant that is bundled with WebLogic Server. Use the following command, after setting your WebLogic environment, to determine the version of Ant bundled with WebLogic Server: prompt> ant -version To view the documentation for a specific version of Ant, such as the version included with WebLogic Server, download the Ant zip file from |
For more information on using Ant to compile your cross-platform scripts or using cross-platform scripts to create XML scripts that can be processed by Ant, refer to any of the WebLogic Server examples, such as EXAMPLES_HOME
/wl_server/examples/src/examples/ejb20/basic/beanManaged/build.xml
, where EXAMPLES_HOME
represents the directory in which the WebLogic Server code examples are configured. For more information about the WebLogic Server code examples, see "Sample Applications and Code Examples" in Understanding Oracle WebLogic Server.
Also refer to the following WebLogic Server documentation on building examples using Ant: EXAMPLES_HOME
/wl_server/examples/src/examples/examples.html
.
You can use your own version of Ant if the one bundled with WebLogic Server is not adequate for your purposes. To determine the version of Ant that is bundled with WebLogic Server, run the following command after setting your WebLogic environment:
prompt> ant -version
If you plan to use a different version of Ant, you can replace the appropriate JAR file in the WL_HOME
\server\lib\ant
directory with an updated version of the file (where WL_HOME
refers to the main WebLogic installation directory, such as c:\Oracle\Middleware\Oracle_Home\wlserver
) or add the new file to the front of your CLASSPATH.
By default the environment script allocates a heap size of 128 megabytes to Ant. You can increase or decrease this value for your own projects by setting the -X
option in your local ANT_OPTS
environment variable. For example:
prompt> setenv ANT_OPTS=-Xmx128m
If you want to set the heap size permanently, add or update the MEM_ARGS
variable in the scripts that set your environment, start WebLogic Server, and so on, as shown in the following snippet from a Windows command script that starts a WebLogic Server instance:
set MEM_ARGS=-Xms32m -Xmx200m
See the scripts and commands in WL_HOME
/server/bin
for examples of using the MEM_ARGS
variable.
You need a text editor to edit Java source files, configuration files, HTML or XML pages, and JavaServer Pages. An editor that gracefully handles Windows and UNIX line-ending differences is preferred, but there are no other special requirements for your editor. You can edit HTML or XML pages and JavaServer Pages with a plain text editor, or use a Web page editor such as Dreamweaver. For XML pages, you can also use an enterprise-level IDE with DTD validation or another development tool that supports editing of XML files.
Nearly all WebLogic Server applications require a database system. You can use any DBMS that you can access with a standard JDBC driver, but services such as WebLogic Java Message Service (JMS) require a supported JDBC driver for Oracle, Sybase, Informix, Microsoft SQL Server, or IBM DB2. Refer to "Oracle Fusion Middleware Supported System Configurations" to find out about supported database systems and JDBC drivers.
Most Java EE applications are designed to be executed by Web browser clients. WebLogic Server supports the HTTP 1.1 specification and is tested with current versions of the Firefox and Microsoft Internet Explorer browsers.
When you write requirements for your application, note which Web browser versions you will support. In your test plans, include testing plans for each supported version. Be explicit about version numbers and browser configurations. Will your application support Secure Socket Layers (SSL) protocol? Test alternative security settings in the browser so that you can tell your users what choices you support.
If your application uses applets, it is especially important to test browser configurations you want to support because of differences in the JVMs embedded in various browsers. One solution is to require users to install the Java plug-in so that everyone has the same Java run-time version.
You can use third-party software products to enhance your WebLogic Server development environment. See "WebLogic Developer Tools Resources", which provides developer tools information for products that support the application servers.
Note: Check with the software vendor to verify software compatibility with your platform and WebLogic Server version. |
This document contains the following updates to describe the new application development features introduced in this release of WebLogic Server:
Maven updates—In this release of WebLogic Server, the weblogic-maven-plugin
provides enhanced functionality to install, start and stop servers, create domains, execute WLST scripts, and compile and deploy applications. With the weblogic-maven-plugin
, you can install WebLogic Server from within your Maven environment to fulfill the local WebLogic Server requirement. See Chapter 3, "Using the WebLogic Development Maven Plug-In".
OSGi bundles for WebLogic Server applications—In this release of WebLogic Server, developers who want to use OSGi in their applications can easily share OSGi facilities, such as the OSGi service registry, class loaders, and other OSGi services. See Chapter 16, "Developing OSGi Bundles for WebLogic Server Applications".
WebSockets—This release of WebLogic Server adds support for the WebSocket Protocol (RFC 6455), which provides two-way, full-duplex communication over a single TCP connection between clients and servers, where each side can send data independently from the other. See Chapter 17, "Using WebSockets in WebLogic Server".
Coherence Grid Archive (GAR) module support—A Coherence GAR module provides distributed in-memory caching and data grid computing that allows applications to increase their availability, scalability, and performance. See "Coherence Grid Archive (GAR) Modules".
For a comprehensive listing of the new WebLogic Server features introduced in this release, see What's New in Oracle WebLogic Server.
Developing Applications for Oracle WebLogic Server
12c (12.1.2)
E28106-05
September 2014
This document describes building WebLogic Server e-commerce applications using the Java Platform, Enterprise Edition 6.
Oracle Fusion Middleware Developing Applications for Oracle WebLogic Server, 12c (12.1.2)
E28106-05
Copyright © 2007, 2014, Oracle and/or its affiliates. All rights reserved.
This software and related documentation are provided under a license agreement containing restrictions on use and disclosure and are protected by intellectual property laws. Except as expressly permitted in your license agreement or allowed by law, you may not use, copy, reproduce, translate, broadcast, modify, license, transmit, distribute, exhibit, perform, publish, or display any part, in any form, or by any means. Reverse engineering, disassembly, or decompilation of this software, unless required by law for interoperability, is prohibited.
The information contained herein is subject to change without notice and is not warranted to be error-free. If you find any errors, please report them to us in writing.
If this is software or related documentation that is delivered to the U.S. Government or anyone licensing it on behalf of the U.S. Government, the following notice is applicable:
U.S. GOVERNMENT END USERS: Oracle programs, including any operating system, integrated software, any programs installed on the hardware, and/or documentation, delivered to U.S. Government end users are "commercial computer software" pursuant to the applicable Federal Acquisition Regulation and agency-specific supplemental regulations. As such, use, duplication, disclosure, modification, and adaptation of the programs, including any operating system, integrated software, any programs installed on the hardware, and/or documentation, shall be subject to license terms and license restrictions applicable to the programs. No other rights are granted to the U.S. Government.
This software or hardware is developed for general use in a variety of information management applications. It is not developed or intended for use in any inherently dangerous applications, including applications that may create a risk of personal injury. If you use this software or hardware in dangerous applications, then you shall be responsible to take all appropriate failsafe, backup, redundancy, and other measures to ensure its safe use. Oracle Corporation and its affiliates disclaim any liability for any damages caused by use of this software or hardware in dangerous applications.
Oracle and Java are registered trademarks of Oracle and/or its affiliates. Other names may be trademarks of their respective owners.
Intel and Intel Xeon are trademarks or registered trademarks of Intel Corporation. All SPARC trademarks are used under license and are trademarks or registered trademarks of SPARC International, Inc. AMD, Opteron, the AMD logo, and the AMD Opteron logo are trademarks or registered trademarks of Advanced Micro Devices. UNIX is a registered trademark of The Open Group.
This software or hardware and documentation may provide access to or information on content, products, and services from third parties. Oracle Corporation and its affiliates are not responsible for and expressly disclaim all warranties of any kind with respect to third-party content, products, and services. Oracle Corporation and its affiliates will not be responsible for any loss, costs, or damages incurred due to your access to or use of third-party content, products, or services.
This chapter describes how to program and maintain applications with WebLogic Server using the production redeployment strategy.
This chapter includes the following sections:
Production redeployment enables an administrator to redeploy a new version of an application in a production environment without stopping the deployed application or otherwise interrupting the application's availability to clients. Production redeployment works by deploying a new version of an updated application alongside an older version of the same application. WebLogic Server automatically manages client connections so that only new client requests are directed to the new version. Clients already connected to the application during the redeployment continue to use the older, retiring version of the application until they complete their work.
See "Using Production Redeployment to Upgrade Applications" for more information.
Production redeployment only supports HTTP clients and RMI clients. Your development and design team must ensure that applications using production redeployment are not accessed by an unsupported client. WebLogic Server does not detect when unsupported clients access the application, and does not preserve unsupported client connections during production redeployment.
Enterprise applications can contain any of the supported Java EE module types. Enterprise applications can also include application-scoped JMS and JDBC modules.
If an enterprise application includes a JCA resource adapter module, the module:
Must be JCA 1.5 compliant
Must implement the weblogic.connector.extensions.Suspendable
interface
Must be used in an application-scoped manner, having enable-access-outside-app
set to false
(the default value).
Before resource adapters in a newer version of the EAR are deployed, resource adapters in the older application version receive a callback. WebLogic Server then deploys the newer application version and retires the entire older version of the EAR.
For a complete list of production redeployment requirements for resource adapters, see "Production Redeployment" in Developing Resource Adapters for Oracle WebLogic Server.
Additional production redeployment support is provided for enterprise applications that are accessed by inbound JMS messages from a global JMS destination, and that use one or more message-driven beans as consumers. For this type of application, WebLogic Server suspends message-driven beans in the older, retiring application version before deploying message-driven beans in the newer version. Production redeployment is not supported with JMS consumers that use the JMS API for global JMS destinations. If the message-driven beans need to receive all messages published from topics, including messages published while bean are suspended, use durable subscribers.
WebLogic Server performs production redeployment by deploying two instances of an application simultaneously. You must observe certain programming conventions to ensure that multiple instances of the application can co-exist in a WebLogic Server domain. The following sections describe each programming convention required for using production redeployment.
As a best practice, applications that use the in-place redeployment strategy should be self-contained in their use of resources. This means you should generally use application-scoped JMS and JDBC resources, rather than global resources, whenever possible for versioned applications.
If an application must use a global resource, you must ensure that the application supports safe, concurrent access by multiple instances of the application. This same restriction also applies if the application uses external (separately-deployed) applications, or uses an external property file. WebLogic Server does not prevent the use of global resources with versioned applications, but you must ensure that resources are accessed in a safe manner.
Looking up a global JNDI resource from within a versioned application results in a warning message. To disable this check, set the JNDI environment property weblogic.jndi.WLContext.ALLOW_GLOBAL_RESOURCE_LOOKUP
to true
when performing the JNDI lookup.
Similarly, looking up an external application results in a warning unless you set the JNDI environment property, weblogic.jndi.WLContext.ALLOW_EXTERNAL_APP_LOOKUP
, to true
.
WebLogic Server binds application-scoped resources, such as JMS and JDBC application modules, into a local JNDI tree available to the application. As with non-versioned applications, versioned applications can look up application-scoped resources directly from this local tree. Application-scoped JMS modules can be accessed via any supported JMS interfaces, such as the JMS API or a message-driven bean.
Application modules that are bound to the global JNDI tree should be accessed only from within the same application version. WebLogic Server performs version-aware JNDI lookups and bindings for global resources deployed in a versioned application. By default, an internal JNDI lookup of a global resource returns bindings for the same version of the application.
If the current version of the application cannot be found, you can use the JNDI environment property weblogic.jndi.WLContext.RELAX_VERSION_LOOKUP
to return bindings from the currently active version of the application, rather than the same version.
Note:: Set |
Any security provider used in the application must support the WebLogic Server application versioning SSPI. The default WebLogic Server security providers for authorization, role mapping, and credential mapping support the application versioning SSPI.
In order to use production redeployment, both the current, deployed version of the application and the updated version of the application must specify unique version identifiers. See Assigning an Application Version.
Versioned applications can programmatically obtain both an application name, which remains constant across different versions, and an application identifier, which changes to provide a unique label for different versions of the application. Use the application name for basic display or error messages that refer to the application's name irrespective of the deployed version. Use the application ID when the application must provide unique identifier for the deployed version of the application. See Accessing Version Information for more information about the MBean attributes that provide the name and identifier.
As described in What is Production Redeployment?, WebLogic Server attempts to route a client application's requests to the same version of the application until all of the client's in-progress work has completed. However, if an application version is retired using a timeout period, or is undeployed, the client's request will be routed to the active version of the application. In other words, a client's association with a given version of an application is maintained only on a "best-effort basis."
This behavior can be problematic for client applications that recursively access other applications when processing requests. WebLogic Server attempts to dispatch requests to the same versions of the recursively-accessed applications, but cannot guarantee that an intermediate application version is not undeployed manually or after a timeout period. If you have a group of related applications with strict version requirements, Oracle recommends packaging all of the applications together to ensure version consistency during production redeployment.
Oracle recommends that you specify the version identifier in the MANIFEST.MF
of the application, and automatically increment the version each time a new application is released for deployment. This ensures that production redeployment is always performed when the administrator or deployer redeploys the application.
For testing purposes, a deployer can also assign a version identifier to an application during deployment and redeployment. See "Assigning a Version Identifier During Deployment and Redeployment" in Deploying Applications to Oracle WebLogic Server.
WebLogic Server obtains the application version from the value of the Weblogic-Application-Version
property in the MANIFEST.MF
file. The version string can be a maximum of 215 characters long, and must consist of valid characters as identified in Table 7-1.
Table 7-1 Valid and Invalid Characters
Valid ASCII Characters | Invalid Version Constructs |
---|---|
a-z |
.. |
A-Z |
. |
0-9 | |
period ("."), underscore ("_"), or hyphen ("-") in combination with other characters |
For example, the following manifest file content describes an application with version "v920.beta
":
Manifest-Version: 1.0 Created-By: 1.4.1_05-b01 (Sun Microsystems Inc.) Weblogic-Application-Version: v920.beta
If you are upgrading applications for deployment to WebLogic Server 9.2 or later, note that the Name
attribute retrieved from AppDeploymentMBean
now returns a unique application identifier consisting of both the deployed application name and the application version string. Applications that require only the deployed application name must use the new ApplicationName
attribute instead of the Name
attribute. Applications that require a unique identifier can use either the Name
or ApplicationIdentifier
attribute, as described in Accessing Version Information.
Your application code can use new MBean attributes to retrieve version information for display, logging, or other uses. The following table describes the read-only attributes provided by ApplicationMBean
.
Table 7-2 Read-Only Version Attributes in ApplicationMBean
Attribute Name | Description |
---|---|
ApplicationName |
A String that represents the deployment name of the application |
VersionIdentifier |
A String that uniquely identifies the current application version across all versions of the same application |
ApplicationIdentifier |
A String that uniquely identifies the current application version across all deployed applications and versions |
ApplicationRuntimeMBean
also provides version information in the new read-only attributes described in the following table.
Table 7-3 Read-Only Version Attributes in ApplicationRuntimeMBean
Attribute Name | Description |
---|---|
ApplicationName |
A String that represents the deployment name of the application |
ApplicationVersion |
A string that represents the version of the application. |
ActiveVersionState |
An integer that indicates the current state of the active application version. Valid states for an active version are:
See the Java API Reference for Oracle WebLogic Server for more information. Note that the currently active version does not always correspond to the last-deployed version, because the administrator can reverse the production redeployment process. See "Rolling Back the Production Redeployment Process" in Deploying Applications to Oracle WebLogic Server. |
This chapter describes how to deploy WebLogic Server Java EE applications using the WebLogic split development directory environment.
This chapter includes the following sections:
The wldeploy
task provides an easy way to deploy directly from the split development directory. wlcompile
provides most of the same arguments as the weblogic.Deployer
directory. To deploy from a split development directory, you simply identify the build directory location as the deployable files, as in:
<wldeploy user="${user}" password="${password}" action="deploy" source="${dest.dir}" name="helloWorldEar" />
The above task is automatically created when you use weblogic.BuildXMLGen
to create the build.xml
file.
See Appendix B, "wldeploy Ant Task Reference," for a complete command reference.
The wlpackage
Ant task uses the contents of both the source and build directories to create either a deployable archive file (.EAR
file), or an exploded archive directory representing the enterprise application (exploded .EAR
directory). Use wlpackage
when you want to deliver your application to another group or individual for evaluation, testing, performance profiling, or production deployment.
For production purposes, it is convenient to deploy enterprise applications in exploded (unarchived) directory format. This applies also to standalone Web applications, EJBs, and connectors packaged as part of an enterprise application. Using this format allows you to update files directly in the exploded directory rather than having to unarchive, edit, and rearchive the whole application. Using exploded archive directories also has other benefits, as described in Deployment Archive Files Versus Exploded Archive Directories in Deploying Applications to Oracle WebLogic Server.
You can also package applications in a single archived file, which is convenient for packaging modules and applications for distribution. Archive files are easier to copy, they use up fewer file handles than an exploded directory, and they can save disk space with file compression.
The Java classloader can search for Java class files (and other file types) in a JAR file the same way that it searches a directory in its classpath. Because the classloader can search a directory or a JAR file, you can deploy Java EE modules on WebLogic Server in either a JAR (archived) file or an exploded (unarchived) directory.
In a production environment, use the wlpackage
Ant task to package your split development directory application as a traditional EAR file that can be deployed to WebLogic Server. Continuing with the MedRec example, you would package your application as follows:
<wlpackage tofile="\physicianEAR\physicianEAR.ear" srcdir="\physicianEAR" destdir="\build\physicianEAR"/> <wlpackage todir="\physicianEAR\explodedphysicianEar" srcdir="\src\physicianEAR" destdir="\build\physicianEAR" />
The following table describes the attributes of the wlpackage
Ant task.
Table 6-1 Attributes of the wlpackage Ant Task
Attribute | Description | Data Type | Required? |
---|---|---|---|
|
Name of the EAR archive file into which the |
String |
You must specify one of the following two attributes: |
|
Name of an exploded directory into which the |
String |
You must specify one of the following two attributes: |
|
Specifies the source directory of your split development directory application. The source directory contains all editable files for your project—Java source files, editable descriptor files, JSPs, static content, and so forth. |
String |
Yes. |
|
Specifies the build directory of your split development directory application. It is assumed that you have already executed the |
String |
Yes. |
This chapter describes the implementation of the WebSocket Protocol in WebLogic Server.
This chapter includes the following sections:
WebLogic Server supports the WebSocket Protocol (RFC 6455), which provides simultaneous two-way communication over a single TCP connection between clients and servers, where each side can send data independently from the other. To initiate the WebSocket connection, the client sends a handshake request to the server. The connection is established if the handshake request passes validation, and the server accepts the request. When a WebSocket connection is created, a browser client can send data to a WebLogic Server instance while simultaneously receiving data from that server instance. As part of the HTML5 specification (http://www.w3.org/TR/html5/
), the WebSocket Protocol is supported by most browsers. For general information about the WebSocket Protocol, see http://tools.ietf.org/html/rfc6455
.
If the WebLogic Server Examples component is installed and configured on your machine, you can use the HTML5 WebSocket example for a demonstration of using WebSockets in WebLogic Server. For more information about running this example, see "Sample Applications and Code Examples" in Understanding Oracle WebLogic Server.
The following sections describe the life cycle of a WebSocket in WebLogic Server:
All WebSocket connections are initiated by the client. To establish a WebSocket connection, the client must send a handshake request (an HTTP GET request) to the server. If the HTTP request matches the pathPatterns
attribute of the @WebSocket
annotation, then the internal WebSocket servlet validates the handshake request. The validation process follows application validation (implemented in the accept
method of the WebSocket listener) and the rules defined in the WebSocket Protocol. If the handshake request is valid, then the servlet upgrades the HTTP request to a WebSocket connection, and the server sends a WebSocket handshake response to the client. If the request is invalid, then the servlet rejects the request.
After the WebSocket connection is established, the server frees the request thread and listens for read events on the connection. When the server detects a read event, the server decodes the message, as defined in the WebSocket Protocol, and invokes the corresponding methods of the listener. For example, the server invokes onMessage
methods if the message is a text or binary message, onFragment
methods if the message is a fragment, and so on. The Work Manager specified in the dispatchPolicy
attribute of the @WebSocket
annotation controls the thread that invokes these methods.
At the same time, messages can be sent to the WebSocket by invoking the corresponding methods of the WebSocketConnection
interface until the WebSocket is closed. For example:
send
methods send messages to a WebSocket.
sendPing
and sendPong
methods send Ping and Pong control frame.
stream
methods send message fragments.
The context associated with a WebSocket is tied to that specific WebSocket. Sending messages is a synchronous task and occurs on the thread that issues the call.
A WebSocket times out if no read or write activity occurs and no Ping messages are received within the configured timeout period. The container enforces a 30-second timeout period as the default. If the timeout period is set to -1
, no timeout period is set for the connection.
Upon timeout, the container invokes the listener's onTimeout()
method, at which time the listener sends an appropriate message to the client. After the onTimeout()
method returns, the container closes the WebSocket.
At any time during WebSocket communication, the client or server can terminate the WebSocket connection. If the client issues a close request, the container invokes the listener's onClose()
method and terminates the underlying connection. From the server side, you can use the WebSocketConnection.close
methods to close the WebSocket connection. Upon invoking these methods, the server issues a close request to the client before it closes the connection.
After upgrading to a WebSocket connection, messages can flow asynchronously in either direction. However, to prevent message corruption, message sending must be synchronous. When multiple threads attempt to send messages on the same WebSocket, ordering is not guaranteed; the thread that first acquires the lock sends the first message.
The WebSocketConnection
methods that send messages to the client are not thread safe. If multiple threads use the same instance of the WebSocketConnection
methods to send messages, the application is responsible for using the appropriate lock mechanism to send messages synchronously. Otherwise, messages may be corrupted.
In WebLogic Server, you can use the WebSocket Protocol implementation and accompanying programming API to develop and deploy applications that communicate bidirectionally with clients. Although you can use WebSockets for any type of client-server communication, the implementation is most commonly used to communicate with browsers running Web pages that use the WebSocket API.
The following sections describe using WebSockets in WebLogic Server:
The WebLogic Server WebSockets implementation includes the following components:
The WebSocket Protocol handles connection upgrades, establishes and manages connections, and handles exchanges with the client. Using the existing WebLogic Server threading and network infrastructure, WebLogic Server fully integrates the WebSockets Protocol in its implementation.
You can use the WebLogic WebSocket API weblogic.websocket
package to develop WebSocket applications. Table 17-1 lists and summarizes the classes and interfaces included in this API. For complete information, see weblogic.websocket
in the Java API Reference for Oracle WebLogic Server.
Table 17-1 WebLogic WebSocket Java API Interfaces and Classes
Name | Description |
---|---|
Interface that receives and handles WebSocket messages. The container is responsible for wiring the listener to the corresponding servlet, which handles the HTTP upgrade request to a WebSocket. | |
Interface that represents the WebSocket connection between the client and the server. An application uses | |
Interface that provides context information for a set of WebSocket connections handled by a WebSocket listener. This interface also provides context information and associated settings for a WebSocket endpoint declared by the From the | |
Class that provides a convenient, empty implementation of the | |
Class that defines an object to provide WebSocket opening handshake request information to a WebSocket listener. | |
Class that defines an object that assists in sending the opening handshake response to the client. |
The @WebSocket
annotation declares a WebSocket endpoint that communicates using the WebSocket Protocol. Use the @WebSocket
annotation to mark a class as a WebSocket listener that is ready to be exposed as a WebSocket endpoint on which read events are processed. The class annotated by the @WebSocket
annotation must implement the WebSocketListener
interface or extend from the WebSocketAdapter
class. For more information, see weblogic.websocket.annotation.WebSocket
in the Java API Reference for Oracle WebLogic Server.
Example 17-1 demonstrates using the @WebSocket
annotation:
You can use the WebLogic WebSocket API to create browser-based applications that require two-way communication with servers without relying on having multiple HTTP connections open.
WebLogic Server provides the WebLogic WebSocket API within the wlserver/server/lib/wls-api.jar
file. To build applications using the WebLogic WebSocket API, define this library in the classpath when compiling the application.
You can also use Maven to build applications using the WebLogic WebSocket API. For more information, see "Using the WebLogic Development Maven Plug-In".
In WebLogic Server, you deploy WebSocket applications as part of standard Java EE Web application archives (WARs), either as standalone Web applications or WAR modules within enterprise applications. When you deploy the Web application, WebLogic Server detects the @WebSocket
annotation on a class and automatically establishes it as a WebSocket endpoint.
You do not need to configure the WebSocket endpoint in the web.xml
file, or any other deployment descriptor, or perform any type of dynamic operation to register or enable the WebSocket endpoint.
Clients accessing WebSocket applications must either connect directly to the WebLogic Server instance or through a Web proxy server that supports the WebSockets Protocol.
Currently, the only Oracle proxy server that supports WebSockets is Oracle Traffic Director. If you use a different proxy server to access WebSocket applications, then ensure that the proxy server supports WebSockets.
A WebSocket client application is typically a composite of HTML5 technologies, including the HTML markup, CSS3, and JavaScript that makes use of the WebSocket JavaScript API. Oracle does not provide a WebSocket JavaScript API for WebSocket clients. However, most browsers support a standard WebSocket API that can be used to create and work with WebSockets. For more information about HTML5, see http://www.w3.org/TR/html5/
.
The following steps show an example of the execution flow on a client that is sending messages to a WebLogic Server instance using the WebSockets Protocol.
The client opens a WebSocket connection to the server hosting the WebSocket endpoint, using the ws://
or wss://
protocol prefix. For more information, see "Establishing Secure WebSocket Connections".
url = ((window.location.protocol == "https:") ? "wss:" : "ws:") + "//" + window.location.host + "/websocket-helloworld-wls/helloworld_delay.ws"; ws = new WebSocket(url);
The client registers listeners with the WebSocket object to respond to events, such as opening, closing, and receiving messages. Based on the event and the information received, the client performs the appropriate action.
ws.onopen = function(event) { document.getElementById("status").innerHTML = "OPEN" } ws.onmessage = function(event) { msg = event.data document.getElementById("short_msg").innerHTML = event.data; }
The client sends messages to the server over the WebSocket object as needed by the application.
function sendMsg() { // Check if connection is open before sending if(ws == null || ws.readyState != 1) { document.getElementById("reason").innerHTML = "Not connected can't send msg" } else { ws.send(document.getElementById("name").value); } } <input id="send_button" class="button" type="button" value="send" onclick="sendMsg()"/>
In some scenarios, applications must send messages to all of the open WebSocket connections. For example, a stock application must send stock prices to connected WebSocket clients, or a chat application must send messages from one user to all of the other clients in the same chat room.
In order to broadcast messages to all of the WebSocket clients, the application must first determine all of the open WebSocket connections using the getWebSocketConnections()
method in the WebSocketContext
interface. You can then iterate each WebSocketConnection
to send the message to each client.
The following brief code example demonstrates broadcasting messages to clients:
import weblogic.websocket.WebSocketListener; import weblogic.websocket.WebSocketConnection; import weblogic.websocket.WebSocketContext; @WebSocket(pathPatterns={"/demo"}) public class MyListener implements WebSocketListener { … public void broadcast(String message) { for(WebSocketConnection conn : getWebSocketContext().getWebSocketConnections()) { try { conn.send(message); } catch (IOException ioe) { // handle the error condition. } } } }
For real-world applications, two important aspects must be considered that are not addressed in the previous code example:
Efficiency
If too many WebSocket connections are open, then using one thread to broadcast messages is inefficient, because the time it takes for a client to receive a message depends on its location in the iteration process. If thousands of WebSocket connections are open, then iteration is slow, causing some clients to receive messages early and other clients to receive messages much later. This delay is unacceptable in certain situations; for example, a stock application should ensure that each client receives stock price data as early as possible.
To increase efficiency, the application can partition open WebSocket connections into groups and then use multiple threads to broadcast messages to each group of WebSocket connections.
Concurrency
The implementation of the WebSocketConnection
interface is not thread safe. If multiple threads send messages on the same WebSocketConnection
instance without a proper lock mechanism, then the messages could have issues. Problematic messages could cause connections to close unexpectedly because the client cannot correctly interpret a message.
Applications should choose the appropriate lock mechanism to ensure that when one thread sends messages on a particular WebSocketConnection
instance, no other threads can send messages on the same WebSocketConnection
instance.
In WebLogic Server, you deploy WebSocket applications as Web application archives (WARs), either as standalone Web applications or WAR modules within enterprise applications. Therefore, many security practices that you apply to securing Web applications can apply to WebSocket applications. For information about Web application security, see "Developing Secure Web Applications" in Developing Applications with the WebLogic Security Service.
The following sections describe security considerations for WebSocket applications in WebLogic Server:
Modern browsers use same-origin policies to prevent scripts that are running on Web pages loaded from one origin from interacting with resources from a different origin. The WebSocket Protocol (RFC 6455) uses a verified-origin policy that enables the server to decide whether or not to consent to a cross-origin connection.
When a script sends an opening handshake request to a WebSocket application, an Origin
HTTP header is sent with the WebSocket handshake request. If the application does not verify the Origin
, then it accepts connections from any origin. If the application is configured not to accept connections from origins other than the expected origin, then the WebSocket application can reject the connection. You can ensure that the WebSocket application verifies the Origin
through the accept
method of the WebSocketListener
implementation class.
The following code example demonstrates applying a verified-origin policy:
import weblogic.websocket.WebSocketListener; import weblogic.websocket.WSHandshakeRequest; import weblogic.websocket.WSHandshakeResponse; @WebSocket(pathPatterns={"/demo"}) public class MyListener implements WebSocketListener { private static final String ORIGIN = "http://www.example.com:7001"; public boolean accept(WSHandshakeRequest request, WSHandshakeResponse response) { return ORIGIN.equals(request.getOrigin()); } … }
Note: Nonbrowser clients (for example, Java Client) are not required to send an Because nonbrowser clients can send arbitrary |
The WebSocket Protocol (RFC 6455) does not specify an authentication method for WebSocket clients during the handshake process. You can use standard Web container authentication and authorization functionality to prevent unauthorized clients from opening WebSocket connections on the server.
Authentication
All configurations of the <auth-method>
element that are supported for Web applications can also be used for WebSocket applications. These authentication types include BASIC, FORM, CLIENT-CERT, and so on. For more information, see "Developing Secure Web Applications" in Developing Applications with the WebLogic Security Service.
You can secure the pathPatterns
attribute by configuring the relevant <security-constraint>
element in the web.xml
deployment descriptor file of the WebSocket application. By configuring <security-constraint>
, clients must authenticate themselves before sending WebSocket handshake requests. Otherwise, the server rejects the WebSocket handshake request. For more information about the <security-constraint>
element, see "web.xml Deployment Descriptor Elements" in Developing Web Applications, Servlets, and JSPs for Oracle WebLogic Server.
The following code example demonstrates securing pathPatterns
on the WebSocketListener
implementation class, where pathPatterns={"/demo"}
:
<security-constraint> <web-resource-collection> <web-resource-name>Secured WebSocket Endpoint</web-resource-name> <url-pattern>/demo/*</url-pattern> <http-method>GET</http-method> </web-resource-collection> <auth-constraint> <role-name>user</role-name> </auth-constraint> </security-constraint> <login-config> <auth-method>FORM</auth-method> <form-login-config> <form-login-page>/login.jsp</form-login-page> <form-error-page>/error.jsp</form-error-page> </form-login-config> </login-config> <security-role> <role-name>user</role-name> </security-role>
Authorization
You can configure a WebSocket application to authorize certain clients in the accept
method of the WebSocketListener
implementation class. If the application does not authorize a client to create a WebSocket connection, the server rejects the WebSocket handshake request from that client.
The following code example demonstrates configuring the accept
method of the WebSocketListener
implementation class:
import weblogic.websocket.WebSocketListener; import weblogic.websocket.WSHandshakeRequest; import weblogic.websocket.WSHandshakeResponse; @WebSocket(pathPatterns={"/demo"}) public class MyListener implements WebSocketListener { private static final String ORIGIN = "http://www.example.com:7001"; public boolean accept(WSHandshakeRequest request, WSHandshakeResponse response) { return ORIGIN.equals(request.getOrigin()) || hasPermission(request.getUserPrincipal()); } private boolean hasPermission(Principal user) { // Verifies whether the user is authorized to create this WebSocket connection. } … }
To establish a WebSocket connection, the client sends a handshake request to the server. When using the ws://
URI to open the WebSocket connection, the handshake request is a plain HTTP request; the data being transferred over the established WebSocket connection is not encrypted.
To establish a secure WebSocket connection and prevent data from being intercepted, WebSocket applications should use the wss://
URI. The wss://code> URI ensures that clients send handshake requests as HTTPS requests, encrypting transferred data by TLS/SSL.
You can configure a WebSocket application to accept only HTTPS handshake requests, where all WebSocket connections must be encrypted and nonencrypted WebSocket handshake requests are rejected. Specify the <user-data-constraint>
element in the web.xml
deployment descriptor file of the WebSocket application. For more information about the <user-data-constraint>
element, see "web.xml Deployment Descriptor Elements" in Developing Web Applications, Servlets, and JSPs for Oracle WebLogic Server.
The following code example demonstrates configuring the <user-data-constraint>
element:
<security-constraint> <web-resource-collection> <web-resource-name>Secured WebSocket Endpoint</web-resource-name> <url-pattern>/demo/*</url-pattern> <http-method>GET</http-method> </web-resource-collection> <auth-constraint> <role-name>user</role-name> </auth-constraint> <user-data-constraint> <transport-guarantee>CONFIDENTIAL</transport-guarantee> </user-data-constraint> </security-constraint>
If a script attempts to open a WebSockets connection through the ws://
URI (using a plain HTTP request), but the top-level Web page is retrieved through an HTTPS request, the Web page is referred to as mixed content. Although most browsers no longer allow mixed content, some still do. WebSocket applications should avoid mixed content, because it allows certain information that should be protected, such as JSESSIONID
and cookies, to be exposed.
For more information about mixed content, see "Web Security Context: User Interface Guidelines" at http://www.w3.org/TR/wsc-ui/#securepage
.
The WebLogic Server WebSocket API enables you to specify limits for WebSocket connections by configuring attributes of the @WebSocket
annotation. By configuring an application to specify limits, you can prevent clients from requesting a large number of connections and potentially exhausting server resources, such as memory, sockets, and so on.
You can specify the following limits:
timeout
The value of the timeout
attribute provides the idle timeout value of the WebSocket connection in seconds.
The WebSocket Protocol (RFC 6455) defines Ping and Pong control frames to keep WebSocket connections open. Instead of specifying large values in the timeout
attribute, applications should send Ping or Pong messages to keep WebSocket connections open.
maxMessageSize
The value of the maxMessageSize
attribute specifies the maximum size of a WebSocket message that the server can receive. The server rejects any message that exceeds this size. If a message is too large, then the client receives a closing frame message with the status code 1009, and the WebSocket connection closes. Applications should specify a reasonable value for this attribute.
For more information about status code 1009, see the WebSocket Protocol (RFC 6455) at http://tools.ietf.org/html/rfc6455
.
maxConnections
The value of the maxConnections
attribute specifies the maximum number of open connections on this WebSocket. If the number of open connections exceeds this value, then the server rejects any new WebSocket handshake requests. Applications should specify a reasonable value for this attribute.
The following code example demonstrates setting the previous limits:
import weblogic.websocket.WebSocketListener; import weblogic.websocket.WSHandshakeRequest; import weblogic.websocket.WSHandshakeResponse; @WebSocket(pathPatterns={"/demo"}, timeout=15, maxMessageSize=1024, maxConnections=1000) public class MyListener implements WebSocketListener { … }
Example 17-2 uses the WebLogic WebSocket API. In this example, the WebSocket listener receives messages from the browser, encapsulates the received messages, and sends them back to the browser.
Example 17-2 Using WebSockets with WebLogic Server
package examples.webapp.html5.websocket;
import weblogic.websocket.ClosingMessage;
import weblogic.websocket.WebSocketAdapter;
import weblogic.websocket.WebSocketConnection;
import weblogic.websocket.annotation.WebSocket;
import java.io.IOException;
@WebSocket(
timeout = -1,
pathPatterns = {"/ws/*"}
)
public class MessageListener extends WebSocketAdapter {
@Override
public void onMessage(WebSocketConnection connection, String payload) {
// Sends message from the browser back to the client.
String msgContent = "Message \"" + payload + "\" has been received by server.";
try {
connection.send(msgContent);
} catch (IOException e) {
connection.close(ClosingMessage.SC_GOING_AWAY);
}
}
}
The following sections describe tools for deploying applications and standalone modules to WebLogic Server:
The wldeploy
Ant task enables you to perform weblogic.Deployer
functions using attributes specified in an Ant XML file. You can use wldeploy
along with other WebLogic Server Ant tasks to create a single Ant build script that:
Builds your application from source, using wlcompile
, appc
, and the Web services Ant tasks.
Creates, starts, and configures a new WebLogic Server domain, using the wlserver
and wlconfig
Ant tasks.
Deploys a compiled application to the newly-created domain, using the wldeploy
Ant task.
See Chapter 2, "Using Ant Tasks to Configure and Use a WebLogic Server Domain," for more information about wlserver
and wlconfig
. See Chapter 5, "Building Applications in a Split Development Directory," for information about wlcompile
.
To use the wldeploy
Ant task:
Set your environment.
On Windows NT, execute the setWLSEnv.cmd
command, located in the directory WL_HOME
\server\bin
, where WL_HOME
is the top-level directory of your WebLogic Server installation.
On UNIX, execute the setWLSEnv.sh
command, located in the directory WL_HOME
/server/bin
, where WL_HOME
is the top-level directory of your WebLogic Server installation.
Note: On UNIX operating systems, the |
In the staging directory, create the Ant build file (build.xml
by default). If you want to use an Ant installation that is different from the one installed with WebLogic Server, start by defining the wldeploy
Ant task definition:
<taskdef name="wldeploy" classname="weblogic.ant.taskdefs.management.WLDeploy"/>
If necessary, add task definitions and calls to the wlserver
and wlconfig
tasks in the build script to create and start a new WebLogic Server domain. See Chapter 2, "Using Ant Tasks to Configure and Use a WebLogic Server Domain," for information about wlserver
and wlconfig
.
Add a call to wldeploy
to deploy your application to one or more WebLogic Server instances or clusters. See Sample build.xml Files for wldeploy and wldeploy Ant Task Attribute Reference.
Execute the Ant task or tasks specified in the build.xml
file by typing ant
in the staging directory, optionally passing the command a target argument:
prompt> ant
The following example shows a wldeploy
target that deploys an application to a single WebLogic Server instance:
<target name="deploy"> <wldeploy action="deploy" verbose="true" debug="true" name="DeployExample" source="output/redeployEAR" user="weblogic" password="weblogic" adminurl="t3://localhost:7001" targets="myserver" /> </target>
The following example shows a corresponding task to undeploy the application; the example shows that when you undeploy or redeploy an application, you do not specify the source archive file or exploded directory, but rather, just its deployed name.:
<target name="undeploy"> <wldeploy action="undeploy" verbose="true" debug="true" name="DeployExample" user="weblogic" password="weblogic" adminurl="t3://localhost:7001" targets="myserver" failonerror="false" /> </target>
The following example shows how to perform a partial redeploy of the application; in this case, just a single WAR file in the application is redeployed:
<target name="redeploy_partial"> <wldeploy action="redeploy" verbose="true" name="DeployExample" user="weblogic" password="weblogic" adminurl="t3://localhost:7001" targets="myserver" deltaFiles="examples/general/redeploy/SimpleImpl.war" /> </target>
The following example uses the nested <files>
child element of wldeploy
to specify a particular file in the application that should be undeployed:
<target name="undeploy_partial"> <wldeploy action="undeploy" verbose="true" debug="true" name="DeployExample" user="weblogic" password="weblogic" adminurl="t3://localhost:7001" targets="myserver" failonerror="false"> <files dir="${current-dir}/output/redeployEAR/examples/general/redeploy" includes="SimpleImpl.jsp" /> </wldeploy> </target>
The following example shows how to deploy a Java EE library called myLibrary
whose source files are located in the output/myLibrary
directory:
<target name="deploy"> <wldeploy action="deploy" name="myLibrary" source="output/myLibrary" library="true" user="weblogic" password="weblogic" verbose="true" adminurl="t3://localhost:7001" targets="myserver" /> </target>
The following sections describe the attributes and child element <files>
of the wldeploy
Ant task.
The following table describes the main attributes of the wldeploy
Ant task.
These attributes mirror some of the arguments of the weblogic.Deployer
command. Oracle provides an Ant task version of the weblogic.Deployer
command so that developers can easily deploy and test their applications as part of the iterative development process. Typically, however, administrators use the weblogic.Deployer
command, and not the wldeploy
Ant task, to deploy applications in a production environment. For that reason, see the "weblogic.Deployer Command-Line Reference" in Deploying Applications to Oracle WebLogic Server for the full and complete definition of the attributes of the wldeploy
Ant task. The table below is provided just as a quick summary.
Table B-1 Attributes of the wldeploy Ant Task
Attribute | Description | Data Type |
---|---|---|
action |
The deployment action to perform. Valid values are |
String |
adminmode |
Specifies that the deployment action puts the application into Administration mode. Administration mode restricts access to an application to a configured Administration channel. Valid values for this attribute are |
Boolean |
adminurl |
The URL of the Administration Server. The format of the value of this attribute is Note: In order to use the HTTP protocol, you must enable the http tunnelling option in the Administration Console. |
String |
allversions |
Specifies that the action (redeploy, stop, and so on) applies to all versions of the application. Valid values for this attribute are |
Boolean |
altappdd |
Specifies the name of an alternate Java EE deployment descriptor ( If you do not specify this attribute, and you are deploying an enterprise application, the default deployment descriptor is called |
String |
altwlsappdd |
Specifies the name of an alternate WebLogic Server deployment descriptor ( If you do not specify this attribute, and you are deploying an enterprise application, the default deployment descriptor is called |
String |
appversion |
The version identifier of the deployed application. |
String |
debug |
Enable |
Boolean |
deleteFiles |
Specifies whether to remove static files from a server's staging directory. This attribute is valid only for unarchived deployments, and only for applications deployed using Specifying the This attribute can be used only in combination with Because the Valid values for this attribute are true and false. Default value is false. |
Boolean |
deltaFiles |
Specifies a comma- or space-separated list of files, relative to the root directory of the application, which are to be redeployed. Use this attribute only in conjunction with |
String |
enableSecurityValidation |
Specifies whether or not to enable validation of security data. Valid values for this attribute are true and false. Default value is false. |
Boolean |
externalStage |
Specifies whether the deployment uses In this mode, the Ant task does not copy the deployment files to target servers; instead, you must ensure that deployment files have been copied to the correct subdirectory in the target servers' staging directories. You can specify only one of the following attributes: See "Controlling Deployment File Copying with Staging Modes". |
Boolean |
failonerror |
This is a global attribute used by WebLogic Server Ant tasks. It specifies whether the task should fail if it encounters an error during the build. Valid values for this attribute are true and false. Default value is true. |
Boolean |
graceful |
Stops the application after existing HTTP clients have completed their work. You can use this attribute only when stopping or undeploying an application, or in other words, you must also specify either the Valid values for this attribute are |
Boolean |
id |
Identification used for obtaining status or cancelling the deployment. You assign a unique ID to an application when you deploy it, and then subsequently use the ID when redeploying, undeploying, stopping, and so on. If you do not specify this attribute, the Ant task assigns a unique ID to the application. |
String |
ignoresessions |
This option immediately places the application into Administration mode without waiting for current HTTP sessions to complete. You can use this attribute only when stopping or undeploying an application, or in other words, you must also specify either the Valid values for this attribute are |
Boolean |
libImplVer |
Specifies the implementation version of a Java EE library or optional package. This attribute can be used only if the library or package does not include a implementation version in its manifest file. You can specify this attribute only in combination with the See Chapter 11, "Creating Shared Java EE Libraries and Optional Packages." |
String |
library |
Identifies the deployment as a shared Java EE library or optional package. You must specify the Valid values for this attribute are See Chapter 11, "Creating Shared Java EE Libraries and Optional Packages." |
Boolean |
libSpecVer |
Provides the specification version of a Java EE library or optional package. This attribute can be used only if the library or package does not include a specification version in its manifest file. You can specify this attribute only in combination with the See Chapter 11, "Creating Shared Java EE Libraries and Optional Packages." |
String |
name |
The deployment name for the deployed application. If you do not specify this attribute, WebLogic Server assigns a deployment name to the application, based on its archive file or exploded directory. |
String |
nostage |
Specifies whether the deployment uses nostage deployment mode. In this mode, the Ant task does not copy the deployment files to target servers, but leaves them in a fixed location, specified by the You can specify only one of the following attributes: See "Controlling Deployment File Copying with Staging Modes". |
Boolean |
noversion |
Indicates that the If you use this option, you cannot use versioned applications. Valid values for this attribute are true and false. Default value is false. |
Boolean |
nowait |
Specifies whether |
Boolean |
password |
The administrative password. To avoid having the plain text password appear in the build file or in process utilities such as If you want to obtain a user name and password from a non-default configuration file and key file, use the See the command reference for |
String |
plan |
Specifies a deployment plan to use when deploying the application or module. By default, |
String |
planversion |
The version identifier of the deployment plan. |
String |
remote |
Specifies whether the server is located on a different machine. This affects how filenames are transmitted. Valid values for this attribute are |
Boolean |
retiretimeout |
Specifies the number of seconds before WebLogic Server undeploys the currently-running version of this application or module so that clients can start using the new version. It is assumed, when you specify this attribute, that you are starting, deploying, or redeploying a new version of an already-running application. |
int |
securityModel |
Specifies the security model to use for this deployment. Possible security models are:
Valid actual values for this attribute are See "Options for Securing Web application and EJB Resources" for more information on these security models. |
String |
source |
The archive file or exploded directory to deploy. |
File |
stage |
Specifies whether the deployment uses stage deployment mode. In this mode, the Ant task copies deployment files to target servers' staging directories. You can specify only one of the following attributes: See "Controlling Deployment File Copying with Staging Modes". |
Boolean |
submoduletargets |
Specifies JMS server targets for resources defined within a JMS application module. The value of this attribute is a comma-separated list of JMS server names. See "Using Sub-Module Targeting with JMS Application Modules". |
String |
targets |
The list of target servers to which the application is deployed. The value of this at]tribute is a comma-separated list of the target servers, clusters, or virtual hosts. If you do not specify a target list when deploying an application, the target defaults to the Administration Server instance. |
String |
timeout |
The maximum number of seconds to wait for a deployment to succeed. |
int |
upload |
Specifies whether the source file(s) are copied to the Administration Server's upload directory prior to deployment. Use this attribute when you are on a remote machine and you cannot copy the deployment files to the Administration Server by other means. Valid values for this attribute are |
Boolean |
usenonexclusivelock |
Specifies that the deployment action (deploy, redeploy, stop, and so on) uses the existing lock on the domain that has already been acquired by the same user performing the action. This attribute is particularly useful when the user is using multiple deployment tools (Ant task, command line, Administration Console, and so on) simultaneously and one of the tools has already acquired a lock on the domain. Valid values for this attribute are |
Boolean |
user |
The administrative user name. |
String |
userconfigfile |
Specifies the location of a user configuration file to use for obtaining the administrative user name and password. Use this option, instead of the Before specifying the |
String |
userkeyfile |
Specifies the location of a user key file to use for encrypting and decrypting the user name and password information stored in a user configuration file (the Before specifying the |
String |
verbose |
Specifies whether |
Boolean |
The wldeploy
Ant task also includes the <files>
child element that can be nested to specify a list of files on which to perform a deployment action (for example, a list of JSPs to undeploy.)
Note: : Use of |
The <files>
element works the same as the standard <fileset>
Ant task (except for the difference in actual task name). Therefore, see the Apache Ant Web site at http://ant.apache.org/manual/Types/fileset.html
for detailed reference information about the attributes you can specify for the <files>
element.
This preface describes the document accessibility features and conventions used in this guide—Developing Applications for Oracle WebLogic Server.
For information about Oracle's commitment to accessibility, visit the Oracle Accessibility Program website at http://www.oracle.com/pls/topic/lookup?ctx=acc&id=docacc
.
Access to Oracle Support
Oracle customers have access to electronic support through My Oracle Support. For information, visit http://www.oracle.com/pls/topic/lookup?ctx=acc&id=info
or visit http://www.oracle.com/pls/topic/lookup?ctx=acc&id=trs
if you are hearing impaired.
The following text conventions are used in this document:
Convention | Meaning |
---|---|
boldface |
Boldface type indicates graphical user interface elements associated with an action, or terms defined in text or the glossary. |
italic |
Italic type indicates book titles, emphasis, or placeholder variables for which you supply particular values. |
|
Monospace type indicates commands within a paragraph, URLs, code in examples, text that appears on the screen, or text that you enter. |
This chapter describes how to start and stop WebLogic Server instances and configure WebLogic Server domains using WebLogic Ant tasks in your development build scripts.
This chapter includes the following sections:
Overview of Configuring and Starting Domains Using Ant Tasks
Starting Servers and Creating Domains Using the wlserver Ant Task
Configuring a WebLogic Server Domain Using the wlconfig Ant Task
WebLogic Server provides a pair of Ant tasks to help you perform common configuration tasks in a development environment. The configuration tasks enable you to start and stop WebLogic Server instances as well as create and configure WebLogic Server domains.
When combined with other WebLogic Ant tasks, you can create powerful build scripts for demonstrating or testing your application with custom domains. For example, a single Ant build script can:
Compile your application using the wlcompile
, wlappc
, and Web services Ant tasks.
Create a new single-server domain and start the Administration Server using the wlserver
Ant task.
Configure the new domain with required application resources using the wlconfig
Ant task.
Deploy the application using the wldeploy
Ant task.
Automatically start a compiled client application to demonstrate or test product features.
The sections that follow describe how to use the configuration Ant tasks, wlserver
and wlconfig
.
The wlserver
Ant task enables you to start, reboot, shutdown, or connect to a WebLogic Server instance. The server instance may already exist in a configured WebLogic Server domain, or you can create a new single-server domain for development by using the generateconfig=true
attribute.
When you use the wlserver
task in an Ant script, the task does not return control until the specified server is available and listening for connections. If you start up a server instance using wlserver, the server process automatically terminates after the Ant VM terminates. If you only connect to a currently-running server using the wlserver
task, the server process keeps running after Ant completes.
The wlserver
WebLogic Server Ant task extends the standard java
Ant task (org.apache.tools.ant.taskdefs.Java
). This means that all the attributes of the java
Ant task also apply to the wlserver
Ant task. For example, you can use the output
and error
attributes to specify the name of the files to which output and standard errors of the wlserver
Ant task is written, respectively. For full documentation about the attributes of the standard Java Ant task, see Java on the Apache Ant site (http://ant.apache.org/manual/Tasks/java.html
).
To use the wlserver
Ant task:
Set your environment.
On Windows, execute the setWLSEnv.cmd
command, located in the directory WL_HOME
\server\bin
, where WL_HOME
is the top-level directory of your WebLogic Server installation.
On UNIX, execute the setWLSEnv.sh
command, located in the directoryWL_HOME
\server\bin
, where WL_HOME
is the top-level directory of your WebLogic Server installation.
Note: The <taskdef name="wlserver" classname="weblogic.ant.taskdefs.management.WLServer"/> |
Note: On UNIX operating systems, the |
Add a call to the wlserver
task in the build script to start, shutdown, restart, or connect to a server. See wlserver Ant Task Reference for information about wlserver
attributes and default behavior.
Execute the Ant task or tasks specified in the build.xml
file by typing ant
in the staging directory, optionally passing the command a target argument:
prompt> ant
Use ant -verbose
to obtain more detailed messages from the wlserver
task.
The following shows a minimal wlserver
target that starts a server in the current directory using all default values:
<target name="wlserver-default"> <wlserver/> </target>
This target connects to an existing, running server using the indicated connection parameters and user name/password combination:
<target name="connect-server"> <wlserver host="127.0.0.1" port="7001" username="weblogic" password="weblogic" action="connect"/> </target>
This target starts a WebLogic Server instance configured in the config
subdirectory:
<target name="start-server"> <wlserver dir="./config" host="127.0.0.1" port="7001" action="start"/> </target>
This target creates a new single-server domain in an empty directory, and starts the domain's server instance:
<target name="new-server"> <delete dir="./tmp"/> <mkdir dir="./tmp"/> <wlserver dir="./tmp" host="127.0.0.1" port="7001" generateConfig="true" username="weblogic" password="weblogic" action="start"/> </target>
The following table describes the attributes of the wlserver
Ant task.
Table 2-1 Attributes of the wlserver Ant Task
Attribute | Description | Data Type | Required? |
---|---|---|---|
policy |
The path to the security policy file for the WebLogic Server domain. This attribute is used only for starting server instances. |
File |
No |
dir |
The path that holds the domain configuration (for example, |
File |
No |
beahome |
The path to the Middleware Home directory (for example, |
File |
No |
weblogichome |
The path to the WebLogic Server installation directory (for example, |
File |
No |
servername |
The name of the server to start, shutdown, reboot, or connect to. A WebLogic Server instance is uniquely identified by its protocol, host, and port values, so if you use this set of attributes to specify the server you want to start, shutdown or reboot, you do not need to specify its actual name using the The default value for this attribute is |
String |
Required only when shutting down the Administration server. |
domainname |
The name of the WebLogic Server domain in which the server is configured. |
String |
No |
adminserverurl |
The URL to access the Administration Server in the domain. This attribute is required if you are starting up a Managed Server in the domain. |
String |
Required for starting Managed Servers. |
username |
The user name of an administrator account. If you omit both the |
String |
No |
password |
The password of an administrator account. If you omit both the |
String |
No |
pkpassword |
The private key password for decrypting the SSL private key file. |
String |
No |
timeout |
The maximum time, in milliseconds, that The default value for this attribute is |
long |
No |
timeoutSeconds |
The maximum time, in seconds, that The default value for this attribute is |
long |
No |
productionmodeenabled |
Specifies whether a server instance boots in development mode or in production mode. Development mode enables a WebLogic Server instance to automatically deploy and update applications that are in the Valid values for this attribute are Note: If you boot the server in production mode by setting this attribute to |
Boolean |
No |
host |
The DNS name or IP address on which the server instance is listening. The default value for this attribute is |
String |
No |
port |
The TCP port number on which the server instance is listening. The default value for this attribute is |
int |
No |
generateconfig |
Specifies whether or not Valid values for this attribute are |
Boolean |
No |
action |
Specifies the action The The default value for this attribute is |
String |
No |
failonerror |
This is a global attribute used by WebLogic Server Ant tasks. It specifies whether the task should fail if it encounters an error during the build. Valid values for this attribute are |
Boolean |
No |
forceshutdown |
This optional attribute is used in conjunction with the
|
Boolean |
No |
noExit |
(Optional) Leave the server process running after Ant exits. Valid values are |
Boolean |
No |
protocol |
Specifies the protocol that the Valid values are |
String |
No |
forceImplicitUpgrade |
Specifies whether the Valid values are For more information about upgrading domains, see Upgrading Oracle WebLogic Server. |
Boolean |
No. |
configFile |
Specifies the configuration file for your domain. The value of this attribute must be a valid XML file that conforms to the XML schema as defined in the WebLogic Server Domain Configuration Schema at The XML file must exist in the Administration Server's root directory, which is either the current directory or the directory that you specify with the If you do not specify this attribute, the default value is |
String |
No. |
useBootProperties |
Specifies whether to use the Note: The values of the |
Boolean |
No |
verbose |
Specifies that the Ant task output additional information as it is performing its action. Valid values for this attribute are |
Boolean |
No |
The following sections describe how to use the wlconfig
Ant task to configure a WebLogic Server domain.
Note:: The For equivalent functionality, you should use the WebLogic Scripting Tool (WLST). See Understanding the WebLogic Scripting Tool. |
The wlconfig
Ant task enables you to configure a WebLogic Server domain by creating, querying, or modifying configuration MBeans on a running Administration Server instance. Specifically, wlconfig
enables you to:
Create new MBeans, optionally storing the new MBean Object Names in Ant properties.
Set attribute values on a named MBean available on the Administration Server.
Create MBeans and set their attributes in one step by nesting set attribute commands within create MBean commands.
Query MBeans, optionally storing the query results in an Ant property reference.
Query MBeans and set attribute values on all matching results.
Establish a parent/child relationship among MBeans by nesting create commands within other create commands.
Set your environment in a command shell. See Basic Steps for Using wlserver for details.
Note: The <taskdef name="wlconfig" classname="weblogic.ant.taskdefs.management.WLConfig"/> |
wlconfig
is commonly used in combination with wlserver
to configure a new WebLogic Server domain created in the context of an Ant task. If you will be using wlconfig
to configure such a domain, first use wlserver
attributes to create a new domain and start the WebLogic Server instance.
Add an initial call to the wlconfig
task to connect to the Administration Server for a domain. For example:
<target name="doconfig">
<wlcon fig url="t3://localhost:7001" username="weblogic"
password=password>
</target>
Add nested create
, delete
, get
, set
, and query
elements to configure the domain.
Execute the Ant task or tasks specified in the build.xml
file by typing ant
in the staging directory, optionally passing the command a target argument:
prompt> ant doconfig
Use ant -verbose
to obtain more detailed messages from the wlconfig
task.
Note: Since WLST is the recommended tool for domain creation scripts, you should refer to the WLST offline sample scripts that are installed with the software. The offline scripts demonstrate how to create domains using the domain templates and are located in the following directory: |
The following sections describe the attributes and elements that can be used with wlconfig
.
The following table describes the main attributes of the wlconfig
Ant task.
Table 2-2 Main Attributes of the wlconfig Ant Task
Attribute | Description | Data Type | Required? |
---|---|---|---|
url |
The URL of the domain's Administration Server. |
String |
Yes |
username |
The user name of an administrator account. |
String |
No |
password |
The password of an administrator account. To avoid having the plain text password appear in the build file or in process utilities such as If you want to obtain a user name and password from a non-default configuration file and key file, use the See the command reference for |
String |
No |
failonerror |
This is a global attribute used by WebLogic Server Ant tasks. It specifies whether the task should fail if it encounters an error during the build. This attribute is set to true by default. |
Boolean |
No |
userconfigfile |
Specifies the location of a user configuration file to use for obtaining the administrative user name and password. Use this option, instead of the Before specifying the |
File |
No |
userkeyfile |
Specifies the location of a user key file to use for encrypting and decrypting the user name and password information stored in a user configuration file (the Before specifying the |
File |
No |
wlconfig
also has several elements that can be nested to specify configuration options:
The create
element creates a new MBean in the WebLogic Server domain. The wlconfig
task can have any number of create
elements.
A create
element can have any number of nested set
elements, which set attributes on the newly-created MBean. A create
element may also have additional, nested create
elements that create child MBeans.
The create
element has the following attributes.
Table 2-3 Attributes of the create Element
Attribute | Description | Data Type | Required? |
---|---|---|---|
name |
The name of the new MBean object to create. |
String |
No ( |
type |
The MBean type. |
String |
Yes |
property |
The name of an optional Ant property that holds the object name of the newly-created MBean. Note: If you nest a |
String |
No |
The delete
element removes an existing MBean from the WebLogic Server domain. delete
takes a single attribute:
The set
element sets MBean attributes on a named MBean, a newly-created MBean, or on MBeans retrieved as part of a query. You can include the set
element as a direct child of the wlconfig
task, or nested within a create
or query
element.
The set
element has the following attributes:
Table 2-5 Attributes of the set Element
Attribute | Description | Data Type | Required? |
---|---|---|---|
attribute |
The name of the MBean attribute to set. |
String |
Yes |
value |
The value to set for the specified MBean attribute. You can specify multiple object names (stored in Ant properties) as a value by delimiting the entire value list with quotes and separating the object names with a semicolon. |
String |
Yes |
mbean |
The object name of the MBean whose values are being set. This attribute is required only when the |
String |
Required only when the |
domain |
This attribute specifies the JMX domain name for Security MBeans and third-party SPI MBeans. It is not required for administration MBeans, as the domain corresponds to the WebLogic Server domain. Note: You cannot use this attribute if the |
String |
No |
The get
element retrieves attribute values from an MBean in the WebLogic Server domain. The wlconfig
task can have any number of get
elements.
The get
element has the following attributes.
Table 2-6 Attributes of the get Element
Attribute | Description | Data Type | Required? |
---|---|---|---|
attribute |
The name of the MBean attribute whose value you want to retrieve. |
String |
Yes |
property |
The name of an Ant property that will hold the retrieved MBean attribute value. |
String |
Yes |
mbean |
The object name of the MBean you want to retrieve attribute values from. |
String |
Yes |
The query
elements finds MBean that match a search pattern.
The query element supports the following nested child elements:
set
—performs set operations on all MBeans in the result set.
get
—performs get operations on all MBeans in the result set.
create
—each MBean in the result set is used as a parent of a new MBean.
delete
—performs delete operations on all MBeans in the result set.
invoke
—invokes all matching MBeans in the result set.
wlconfig
can have any number of nested query
elements.
query
has the following attributes:
Table 2-7 Attributes of the query Element
Attribute | Description | Data Type | Required? |
---|---|---|---|
domain |
The name of the WebLogic Server domain in which to search for MBeans. |
String |
No |
type |
The type of MBean to query. |
String |
No |
name |
The name of the MBean to query. |
String |
No |
pattern |
A JMX query pattern. |
String |
No |
property |
The name of an optional Ant property that will store the query results. |
String |
No |
domain |
This attribute specifies the JMX domain name for Security MBeans and third-party SPI MBeans. It is not required for administration MBeans, as the domain corresponds to the WebLogic Server domain. |
String |
No |
The invoke
element invokes a management operation for one or more MBeans. For WebLogic Server MBeans, you usually use this command to invoke operations other than the get
Attribute
and set
Attribute
that most WebLogic Server MBeans provide.
The invoke
element has the following attributes.
Table 2-8 Attributes of the invoke Element
Attribute | Description | Data Type | Required? |
---|---|---|---|
mbean |
The object name of the MBean you want to invoke. |
String |
You must specify either the |
type |
The type of MBean to invoke. |
String |
You must specify either the |
methodName |
The method of the MBean to invoke. |
String |
Yes |
arguments |
The list of arguments (separated by spaces) to pass to the method specified by the |
String |
No |
Use the libclasspath
Ant task to build applications that use libraries, such as application libraries and Web libraries.
To use the task with your own Ant installation, add the following task definition in your build file:
<taskdef name="libclasspath" classname="weblogic.ant.taskdefs.build.LibClasspathTask"/>
The following sections describe the attributes and elements that can be used with the libclasspath
Ant task.
The following table describes the main attributes of the libclasspath
Ant task.
Table 2-9 Attributes of the libclasspath Ant Task
Attribute | Description | Required |
---|---|---|
basedir |
The root of . |
Either |
basewar |
The name of the .war file to extract from. |
If |
tmpdir |
The fully qualified name of the directory to be used for extracting libraries. |
Yes. |
classpathproperty |
Contains the classpath for the referenced libraries. For example, if Additionally, if |
At least one of the two attributes is required. |
resourcepathproperty |
Contains library resources that are not classes. For example, if |
libclasspath
also has two elements that can be nested to specify configuration options. At least one of the elements is required when using the libclasspath
Ant task:
The following attribute is required when using this element:
dir
—Specifies that all files in this directory are registered as available libraries.
This section provides example code of a libclasspath
Ant task:
Example 2-1 Example libclasspath Ant Task Code
.
.
.
<taskdef name="libclasspath" classname="weblogic.ant.taskdefs.build.LibClasspathTask"/>
<!-- Builds classpath based on libraries defined in weblogic-application.xml. -->
<target name="init.app.libs">
<libclasspath basedir="${src.dir}" tmpdir="${tmp.dir}" classpathproperty
="app.lib.classpath">
<librarydir dir="${weblogic.home}/common/deployable-libraries/"/>
</libclasspath>
<echo message="app.lib.claspath is ${app.lib.classpath}" level="info"/>
</target>
.
.
.