BEA Logo BEA WebLogic Server Release 6.1

  Corporate Info  |  News  |  Solutions  |  Products  |  Partners  |  Services  |  Events  |  Download  |  How To Buy

   Developing WebLogic Server Applications:   Previous topic   |   Next topic   |   Contents   


Packaging and Deploying WebLogic Server Applications


The following sections describe how to package and deploy WebLogic Server applications:

Packaging Overview

WebLogic Server applications are packaged in a standard way, defined by the J2EE specifications. J2EE defines component behaviors and packaging in a generic, portable way, postponing run-time configuration until the component is actually deployed on an application server.

J2EE includes deployment specifications for Web applications, EJB modules, Enterprise applications, and Client applications. J2EE does not specify how an application is deployed on the target server-only how a standard component or application is packaged.

For each component type, the specifications define the files required and their location in the directory structure. Components and applications may include Java classes for EJBs and servlets, Web pages and supporting files, XML-formatted deployment descriptors, and JAR files containing other components.

An application that is ready to deploy on WebLogic Server contains additional, WebLogic-specific deployment descriptors and, possibly, container classes generated with the WebLogic EJB, RMI, or JSP compilers.

JAR Files

A file created with the Java jar utility bundles the files in a directory into a single Java ARchive (JAR) file, maintaining the directory structure. 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 components on WebLogic Server in either an "exploded" directory or a JAR file.

JAR files are convenient for packaging components 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. If your Administration Server manages a domain with multiple WebLogic Servers, you can only deploy JAR files, because the Administration Console does not copy expanded directories to managed servers.

The 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. See the documentation for the JDK utilities for more about jar command options.

XML Deployment Descriptors

Components 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 J2EE specifications define standard, portable deployment descriptors for J2EE components and applications. BEA defines additional WebLogic-specific deployment descriptors required to deploy a component or application in the WebLogic Server environment.

Table 3-1 lists the types of components and applications and their J2EE-standard and WebLogic-specific deployment descriptors.

Table 3-1 J2EE and WebLogic Deployment Descriptors

Component or


Deployment Descriptors

Web Application





Enterprise Bean






Enterprise Application



Client Application




When you package a component or application, you create a directories to hold the deployment descriptors-WEB-INF or META-INF-and then create the required XML deployment descriptors in that directory.

If you receive a J2EE-compliant JAR file from a developer, it already contains J2EE-defined deployment descriptors. To deploy the JAR file on WebLogic Server, you must extract the contents of the JAR file into a directory, add the required WebLogic-specific deployment descriptors and any generated container classes, and then create a new JAR file containing the old and new files.

Packaging Web Applications

To stage and package a Web application:

  1. Create a temporary staging directory.

  2. 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.

  3. Create META-INF and WEB-INF/classes subdirectories in the staging directory to hold deployment descriptors and compiled Java classes.

  4. Copy or compile any servlet classes and helper classes into the WEB-INF/classes subdirectory.

  5. Copy the home and remote interface classes for enterprise beans used by the servlets into the WEB-INF/classes subdirectory.

    Note: See Classloader Overview to understand how the WebLogic Server class-loading mechanism affects EJB references from servlets within the same application.

  6. 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.)

  7. Create web.xml and weblogic.xml deployment descriptors in the WEB-INF subdirectory.

    Note: See Writing Web Application Deployment Descriptors for help creating deployment descriptors for Web applications.

  8. Bundle the staging directory into a .war file by executing a jar command such as the following:

    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 Administration Console or the weblogic.deploy command-line utility.

Packaging Enterprise JavaBeans

You can stage one or more enterprise beans in a directory and package them in an EJB JAR file.

To stage and package an enterprise bean:

  1. Create a temporary staging directory.

  2. Compile or copy the bean's Java classes into the staging directory.

  3. Create a META-INF subdirectory in the staging directory.

  4. Create an ejb-jar.xml deployment descriptor in the META-INF subdirectory and add entries for the bean.

  5. Create a weblogic-ejb-jar.xml deployment descriptor in the META-INF subdirectory and add entries for the bean.

  6. 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.

    Note: See "Programming WebLogic EJB" for help compiling enterprise beans and creating EJB deployment descriptors.

  7. When all of the enterprise bean classes and deployment descriptors are set up in the staging directory, you can create 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 a WebLogic Server or package in an application JAR file.

    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. See Programming WebLogic EJB for help with the WebLogic EJB compiler.

Packaging Enterprise Applications

An Enterprise archive contains EJB and Web modules that are part of a related application. The EJB and Web modules are bundled together in another JAR file with an .ear extension.

