Packaging WebLogic Server Applications

Packaging WebLogic Server Applications

Overview

WebLogic Server J2EE applications are packaged according to J2EE specifications. J2EE defines module behaviors and packaging in a generic, portable way, postponing run-time configuration until the module is actually deployed on an application server.
J2EE includes deployment specifications for Webapps, EJB modules, enterprise applications, client applications, and connectors. J2EE 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. Modules and applications may include Java classes for EJBs and servlets, resource adapters, Web pages and supporting files, XML deployment descriptors, and more.
An application that is ready to deploy on WebLogic Server may require WebLogic-specific deployment descriptors and, possibly, container classes. These can be generated using the WebLogic appc compiler.

Packaging Applications as Part of an Enterprise Application

An enterprise application consists of assembled Webapp modules, EJB modules, and resource adapters. For both production and development purposes, BEA recommends that you package and deploy your stand-alone Webapps, EJBs, and resource adapters as part of an enterprise application.
This is a BEA best practice, which allows for easier application migration, additions, and changes. For example, to add more than one Webapp, EJB, or resource adapter module to an application, package the modules in an enterprise application. If you package and deploy stand-alone applications in an enterprise application from the start, this saves you a lot of time.
Also, packaging your applications as part of an enterprise application allows you to take advantage of the split development directory structure, which provides a number of benefits over the traditional single directory structure.
For production purposes, BEA further recommends that you package your enterprise application in an exploded (unarchived) directory structure. This allows you to update files in the exploded directory rather than having to unarchive, edit, and rearchive the whole application.
However, you can also package the enterprise application as an archive (EAR) file using the jar utility and giving the file an .ear extension. Archived files are easier to distribute and take up less space.

Split Development Directory Structure

In a development environment, BEA recommends that you use the new WebLogic split development directory structure to build WebLogic Server applications. The split development directory structure is compatible with enterprise applications only. BEA therefore recommends that you package stand-alone Webapps, EJBs, and connectors as part of an enterprise application so that you can take advantage of this structure.
This structure is optimized for iterative development on a single WebLogic Server instance. Rather than having a single archived EAR file or an exploded enterprise application directory structure, the split development directory structure provides two parallel directories. The source directory contains all of the source files (such as Java files, descriptors, JSP files, HTML, and so on) in a traditional EAR-like directory structure. All of the generated or compiled classes are stored in a separate output directory.
The split development directory structure provides several important benefits over the traditional structure:

You no longer have to copy over large quantities of files (deployment descriptors, JSP files, image files, and so on) from the source file into the output directory where you have compiled your Java files.
You can make changes to files and redeploy them in place without having to rebuild the application. Using the traditional JAR-centric directory structure, when you copy files into your output directory, you are unable to edit them there and have the server automatically detect these changes. This is not an issue with the split development directory structure.
You have clean separation between source and output files. This allows for cleaning the build by just removing the output directory.

Using the split development directory structure, you specify the output directory when deploying the application to WebLogic Server. WebLogic Server automatically recognizes the deployment as a split development directory structure and uses information in the output directory to locate the source directory. WebLogic Server views the application as a union of the source and output directories. When it searches for a resource or class, it first checks the source directory. If it does not locate the class or resource, it then checks the output directory.
The split development directory structure is accompanied in WebLogic Server by a set of Ant tasks for building, packaging, and deploying applications as traditional EAR files for production use.

Example Split Development Directory

