BEA Home | Events | Solutions | Partners | Products | Services | Download | Developer Center | WebSUPPORT
| WebLogic Server Doc Home | Developing Applications | Previous Topic | Next Topic | Contents | Index | View as PDF

Packaging WebLogic Server J2EE Applications

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

- Packaging Overview

- Packaging Web Applications

- Packaging Enterprise JavaBeans

- Packaging Resource Adapters

- Packaging Enterprise Applications

- Packaging Client Applications

- Packaging J2EE Applications Using Apache Ant

- Packaging Client Applications

Packaging Overview

WebLogic Server J2EE 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, client applications, and resource adapters. 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, resource adapters, 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 Application | Scope | Deployment Descriptors
--- | --- | ---
Web Application | J2EE | WEB-INF/web.xml
WebLogic | WEB-INF/weblogic.xml
Enterprise Bean | J2EE | META-INF/ejb-jar.xml
WebLogic | META-INF/weblogic-ejb-jar.xml META-INF/weblogic-cmp-rdbms-jar.xml
Resource Adapter | J2EE | META-INF/ra.xml
WebLogic | META-INF/weblogic-ra.xml
Enterprise Application | J2EE | META-INF/application.xml
Client Application | J2EE | application-client.xml
WebLogic | client-application.runtime.xml

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.

You can create the deployment descriptors by hand, or you can use WebLogic-specific Java-based utilities to automatically generate them for you. For more information about generating deployment descriptors, see Automatically Generating Deployment Descriptors.

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.

Automatically Generating Deployment Descriptors

WebLogic Server includes a set of Java-based utilities that automatically generate the deployment descriptors for the following J2EE components or applications: Web applications, Enterprise JavaBeans (versions 1.1 and 2.0), and Enterprise Applications.

These utilities examine the objects you have assembled in a staging directory and build the appropriate deployment descriptors based on the servlet classes, EJB classes, and so on. The utilities generate both the standard J2EE and WebLogic-specific deployment descriptors for each component.

WebLogic Server includes the following utilities:

- weblogic.ant.taskdefs.ejb.DDInit

  Creates the deployment descriptors for Enterprise JavaBeans 1.1.

- weblogic.ant.taskdefs.ejb20.DDInit

  Creates the deployment descriptors for Enterprise JavaBeans 2.0.

- weblogic.ant.taskdefs.war.DDInit

  Creates the deployment descriptors for Web applications.

- weblogic.ant.taskdefs.ear.DDInit

  Creates the deployment descriptors for Enterprise Applications.

Note: Although these utilities attempt to create deployment descriptor files that are complete and accurate for your component or application, the utilities must guess at the value of many of the required elements. Often this guess is wrong, causing WebLogic Server to return an error when you deploy the component or application. In this case, you must undeploy the component or application, edit the deployment descriptor using the Deployment Descriptor Editor of the Administration Console, and then redeploy it. For details on using the Deployment Descriptor Editor, see Editing Deployment Descriptors.

Each utility takes a single parameter: the root directory that contains the objects in the component or application for which you are generating deployment descriptors. The root directory is the one that contains the WEB-INF or META-INF subdirectories.

For example, assume that you have created a directory called c:\stage that contains the WEB-INF directory, 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:

>     $ java weblogic.ant.taskdefs.war.DDInit c:\stage

The utility generates the web.xml and weblogic.xml deployment descriptors and places them in the WEB-INF directory.

Development Mode vs. Production Mode

You can run WebLogic Server in two different modes: development and production. You determine this mode by configuring the STARTMODE script variable, which is a variable you can modify in domain_name\startWebLogic. The STARTMODE variable allows you to toggle the start mode from production to development.

To enable development mode, configure the STARTMODE script variable as follows:

-Dweblogic.ProductionModeEnabled=false

To enable production mode, set the variable as follows:

-Dweblogic.ProductionModeEnabled=true

Note: The default setting is false.

For more information on starting WebLogic Server in development and production modes, refer to "Starting and Stopping WebLogic Servers."

When you specify development mode, you can use the auto-deploy feature of the applications directory. This means that you can copy new files into the applications directory of your Administration Server, located in the config/domain_name directory of the WebLogic Server installation (where domain_name is the name of a WebLogic Server domain). The aplications will be automatically deployed and updated.

In production mode, you must use the WebLogic Server Administration Console or the weblogic.Deploy tool to redeploy an application. Both deployment methods require a user name and password. This addresses security concerns around users who have write access to the file system and have the ability to deploy applications on the server.