The META-INF subdirectory in an .ear file contains an application.xml deployment descriptor, which identifies the modules packaged in the .ear file. You can find the DTD for the application.xml file at No WebLogic-specific deployment descriptor is needed for an enterprise archive.

Here is the application.xml file from the Pet Store example:

<?xml version="1.0"  encoding="UTF-8"?>

<!DOCTYPE application PUBLIC '-//Sun Microsystems, Inc.//DTD
J2EE Application 1.2//EN'

<description>Application description</description>
<description>the gold customer role</description>
<description>the customer role</description>

To stage and package an Enterprise application:

  1. Create a temporary staging directory.

  2. Copy the Web archives (.war files) and EJB archives (.jar files) into the staging directory.

  3. Create a META-INF subdirectory in the staging directory.

  4. Create the application.xml deployment descriptor in the META-INF subdirectory.

  5. Create the Enterprise Archive (.ear file) for the application, using a jar command such as:

    jar cvf application.ear -C staging-dir .

The resulting .ear file can be deployed using the Administration Console or the weblogic.deploy command-line utility.

Resolving Class References Between Components

Your applications may use many different Java classes, including enterprise beans, servlets and JavaServer Pages, startup classes, utility classes, and third-party packages. WebLogic Server deploys applications in separate classloaders to maintain independence and to facilitate dynamic redeployment and undeployment. Because of this, you need to package your application classes in such a way that each component has access to the classes it depends on. In some cases, you may have to include a set of classes in more than one application or component. This section describes how WebLogic Server uses multiple classloaders so that you can stage your applications successfully.

Classloader Overview

A classloader is a Java class that locates and loads a requested class into the Java virtual machine (JVM). A classloader resolves references by searching for files in the directories or JAR files listed in its classpath. Most Java programs have a single classloader, the default system classloader created when the JVM starts up. WebLogic Server creates additional classloaders when it deploys applications because these classloaders can be destroyed in order to undeploy the application. This allows WebLogic Server to redeploy modified applications without having to restart the server.

Classloaders are hierarchical. When you start WebLogic Server, the Java system classloader is active and is the parent of all subsequent classloaders that WebLogic Server creates. A classloader always asks its parent for a class before it searches its own classpath, but a parent classloader does not consult its children. Because the search only proceeds upwards in the classloader hierarchy, this also means that a child classloader cannot locate classes on a sibling's classpath.

The search protocol also clarifies how duplicate classes are handled in Java. Classes located in the Java system classpath always have precedence over any class with the same name in a child classloader's classpath. Because of this, you should avoid placing application classes in the Java system classpath before you start WebLogic Server. The classloader created at startup time cannot be destroyed, so any classes it contains cannot be redeployed without restarting WebLogic Server.

About Application Classloaders

When WebLogic Server deploys an application, it creates two new classloaders: one for EJBs and one for Web applications. The EJB classloader is a child of the Java system classloader and the Web application classloader is a child of the EJB classloader. This allows classes in a Web application to locate EJB classes, but EJB classes cannot locate Web application classes. A positive side-effect of this classloader hierarchy is that it allows servlets and JSPs direct access to EJB implementation classes. WebLogic Server can bypass the intermediate RMI classes because the EJB client and implementation are in the same JVM.

If your application includes servlets and JSPs that use enterprise beans:

Although you could deploy the .war and .jar files separately, deploying them together in an .ear file produces a classloader arrangement that allows the servlets and JSPs to find the EJB classes. If you deploy the .war and .ejb files separately, WebLogic Server creates sibling classloaders for them. You must include the EJB home and remote interfaces in the .war file, and WebLogic Server must use the RMI stub and skeleton classes for EJB calls, just as it does when EJB clients and implementation classes are in different JVMs.

Packaging Common Utilities and Third-Party Classes

If you create or acquire utility classes that you will use in more than one application, you must package them with each application. Alternatively, you could add them to the Java system classpath by editing the java command in the script that runs WebLogic Server. If you modify your utility classes and they are in the Java system classpath, however, you will have to restart WebLogic Server.

Classes that WebLogic Server uses during startup must be in the Java system classpath. For example, JDBC drivers used for connection pools must be in the classpath when you start WebLogic Server. Again, if you need to modify classes in the Java system classpath, or modify the classpath itself, you will have to restart WebLogic Server.

Handling Interactions Between Startup Classes and Applications

Startup classes are classes you create that WebLogic Server executes at startup time. Startup classes are located by the Java system classpath, so you must put them in the system classpath before you start the server. Also, any classes they require must be included in the system classpath.

If a startup class uses application classes (such as EJB interfaces) you will also have to add those classes to the WebLogic Server startup classpath. Unfortunately, this means that you cannot modify those classes without restarting the server.