The following is a working example of a split development directory structure, taken from the BEA MedRec sample provided with this release. The MedRec example uses the split development directory structure, which you can use as a template to build your application. You can find the MedRec example at:
$WL_HOME/weblogic81/samples/server/medrec/
Listing 3-1 illustrates the medrecEar/ enterprise application in a split development directory structure. It illustrates the source (src/) and output (build/) directories of the split development directory structure for an EJB (webServicesEJB/) and a Webapp (patientWebApp/). As usual, the enterprise application descriptors are contained in the META-INF/ directory.Listing 3-1 Example Split Development Directory: medrecEAR/ Enterprise Application
medrec/src/medrecEar/META-INF/application.xml medrec/src/medrecEar/META-INF/weblogic-application.xml medrec/src/medrecEar/webServicesEjb/META-INF/ejb-jar.xml medrec/src/medrecEar/webServicesEjb/META-INF/weblogic-ejb-jar.xml medrec/src/medrecEar/webServicesEjb/com/bea/medrec/webservices/MedRecWebServicesEJB.java medrec/src/medrecEar/webServicesEjb/com/bea/medrec/webservices/MedRecWebServicesHome.java medrec/src/medrecEar/webServicesEjb/com/bea/medrec/webservices/MedRecWebServicesEJB.java medrec/src/medrecEar/webServicesEjb/com/bea/medrec/webservices/... medrec/src/medrecEar/patientWebApp/WEB-INF/web.xml medrec/src/medrecEar/patientWebApp/WEB-INF/weblogic.xml medrec/src/medrecEar/patientWebApp/WEB-INF/classes... medrec/src/medrecEar/patientWebApp/WEB-INF/src... medrec/src/medrecEar/patientWebApp/*.jsp medrec/src/medrecEar/patientWebApp/images/*.gif medrec/build/medrecEar/webServicesEjb/com/bea/medrec/webservices/*.class medrec/build/medrecEAR/patientWebApp/WEB-INF/classes/... medrec/build/medrecEAR/patientWebApp/WEB-INF/lib/...

JAR Files and Java Utility Classes

Listing 3-2 illustrates where .jar and .class files are stored. These files are visible and shared throughout the enterprise application.
You can extend the enterprise application to use third-party .jar files by placing in the APP-INF/lib/ directory. Third-party JARs usually own their own code and are not recompiled. For example, XML parsers, logging implementations, and other utility JAR files are common.
You can also extend the enterprise application to use Java utility classes. Java utility classes differ from third-party JARs in that the source files are part of the application and must be compiled. Java utility classes are typically libraries used by application modules such as EJBs or Webapps. The wlcompile Ant task invokes the javac compiler and compiles these files into the APP-INF/classes/ directory under the output (build/) directory. These classes are available throughout the application.
Listing 3-2 shows the following:

lib/exceptions.jar - shared MedRec exceptions
lib/utils.jar - shared utilities
lib/value.jar - shared value objects
lib/log4j-1.2.4.jar - an added, shared third-party JAR
classes/com/bea/medrec/... - contains Java utility classes
Listing 3-2 JAR and Java Utility Classes
medrec/src/medrecEar/APP-INF/lib/exceptions.jar medrec/src/medrecEar/APP-INF/lib/utils.jar medrec/src/medrecEar/APP-INF/lib/values.jar medrec/src/medrecEar/APP-INF/lib/log4j-1.2.4.jar medrec/build/medrecEar/APP-INF/classes/com/bea/medrec/...

Creating the build.xml File

Once you have set up your directory structure, you create the build.xml file using the weblogic.BuildXMLGen utility.

weblogic.BuildXMLGen

weblogic.BuildXMLGen is a utility that generates an Ant build.xml file for enterprise applications in the split development directory structure. This utility analyzes the source (src/) directory and creates build and deploy targets for the enterprise application as well as individual modules. It also creates targets to clean the build and generate new deployment descriptors.
After running weblogic.BuildXMLGen, you can use the following Ant command to view more information on the generated targets: -projecthelp
The syntax for weblogic.BuildXMLGen is as follows:
java weblogic.BuildXMLGen [options] <source directory>

where options include:

-help - print standard usage message
-version - print version information
-projectName <project name> - name of the Ant project
-d <directory> - directory where build.xml is created. The default is the current directory.
-file <build.xml> - name of the generated build file
-username <username> - user name for deploy commands
-password <password> - user password

Example MedRec build.xml File

The following is a build.xml file for our example medrecEAR enterprise application. It contains the following three "targets," or actions:

build - calls wlcompile and compiles the application.
package - takes the build output and generates a traditional exploded EAR.
clean - deletes the output (build/) directory.

Note: Each Ant build.xml can have multiple targets, which are basically actions. The above targets (actions) build, package, and clean the application. You specify the target as: ant <target>Listing 3-3 Example build.xml
<project name="medrec ear" default="build">  <property name="medrec.ear.src.dir" value="." />  <property name="dest.dir" value="${medrec.ear.wlcompile.build.dir}" />  <property name="ear.file" value="${medrec.ear.file}" />  <property name="ear.exploded.dir" value="${medrec.ear.exploded.dir}" />  <target name="build.split.dir" depends="banner,prepare">  <wlcompile srcdir="${medrec.ear.src.dir}" destdir="${dest.dir}" excludes="adminWebApp, xml, mdbEjbs, webServicesEjb"/>  <wlcompile srcdir="${medrec.ear.src.dir}" destdir="${dest.dir}" includes="xml, webServicesEjb" classpath="${java.class.path};${dest.dir}/sessionEjbs"/>  <wlcompile srcdir="${medrec.ear.src.dir}" destdir="${dest.dir}" includes="mdbEjbs, adminWebApp"/> </target>  <target name="ear"> <wlpackage srcdir="${medrec.ear.src.dir}" destdir="${dest.dir}" toFile="${ear.file}"/> </target> <target name="clean.exploded.ear"> <delete dir="${ear.exploded.dir}"/> </target> </project>

Exploded (Unarchived) Directory

For production purposes, BEA recommends that you package enterprise applications in exploded (unarchived) directory format. This applies also to stand-alone Webapps, EJBs, and connectors packaged as part of an enterprise application. This is considered a BEA best practice. Using this format allows you to update files directly in the exploded directory rather than having to unarchive, edit, and rearchive the whole application.
Note: You can convert split development directory enterprise applications to exploded EARs using the wlpackage Ant task.
Listing 3-1 is a good example of an exploded directory.

Archived File (Using the jar Utility)

For production purposes, you can also package applications in an archived file using the Java jar utility. An archived file created using the jar utility bundles the files in a directory into a single Java ARchive (JAR) file, maintaining the directory structure. JAR files are convenient for packaging modules and applications for distribution. They 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 J2EE modules on WebLogic Server in either a JAR (archived) file or an exploded (unarchived) directory.
WebLogic Server requires you to adhere to the following programmatic naming conventions for application archive files:

Enterprise JavaBean JAR archived files must end with the .jar extension.
Resource adapter RAR archived files must end with the .rar extension.
Webapp WAR archived files end with the .war extension.
Enterprise application EAR archived files end with the .ear extension.

A jar utility is in the bin directory of your Java Development Kit. If you have javac in your path, you also have jar in your path. The jar command syntax and behavior is similar to the UNIX tar command.
The most common usages of the jar command are:
jar cf jar-file files ...
Creates a JAR file named jar-file containing listed files. If you include a directory in the list of files, all files in that directory and its subdirectories are added to the JAR file.
jar xf jar-file
Extract (unbundle) a JAR file in the current directory.
jar tf jar-file
List (tell) the contents of a JAR file.
The first flag specifies the operation: create, extract, or list (tell). The f flag must be followed by a JAR file name. Without the f flag, jar reads or writes JAR file contents on stdin or stdout which is usually not what you want.
The following is an example of an archived enterprise application using the MedRec example:Listing 3-4 Archived File
medrec/dist/medrecEar.ear

Packaging Web Applications

If your Webapp is accessed by a programmatic Java client, see About Client Applications, which describes how WebLogic Server loads your application classes.
Note: When packaging your Webapp, BEA recommends that you package it as part of an enterprise application. This allows you to take advantage of the split development directory structure, which provides a number of benefits over the traditional single directory structure.
To package a Webapp:

Create a temporary staging directory anywhere on your hard drive. You can name this directory anything you want. For example:
myProject/myWebApp

Copy all of your HTML files, JSP files, images, and any other files that these Web pages reference into the staging directory, maintaining the directory structure for referenced files. For example, if an HTML file has a tag such as <img src="images/pic.gif">, the pic.gif file must be in the images subdirectory beneath the HTML file.
Create META-INF and WEB-INF/classes subdirectories in the staging directory to hold deployment descriptors and compiled Java classes. For example:
myProject/myWebApp/META-INF

myProject/myWebApp/WEB-INF/classes

Copy or compile any servlet classes and helper classes into the WEB-INF/classes subdirectory.
Copy the home and remote interface classes for enterprise beans used by the servlets into the WEB-INF/classes subdirectory.
Copy JSP tag libraries into the WEB-INF subdirectory. (Tag libraries may be installed in a subdirectory beneath WEB-INF ; the path to the .tld file is coded in the .jsp file.)
Set up your shell environment.

On Windows NT, execute the setenv.cmd command, located in the directory server/bin/setenv.cmd, where server is the top-level directory in which WebLogic Server is installed.
On UNIX, execute the setenv.sh command, located in the directory server/bin/setenv.sh, where server is the top-level directory in which WebLogic Server is installed.
Execute the following command to automatically generate the web.xml and weblogic.xml deployment descriptors in the WEB-INF subdirectory:
java weblogic.ant.taskdefs.war.DDInit staging-dir

where staging-dir refers to the staging directory.

Alternatively, you can create the web.xml and weblogic.xml files manually in the WEB-INF subdirectory.
When all of the Webapp classes and deployment descriptors are set up in the staging directory, you can maintain it as an exploded (unarchived) directory or archive it by creating the Webapp WAR file with a jar command such as:
jar cvf myapp.war -C staging-dir

The resulting WAR file can be added to an Enterprise application (EAR file) or deployed independently using the console or the weblogic.Deployer command-line utility. Note: Now that you have packaged your Webapp, see Deploying WebLogic Server Applications for instructions on deploying applications in WebLogic Server.

Packaging Enterprise JavaBeans

You can stage one or more Enterprise JavaBeans in a directory and package them in an EJB JAR file. If your EJB is accessed by a programmatic Java client, see About Client Applications, which describes how WebLogic Server loads your EJB classes.
Note: When packaging your EJB, BEA recommends that you package it as part of an enterprise application. This allows you to take advantage of the split development directory structure, which provides a number of benefits over the traditional single directory structure.
To package an Enterprise JavaBean (EJB):

Create a temporary staging directory anywhere on your hard drive. For example:
myProject/myEJB

Compile or copy the bean's Java classes into the staging directory.
Create a META-INF subdirectory in the staging directory. For example:
myProject/myEJB/META-INF

Set up your shell environment.

On Windows NT, execute the setenv.cmd command, located in the directory server/bin/setenv.cmd, where server is the top-level directory in which WebLogic Server is installed.
On UNIX, execute the setenv.sh command, located in the directory server/bin/setenv.sh, where server is the top-level directory in which WebLogic Server is installed and domain refers to the name of your domain.
If you are creating EJB 2.0 beans, execute the following command to automatically generate the ejb-jar.xml, weblogic-ejb-jar.xml, and weblogic-rdbms-cmp-jar-bean_name.xml (if needed) deployment descriptors in the META-INF subdirectory:
java weblogic.ant.taskdefs.ejb20.DDInit staging-dir

where staging-dir refers to the staging directory.

If you are using EJB 1.1, execute the following command:
java weblogic.ant.taskdefs.ejb11.DDInit staging-dir

Alternatively, you can create the EJB deployment descriptor files manually. Create an ejb-jar.xml and weblogic-ejb-jar.xml files in the META-INF subdirectory. If the bean is an entity bean with container-managed persistence, create a weblogic-rdbms-cmp-jar-bean_name.xml deployment descriptor in the META-INF directory with entries for the bean. Map the bean to this CMP deployment descriptor with a <type-storage> attribute in the weblogic-ejb-jar.xml file.
When all of the enterprise bean classes and deployment descriptors are set up in the staging directory, you can maintain it as an exploded (archived) directory or archive it by creating the EJB JAR file with a jar command such as:
jar cvf jar-file.jar -C staging-dir

This command creates a JAR file that you can deploy on WebLogic Server. The resulting JAR file can be added to an Enterprise application (EAR file) or deployed independently using the console or the weblogic.Deployer command-line utility.
The -C staging-dir option instructs the jar command to change to the staging-dir directory so that the directory paths recorded in the JAR file are relative to the directory where you staged the enterprise beans.
Enterprise beans require container classes, classes the WebLogic EJB compiler generates to allow the bean to deploy in a WebLogic Server. The WebLogic EJB compiler reads the deployment descriptors in the EJB JAR file to determine how to generate the classes. You can run the WebLogic EJB compiler on the JAR file before you deploy the beans, or you can let WebLogic Server run the compiler for you at deployment time. Note: Now that you have packaged your EJB, see Deploying WebLogic Server Applications for instructions on deploying applications in WebLogic Server.

Using ejb-client.jar

WebLogic Server supports the use of ejb-client.jar files. Create an ejb-client.jar file by specifying this feature in the bean's ejb-jar.xml deployment descriptor file and then generating the ejb-client.jar file using weblogic.appc. An ejb-client.jar contains the class files that a client program needs to call the EJBs contained in the ejb-jar file. The files are the classes required to compile the client. If you specify this feature, WebLogic Server automatically creates the ejb-client.jar.

Packaging Res ourc e Adapters

After you stage one or more resource adapters in a directory, you package them in a Java Archive (JAR). Before you package a resource adapter, be sure you read and understand the chapter entitled WebLogic Server Application Classloading " in this guide, which describes how WebLogic Server loads classes.
Note: When packaging the resource adapter, BEA recommends that you package it as part of an enterprise application. This allows you to take advantage of the split development directory structure, which provides a number of benefits over the traditional single directory structure.
To package a resource adapter :

Create a temporary staging directory anywhere on your hard drive. For example:
myProject/myResourceAdapter

Compile or copy the resource adapter Java classes into the staging directory.
Create a JAR to store the resource adapter Java classes. Add this JAR to the top level of the staging directory.
Create a META-INF subdirectory in the staging directory. For example:
myProject/myResourceAdapter/META-INF

Create a ra.xml deployment descriptor in the META-INF subdirectory and add entries for the resource adapter.

Refer to the following Sun Microsystems documentation for information on the ra.xml document type definition at: http://java.sun.com/dtd/connector_1_0.dtd
Create a weblogic-ra.xml deployment descriptor in the META-INF subdirectory and add entries for the resource adapter.
When the resource adapter classes and deployment descriptors are set up in the staging directory, you can maintain it as an exploded (unarchived) directory or archive it by creating the resource adapter RAR file with a jar command such as:
jar cvf jar-file.rar -C staging-dir

This command creates a RAR file. The resulting RAR file can be added to an Enterprise application (EAR file) or deployed independently using the console or the weblogic.Deployer command-line utility.
The -C staging-dir option instructs the jar utility to change to the staging-dir directory so that the directory paths recorded in the JAR are relative to the directory where you staged the resource adapters.

Packaging Enterprise Appl ications

An enterprise application archive (EAR file) contains EJB and Web modules that are bundled together, along with the enterprise application deployment descriptor files, in an archive file with an EAR extension. The following instructions assume that you are packaging your enterprise application using the BEA-preferred split development directory structure.

Enterprise Applications Deployment Descriptor Files

The META-INF subdirectory in an EAR file contains an application.xml deployment descriptor provided by the application assembler; the format definition of this deployment descriptor is provided by Sun Microsystems. The application.xml deployment descriptor identifies the modules packaged in the EAR file.
You can find the DTD for the application.xml file at http://java.sun.com/j2ee/dtds/application_1_2.dtd.
Within application.xml, you define items such as the modules that make up your application and the security roles used within your application. The following is the application.xml file from the MedRec example:
<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE application PUBLIC '-//Sun Microsystems, Inc.//DTD J2EE Application 1.2//EN' 'http://java.sun.com/j2ee/dtds/application_1_2.dtd'> <application> <display-name>Medical Records Patient Application</display-name> <description>Medical Records Patient Application</description> <module> <web> <web-uri>adminWebApp</web-uri> <context-root>admin</context-root> </web> </module> <module> <ejb>entityEJBs</ejb> </module> <security-role> <description>the gold patient role</description> <role-name>gold_patient</role-name> </security-role> <security-role> <description>the patient role</description> <role-name>patient</role-name> </security-role> </application>

A supplemental deployment descriptor, weblogic-application.xml contains additional WebLogic-specific deployment information.

Packaging Enterprise Applications: Main Steps

If your enterprise application is accessed by a programmatic Java client, see About Client Applications, which describes how WebLogic Server loads your enterprise application classes.
To package an Enterprise application:

Create a temporary staging directory anywhere on your hard drive. For example:
myProject/myEnterpriseApp

Copy the Web archives (WAR files), EJB archives (JAR files), and Resource Adapter archives (RAR files) into the staging directory.
Create a META-INF subdirectory in the staging directory. For example:
myProject/myEnterpriseApp/META-INF

Set up your shell environment.

On Windows NT, execute the setenv.cmd command, located in the directory server/bin/setenv.cmd, where server is the top-level directory in which WebLogic Server is installed.
On UNIX, execute the setenv.sh command, located in the directory server/bin/setenv.sh, where server is the directory in which WebLogic Server is installed.
Execute the following command to automatically generate the application.xml deployment descriptor in the META-INF subdirectory:
java weblogic.ant.taskdefs.ear.DDInit staging-dir

where staging-dir refers to the staging directory.

Alternatively, you can create the application.xml file automatically in the META-INF directory.
Optionally create the weblogic-application.xml file manually in the META-INF directory, as described in Application Deployment Descriptor Elements.
Package your enterprise application files using the WebLogic split development directory structure. Rather than having a single archived EAR file or an exploded EAR directory structure, the split development directory structure has two parallel directories. This directory structure is optimized for development on a single WebLogic Server. Note: Now that you have packaged your enterprise application, see Deploying WebLogic Server Applications for instructions on deploying applications in WebLogic Server.

Split Development Directory Ant Tasks

WebLogic Server provides the following Ant tasks for the split development directory structure:

wlcompile - This Ant task compiles the split development directory application's Java files.
wlpackage - This Ant task packages a split development directory application as a traditional EAR file.
wldeploy - This Ant task deploys a split development directory application to WebLogic Server.

wlcompile

One uses the wlcompile Ant task to compile your application's Java files in a split development directory structure. The following is the order in which events occur using this task:

wlcompile analyzes the application modules in a split development directory structure and determines their type. It recognizes the modules as either an EJBs, Webapps, or Java modules.
wlcompile compiles the application modules into an output directory, making them visible throughout the application:

/medrec/build/medrecEAR/APP-INF/classes
wlcompile builds the EJBs and automatically includes the previously built Java modules in the compiler's classpath. This allows the EJBs to call the Java modules without requiring you to manually edit their classpath.
Finally, wlcompile compiles the Java files in the Webapp with the EJB and Java modules in the compiler's classpath. This allows the Webapps to refer to the EJB and application Java classes without requiring you to manually edit the classpath.

The following is an example based upon MedRec. You can find the MedRec example at: WL_HOME/weblogic81/samples/server/medrec/
Example:
Compile the entire application. Source files located in /medrec/src/physicianEAR are compiled to the output directory /medrec/build/physicianEAR, as follows:
<wlcompile srcdir="/src/physicianEAR" destdir="/build/physicianEAR"/>

By default, wlcompile builds the entire application. You can also configure wlcompile to build a single module. This is especially useful when you are developing large applications in which you make isolated changes and require a faster build. When wlcompile builds a single module, it only rebuilds that module. It does not track dependencies between modules. Therefore, it does not rebuild any other modules that depend on the rebuilt module.
For example, you can build only the physicianWebApp module as follows:
<wlcompile srcdir="/src/physicianEAR/physicianWebApp"
destdir="/build/physicianEAR/physicianWebApp">
<module name="physicianWebApp" />
</wlcompile>
wlcompile automatically "guesses" the type of each module in the application. In general, this guessing works well. However, in some cases - especially when modules are incomplete - wlcompile cannot accurately determine the type.
The common case where wlcompile fails is when you are developing an EJB. Typically, you first compile your Java files, make sure everything works, and then write your deployment descriptors. wlcompile is unable to determine that this module is an EJB when it does not yet have a deployment descriptor.
wlcompile allows you to specify a module's type in cases where the guessing is not correct. For example, you can build only the physSessionEjbs module and hardcode it to be an EJB, as follows:
<wlcompile srcdir="/src/physicianEAR/physSessionEjbs"
destdir="/build/physicianEAR/physSessionEjbs">
<module name="physSessionEjbs" type="EJB"/>
</wlcompile>

wlpac kage

One uses 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" />

About Client Applications

Although not required for WebLogic Server applications, J2EE includes a standard for deploying client applications. A J2EE client application module contains the Java classes that execute in the client JVM (Java Virtual Machine ) and deployment descriptors that describe EJBs (Enterprise JavaBeans) and other WebLogic Server resources used by the client.
A de-facto standard deployment descriptor application-client. xml from Sun is used for J2EE clients and a supplemental deployment descriptor contains additional WebLogic-specific deployment information.

Executing a Client Application in an EAR File

In order to simplify distribution of an application, J2EE defines a way to include client-side modules in an EAR file, along with the server-side modules that are used by WebLogic Server. This enables both the server-side and client-side modules to be distributed as a single unit.
The client JVM must be able to locate the Java classes you create for your application and any Java classes your application depends upon, including WebLogic Server classes. You stage a client application by copying all of the required files on the client into a directory and bundling the directory in a JAR file. The top level of the client application directory can have a batch file or script to start the application. Create a classes subdirectory to hold Java classes and JAR files, and add them to the client Class-Path in the startup script. You may also want to package a Java Runtime Environment (JRE) with a Java client application.
Note: The use of the Class-Path manifest entries in client module JARs is not portable, because it has not yet been addressed by the J2EE standard.
The Main-Class attribute of the JAR file manifest defines the main class for the client application. The client typically uses java:/comp/env JNDI lookups to execute the Main-Class attribute. As a deployer, provide runtime values for the JNDI lookup entries and populate the module local JNDI tree before calling the client's Main-Class attribute. You define JNDI lookup entries in the client deployment descriptor. (Refer to Client Application Deployment Descriptor Elements. )
One uses weblogic.ClientDeployer to extract the client-side JAR file from a J2EE EAR file, creating a deployable JAR file. The weblogic.ClientDeployer class is executed on the Java command line with the following syntax:
java weblogic.ClientDeployer ear-file client

The ear-file argument is an expanded directory (or Java archive file with a .ear extension) that contains one or more client application JAR files.
For example:

java weblogic.ClientDeployer app.ear myclient
where app.ear is the EAR file that contains a J2EE client packaged in myclient.jar.
Once the client-side JAR file is extracted from the EAR file, use the weblogic.j2eeclient.Main utility to bootstrap the client-side application and point it to a WebLogic Server instance as follows:

java weblogic.j2eeclient.Main clientjar URL [application args]
For example:

java weblogic.j2eeclient.Main helloWorld.jar t3://localhost:7001 Greetings

Special Considerations for Deploying J2EE Client Applications

The following is a list of special considerations for deploying J2EE client applications:

Name the WebLogic Server client deployment file using the suffix .runtime.xml.
The weblogic.ClientDeployer class is responsible for generating and adding a client.properties file to the client JAR file. A separate program, weblogic.j2eeclient.Main, creates a local client JNDI context and runs the client from the entry point named in the client manifest file. Note: To run the J2EE client application using weblogic.ClientDeployer, you need the weblogic.j2eeclient.Main class (located in the weblogic.jar file).
If a resource mentioned by the application-client. xml file is one of the following types, the weblogic.j2eeclient.Main class attempts to bind it from the global JNDI tree on the server to java:comp/env/:
ejb-ref javax.jms.QueueConnectionFactory javax.jms.TopicConnectionFactory javax.mail.Session javax.sql.DataSource

The weblogic.j2eeclient.Main class binds UserTransaction to java:comp/UserTransaction.
The rest of the client environment is bound from the client.properties file created by the weblogic.ClientDeployer class into java:comp/env/. The weblogic.j2eeclient.Main class emits error messages for missing or incomplete bindings.
The <res-auth> tag in the application deployment file is currently ignored and should be entered as Application. We do not currently support form-based authentication.