Packaging Web Applications

Before you package your Web application, be sure you read and understand Packaging Client Applications which describes how WebLogic server loads your application classes.

To stage and package a Web application:

1. Create a temporary staging directory. You can name this directory anything you want.

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. Set up your shell environment.

   On Windows NT, execute the setEnv.cmd command, located in the directory BEA_HOME\config\domain, where BEA_HOME is the directory in which WebLogic Server is installed and domain refers to the name of your domain.

   On UNIX, execute the setEnv.sh command, located in the directory BEA_HOME/config/domain, where BEA_HOME is the directory in which WebLogic Server is installed and domain refers to the name of your domain.

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

   For more information on the Java-based DDInit utility for generating deployment descriptors, see Automatically Generating Deployment Descriptors.

   Alternatively, you can create the web.xml and weblogic.xml files in the WEB-INF subdirectory by hand.

   Note: See Assembling and Configuring Web Applications for detailed descriptions of the elements of the web.xml and weblogic.xml files.

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

Before you package your EJBs, be sure you read and understand Packaging Client Applications which describes how WebLogic server loads your EJB classes.

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. Set up your shell environment.

   On Windows NT, execute the setEnv.cmd command, located in the directory BEA_HOME\config\domain, where BEA_HOME is the directory in which WebLogic Server is installed and domain refers to the name of your domain.

   On UNIX, execute the setEnv.sh command, located in the directory BEA_HOME/config/domain, where BEA_HOME is the directory in which WebLogic Server is installed and domain refers to the name of your domain.

5. 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.ejb.DDInit staging-dir

   where staging-dir refers to the staging directory. Use this utility for EJB 1.1. If you are creating EJB 2.0, use the following utility:

   >     java weblogic.ant.taskdefs.ejb20.DDInit staging-dir

   For more information on the Java-based DDInit utility for generating deployment descriptors, see Automatically Generating Deployment Descriptors.

   Alternatively, you can create the EJB deployment descriptor files by hand. 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.

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

6. 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 Enterprise JavaBeans for help with the WebLogic EJB compiler.

Packaging Resource Adapters

You can stage one or more resource adapters in a directory and package them in a JAR file.

Before you package your resource adapters, be sure you read and understand Packaging Client Applications which describes how WebLogic server loads classes.

To stage and package a resource adapter:

1. Create a temporary staging directory.

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

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

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

   Note: Refer to the following Sun Microsystems documentation for information on the ra.xml document type definition:

   http://java.sun.com/dtd/connector_1_0.dtd

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

   Note: Refer to Programming the WebLogic J2EE Connector Architecture for information on the weblogic-ra.xml document type definition.

6. When all of the resource adapter classes and deployment descriptors are set up in the staging directory, you can create the resource adapter 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 resource adapters.

   Note: For instructions on creating a resource adapter and modifying an existing resource adapter for deployment to WebLogic Server, see Creating Resource Adapters: Main Steps of Developing WebLogic Server J2EE Applications.

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 http://java.sun.com/j2ee/dtds/application_1_2.dtd. 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'
>     'http://java.sun.com/j2ee/dtds/application_1_2.dtd'>

>     <application>
>       <display-name>estore</display-name>
>       <description>Application description</description>
>       <module>
>         <web>
>           <web-uri>petStore.war</web-uri>
>           <context-root>estore</context-root>
>         </web>
>       </module>
>       <module>
>         <ejb>petStore_EJB.jar</ejb>
>       </module>
>       <security-role>
>         <description>the gold customer role</description>
>         <role-name>gold_customer</role-name>
>       </security-role>
>       <security-role>
>         <description>the customer role</description>
>         <role-name>customer</role-name>
>       </security-role>
>     </application>

Before you package your enterprise application, be sure you read and understand Packaging Client Applications which describes how WebLogic server loads your enterprise application classes.

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. Set up your shell environment.

   On Windows NT, execute the setEnv.cmd command, located in the directory BEA_HOME\config\domain, where BEA_HOME is the directory in which WebLogic Server is installed and domain refers to the name of your domain.

   On UNIX, execute the setEnv.sh command, located in the directory BEA_HOME/config/domain, where BEA_HOME is the directory in which WebLogic Server is installed and domain refers to the name of your domain.

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

   For more information on the Java-based DDInit utility for generating deployment descriptors, see Automatically Generating Deployment Descriptors.

   Alternatively, you can create the application.xml file by hand in the META-INF directory. See Appendix A, "application.xml Deployment Descriptor Elements," for detailed information about the elements in this file.

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