Startup classes that use application objects must wait for WebLogic Server to finish deploying the applications before they attempt to access the application objects. For example, if a startup class uses EJBs, you must include the home and remote interfaces in the system classpath, and you must ensure that the startup class does not create any EJB instances until WebLogic Server has finished deploying the EJB application.

The Pet Store application has a startup class that demonstrates one method a startup class can use to wait for applications to finish deploying. The com.bea.estore.startup.StartBrowser startup class displays the initial URL to access the Pet Store application, and on Windows it also launches the browser with the URL. StartBrowser executes a while loop until applications have deployed and the server begins accepting connection requests.

Here is an excerpt from that class to show how this works:

while (loop) {
try {
socket = new Socket(host, new Integer(port).intValue());

//launch browser
String[] cmdArray = new String[3];
cmdArray[0] = "beaexec.exe";
cmdArray[1] = "-target:browser";
cmdArray[2] = "-command:\"http://"+host+":"+port+"\"";
try {
Process p = Runtime.getRuntime().exec(cmdArray);
catch (IOException ioe) {
loop = false;
} catch (Exception e) {
try {
Thread.sleep(SLEEPTIME); // try every 500 ms
} catch (InterruptedException ie) {}
finally {
try {
} catch (Exception se) {}

If the system fails to create a socket, or if the BEA-supplied beaexec.exe utility returns an error, the class sleeps for 500 milliseconds before repeating the loop. If a startup class needs to create an EJB instance, it could use a similar technique by looping until the EJB create method succeeds.

Deploying Applications and Components

You can deploy an EJB JAR, Web application, or Enterprise application by using the Administration Console or the weblogic.deploy command-line utility. You can also use either method to undeploy or redeploy an updated application.

The .jar, .ear, or .war file must be correctly structured and contain all of the necessary deployment descriptors described in previous sections.

Note: If you have a single WebLogic Server, you can deploy applications and components by copying them to the server's applications subdirectory. In this case, files do not need to be packaged in JAR files. The ability to refresh individual files in the applications directory is useful for testing during development. However, using JAR files is recommended for production applications.

Using the Administration Console

To deploy an application using the Administration Console:

  1. Start the Administration Console.

  2. In the left pane, expand Deployments.

  3. Under Deployments, click Applications.

  4. In the right pane, click Browse, and find the .ear, .jar, or .war file containing the component or application you want to install.

  5. Click Upload.

    This copies the file to the Administration Server's applications directory.

  6. Expand the new application under the Applications node to reveal the components.

  7. For each of the components in the application, click the component name in the left pane, then complete the information on the Configuration and Targets tabs in the right pane. Consult the online help to find details about the values on these tabs.

  8. Click on the application name under the Applications node, and check the Deployed check box in the right pane.

  9. Click Apply.

Depending on your choices, you may need to restart WebLogic Server. The Administration Console displays a restart message in the right pane.

Using the weblogic.deploy Command-Line Utility

The weblogic.deploy command-line utility allows you to deploy, undeploy, update, and list components on an Administration Server-tasks you can accomplish interactively using the Administration Console. The weblogic.deploy command line utility can be used in scripts, which is especially useful during development.

See the documentation for weblogic.deploy in the Administration Guide for syntax and usage for this command line-utility.

Packaging and Deploying Client Applications

WebLogic Server applications written in Java run in a JVM on a client machine. 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. This usually means distributing the weblogic_sp.jar and weblogic.jar files to the client and adding them to the client's classpath.

You may also want to package a Java Runtime Environment (JRE) with a Java client application.

You can stage a client application by copying all of the files required on the client into a directory and bundling the directory up in a .zip file, or a .jar file if you know that clients have already installed a Java environment with the jar utility.

The top level of the client application directory can have a batch file or script to start the application. Make a classes subdirectory to hold Java classes and .jar files, and add them to the client's classpath in the startup script.

J2EE Client

Although not required for WebLogic Server applications, J2EE includes a standard for deploying client applications. A J2EE Client application module is packaged in a .jar file. The .jar file contains the Java classes that execute in the client JVM and deployment descriptors that describe Enterprise JavaBeans and other WebLogic resources used by the client.

A standard deployment descriptor from Sun is used for J2EE clients and a supplemental deployment descriptor contains additional WebLogic-specific deployment information.

See Client Application Deployment Descriptor Elements for help with these deployment descriptors.

On the client, the weblogic.ClientDeployer utility starts a J2EE client application on the client machine. This 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 an .ear extension, that contains one or more Client application .jar files.

For example:

java appclient.ClientDeployer app.ear client

In this example, the app.ear file is a JAR file that contains a J2EE client packaged in the client.jar JAR file.


Back to Top