Packaging Client Applications

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. This JAR file 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.

Note: See "application.xml Deployment Descriptor Elements" in Appendix A, "application.xml Deployment Descriptor Elements," for help with these deployment descriptors.

Executing a Client Application in an EAR File

In order to simplify distribution of an application, J2EE defines a way to include client-side components 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 components 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 component 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, you must provide runtime values for the JNDI lookup entries and populate the component 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.")

You use 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.

Packaging J2EE Applications Using Apache Ant

The topics in this section discuss building and packaging J2EE applications using Apache Ant, an extensible Java-based tool. Ant is similar to the make command but is designed for building Java applications. Ant libraries are bundled with WebLogic Server to make it easier for our customers to build Java applications out of the box.

Developers write Ant build scripts using eXtensible Markup Language (XML). XML tags define the targets to build, dependencies among targets, and tasks to execute in order to build the targets.

For a complete explanation of ant capabilities, see: http://jakarta.apache.org/ant/manual/index.html

Compiling Java Source Files

Ant provides a javac task for compiling Java source files. The following example compiles all of the Java files in the current directory into a classes directory.

>     <target name="compile">

>       <javac srcdir="." destdir="classes"/>

>     </target>

Refer to Apache Ant online documentation for a full set of options relating to the javac task.

Running WebLogic Server Compilers

Running arbitrary Java programs from Ant can be accomplished by either writing custom Ant tasks or by simply executing the program using the java task. Tasks such as ejbc or rmic can be executed using the java task as shown below:

Listing 3-1 Running WebLogic Server Compilers

>     <java classname="weblogic.ejbc" fork="yes" failonerror="yes">

>       <sysproperty key="weblogic.home" value="${WL_HOME}"/>

>          <arg line="-compiler java ${dist}/std_ejb_basic_containerManaged.jar

>          ${APPLICATIONS}/ejb_basic_containerManaged.jar"/>

>       <classpath>

>          <pathelement path="${CLASSPATH}"/>

>       </classpath>

>     </java>

The above example uses the fork system call to create a Java process to run ejbc. The example supplies a system property to define weblogic.home and provide command line arguments using the arg tag. The classpath for the called Java process is specified using the classpath tag.

Packaging J2EE Deployment Units

As previously discussed, J2EE applications are packaged as JAR files containing a specific file extension depending on the component type:

- EJBs are packaged as JAR files.

- Web Applications are packaged as WAR files.

- Resource Adapters are packaged as RAR files.

- Enterprise Applications are packaged as EAR files.

These components are structured according to the J2EE specifications. In addition to the standard XML deployment descriptors, components may also be packaged with WebLogic Server-specific XML deployment descriptors.

Ant provides tasks that make the construction of these JAR files easier. In addition to the features of the JAR command, Ant provides specific tasks for building EAR and WAR files. Using Ant, you can specify the pathname as it appears in the JAR archive, which may differ from the original path in the file system. This ability is useful for packaging deployment descriptors (in which J2EE specifies an exact location in the archive), which may not correspond to the location in your source tree. See the Apache Ant online documentation pertaining to the ZipFileSet command for related information.

The following listing shows:

Listing 3-2 WAR Task Example

>     <war warfile="cookie.war" webxml="web.xml"
>     manifest="manifest.txt">

>        <zipfileset dir="." prefix="WEB-INF" includes="weblogic.xml"/>

>        <zipfileset dir="." prefix="images" includes="*.gif,*.jpg"/>

>        <classes dir="classes" includes="**/CookieCounter.class"/>

>        <fileset dir="." includes="*.jsp,*.html">

>        </fileset>

>     </war>

Packaging J2EE deployment units requires the following steps:

1. Specify the standard XML deployment descriptor using the webxml parameter.

2. The war task automatically maps XML deployment descriptor to the standard name in the WAR archive WEB-INF/web.xml.

3. Apache Ant stores the manifest file, specified using the manifest parameter, under the standard name META-INF/MANIFEST.MF.

4. Use the Apache Ant ZipFileSet command to define a set of files (in this case, just the WebLogic Server-specific deployment descriptor weblogic.xml) that should be stored in the WEB-INF directory.

5. Use a second ZipFileSet command to package all the images in an images directory.

6. The classes tag packages servlet classes in the WEB-INF/classes directory.

7. Finally, add all the .jsp and .html files from the current directory to the archive.

You can achieve the same result by staging the files in a directory that directly corresponds to the structure of the WAR file and creating a JAR file from that directory. Using special features of the Ant JAR tasks eliminates the need to copy files into a specific directory hierarchy.

The following example builds a Web application and an EJB, and then packages them together in an EAR file:

Listing 3-3 Packaging Example

>     <project name="app" default="app.ear">

>     	   <property name="wlhome" value="/bea/wlserver6.1"/>

>        <property name="srcdir" value="/bea/myproject/src"/>

>        <property name="appdir" value="/bea/myproject/config/mydomain/applications"/>

>        <target name="timer.war">

>            <mkdir dir="classes"/>

>            <javac srcdir="${srcdir}" destdir="classes" includes="myapp/j2ee/timer/*.java"/>

>             <war warfile="timer.war" webxml="timer/web.xml" manifest="timer/manifest.txt">

>               <classes dir="classes" includes="**/TimerServlet.class"/>

>            </war>

>        </target>

>        <target name="trader.jar">

>        <mkdir dir="classes"/>

>        <javac srcdir="${srcdir}" destdir="classes" includes="myapp/j2ee/trader/*.java"/>

>        <jar jarfile="trader0.jar" manifest="trader/manifest.txt">

>           <zipfileset dir="trader" prefix="META-INF" includes="*ejb-jar.xml"/>

>           <fileset dir="classes" includes="**/Trade*.class"/>

>           </jar>

>           <ejbc source="trader0.jar" target="trader.jar"/>

>        </target>

>        <target name="app.ear" depends="trader.jar, timer.war">

>           <jar jarfile="app.ear">

>              <zipfileset dir="." prefix="META-INF" includes="application.xml"/>

>              <fileset dir="." includes="trader.jar, timer.war"/>

>           </jar>

>        </target>

>        <target name="deploy" depends="app.ear">

>           <copy file="app.ear" todir="${appdir}/>

>        </target>

>     </project>

Running Ant

BEA provides a simple script to run Ant in the server/bin directory. By default, Ant loads the build.xml build file, but you can override this using the -f flag. Use the following command to build and deploy an application using the build script shown above:

ant -f yourbuildscript.xml

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:

- Package the servlets and JSPs in a .war file

- Package the enterprise beans in an EJB .jar file

- Package the .war and .jar files in an .ear file

- Deploy the .ear file

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. This means that 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.

About Resource Adapter Classes

Make sure that no resource-adapter specific classes exist in your WebLogic Server system classpath. If you need to use resource adapter-specific classes with Web components (for example, an EJB or Web application), you must bundle these classes in their corresponding archive file (for example, in the .war's /classes directory for servlets or in the .jar's /classes directory for EJBs).

Using PreferWebInfClasses in J2EE Applications

By default, the classloader for a web application follows the standard delegation model described in the Javasoft documentation. The servlet specification requires that a Web application obtain its class definition from the WAR file.

To support this requirement, BEA has included a switch that modifies the delegation model for a Web application so that the Web application's classloader looks for a class in the WAR file before asking its parent classloader for the class. This switch is called PreferWebInfClasses and is located on the WebAppComponentMBean. You can set this switch in the WebLogic Server console.

When you set PreferWebInfClasses to false (the default), the classloader for a Web application follows the standard delegation model. When set to true, it looks for class definitions in the WAR file before asking its parent for a class definition.

This switch satisfies the specification requirement. However, it leads to the possibility of having different versions of the same classes loaded in the Web application classloader than those versions existing in parent classloaders. This can lead to ClassCastExceptions if the developer is not careful to keep these two instances separate. For this reason, we have set the default for this setting to false, which means you use the standard delegation model.

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 after you modify the utility classes.

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 after you modify the classes or the classpath.

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

Startup classes that use application objects must wait for WebLogic Server to finish deploying the applications before the classes 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());
>             socket.close();

>             //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);
>               p.getInputStream().close();
>               p.getOutputStream().close();
>               p.getErrorStream().close();
>             }
>             catch (IOException ioe) {
>             }
>             loop = false;
>           } catch (Exception e) {
>             try {
>               Thread.sleep(SLEEPTIME); // try every 500 ms
>             } catch (InterruptedException ie) {}
>             finally {
>               try {
>                 socket.close();
>               } catch (Exception se) {}
>             }
>           }
>         }

If the system fails to create a socket, 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.

Copyright © 2001 BEA Systems, Inc. All rights reserved. Required browser: Netscape 4.0 or higher, or Microsoft Internet Explorer 4.0 or higher.