e-docs > WebLogic Server > Developing WebLogic Server Applications > WebLogic Server Application Packaging

Developing WebLogic Server Applications

 Previous Next Contents Index View as PDF  

WebLogic Server Application Packaging

The following sections describe how to package WebLogic Server components. You must package components before you deploy them to WebLogic Server.

 

Packaging Overview

WebLogic Server J2EE applications are packaged according to 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 may require WebLogic-specific deployment descriptors and, possibly, container classes generated with the WebLogic EJB, RMI, or JSP compilers.

For more information, refer to the the J2EE 1.3 specification at: http://java.sun.com/j2ee/download.html#platformspec

 

JAR Files

A file created with the Java jar tool 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.

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 for deploying a component or application in the WebLogic Server environment.

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

Table 4-1 J2EE and WebLogic Deployment Descriptors

Component or
Application

Scope

Deployment Descriptors

Web Application

J2EE

web.xml

WebLogic

weblogic.xml

Enterprise Bean

J2EE

ejb-jar.xml

WebLogic

weblogic-ejb-jar.xml

weblogic-cmp-rdbms-jar.xml

Resource Adapter

J2EE

ra.xml

WebLogic

weblogic-ra.xml

Enterprise Application

J2EE

application.xml

WebLogic

weblogic-application.xml

Client Application

J2EE

application-client.xml

WebLogic

client-application.runtime.xml

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

You can create the deployment descriptors manually, 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 extract the contents of the JAR file into a directory, add the WebLogic-specific deployment descriptors and any generated container classes, and then create a new JAR file containing the old and new files. Note that the JAR utility contains a "u" option, which allows you to change or add files directly to an existing JAR.

Automatically Generating Deployment Descriptors

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

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 existing descriptors. The utilities generate both the standard J2EE and WebLogic-specific deployment descriptors for each component.

WebLogic Server includes the following utilities:

Limitations of DDInit

DDInit attempts to create deployment descriptor files that are complete and accurate for your component or application, but must guess at the value of many of the required elements. If such a guess is wrong, WebLogic Server will return an error when you deploy the component or application. If this happens, 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.

Relations among entity beans are a particular problem for DDInit, because it can only be sure of one-to-one bi-directional relations. If a relation has a "many" side to it, DDInit will guess at the nature of the relation.

Example

For an example of DDInit, assume that you have created a directory called c:\stage that contains the WEB-INF directory, the JSP files, and other objects that make up a Web application but you have not yet created the web.xml and weblogic.xml deployment descriptors. To automatically generate them, execute the following command:

java weblogic.marathon.ddinit.WebInit c:\stage

The utility generates the web.xml and weblogic.xml deployment descriptors and places them in the WEB-INF directory, which DDInit will create if it does not already exist.

Editing Deployment Descriptors

BEA offers two tools for editing the deployment descriptors of WebLogic Server applications and components:

Use either editor to update existing elements in, add new elements to, and delete existing elements from the following deployment descriptors:

Using the BEA XML Editor

To edit XML files, use the BEA XML Editor, an entirely Java-based XML stand-alone editor. It is a simple, user-friendly tool for creating and editing XML files. It displays XML file contents both as a hierarchical XML tree structure and as raw XML code. This dual presentation of the document gives you a choice of editing:

BEA XML Editor can validate XML code according to a specified DTD or XML schema.

For more documentation about using the BEA XML Editor and to download it, visit BEA dev2dev Online.

About EJBGen

EJBGen is an Enterprise JavaBeans 2.0 code generator or command-line tool that uses Javadoc markup to generate EJB deployment descriptor files. You annotate your Bean class file with javadoc tags and then use EJBGen to generate the Remote and Home classes and the deployment descriptor files for an EJB application, reducing to one the number of EJB files you need to edit and maintain.

For more information about EJBGen, see Programming WebLogic Enterprise JavaBeans.

Using the Administration Console Deployment Descriptor Editor

The Administration Console Deployment Descriptor Editor looks very much like the main Administration Console: the left pane lists the elements of the deployment descriptor files in tree form and the right pane contains the form for updating a particular element.

When you use the editor, you can either update the in-memory deployment descriptor only, or update both the in-memory and disk files. When you click the Apply button after updating a particular element, or the Create button to create a new element, only the deployment descriptor in WebLogic Server's memory is updated; the change has not yet been written to disk. To do this, click the Persist button. If you do not explicitly persist the changes to disk, the changes are lost when you stop and restart WebLogic Server.

Editing EJB Deployment Descriptors

This section describes the procedure for editing the following EJB deployment descriptors using the Administration Console Deployment Descriptor Editor:

For detailed information about the elements in the EJB-specific deployment descriptors, refer to Programming WebLogic Enterprise JavaBeans.

To edit the EJB deployment descriptors:

  1. Invoke the Administration Console in your browser using the following URL: 
    http://host:port/console

    where host refers to the name of the computer upon which WebLogic Server is running and port refers to the port number to which it is listening.

  2. Click to expand the Deployments node in the left pane.

  3. Click to expand the EJB node under the Deployments node.

  4. Right-click the name of the EJB whose deployment descriptors you want to edit and choose Edit EJB Descriptor from the drop-down menu. The Administration Console window appears in a new browser.

    The left pane contains a tree structure that lists all the elements in the three EJB deployment descriptors and the right pane contains a form for the descriptive elements of the ejb-jar.xml file.

  5. To edit, delete, or add elements in the EJB deployment descriptors, click to expand the node in the left pane that corresponds to the deployment descriptor file you want to edit, as described in the following list:

  6. To edit an existing element in one of the EJB deployment descriptors, follow these steps:

    1. Navigate the tree in the left pane, clicking on parent elements until you find the element you want to edit.

    2. Click the element. A form appears in the right pane that lists either its attributes or sub-elements.

    3. Edit the text in the form in the right pane.

    4. Click Apply.

  7. To add a new element to one of the EJB deployment descriptors, follow these steps:

    1. Navigate the tree in the left pane, clicking on parent elements until you find the name of the element you want to create.

    2. Right-click the element and chose Configure a New Element from the drop-down menu.

    3. Enter the element information in the form that appears in the right pane.

    4. Click Create.

  8. To delete an existing element from one of the EJB deployment descriptors, follow these steps:

    1. Navigate the tree in the left pane, clicking on parent elements until you find the name of the element you want to delete.

    2. Right-click the element and chose Delete Element from the drop-down menu.

    3. Click Yes to confirm that you want to delete the element.

  9. Once you make all your changes to the EJB deployment descriptors, click the root element of the tree in the left pane. The root element is the either the name of the EJB JAR archive file or the display name of the EJB.

  10. Click Validate if you want to ensure that the entries in the EJB deployment descriptors are valid.

  11. Click Persist to write your edits of the deployment descriptor files to disk in addition to WebLogic Server memory.

Editing Web Application Deployment Descriptors

This section describes the procedure for editing the web.xml and weblogic.xml Web application deployment descriptors using the Administration Console Deployment Descriptor Editor.

See Assembling and Configuring Web Applications for detailed information on the elements in the Web application deployment descriptors.

To edit the Web application deployment descriptors:

  1. Invoke the Administration Console in your browser: 
    http://host:port/console

    where host refers to the name of the computer upon which WebLogic Server is running and port refers to the port number to which it is listening.

  2. Click to expand the Deployments node in the left pane.

  3. Click to expand the Web Applications node under the Deployments node.

  4. Right-click the name of the Web application whose deployment descriptors you want to edit and choose Edit Web Application Descriptor from the drop-down menu. The Administration Console window appears in a new browser.

    The left pane contains a tree structure that lists all the elements in the two Web application deployment descriptors and the right pane contains a form for the descriptive elements of the web.xml file.

  5. To edit, delete, or add elements in the Web application deployment descriptors, click to expand the node in the left pane that corresponds to the deployment descriptor file you want to edit:

  6. To edit an existing element in one of the Web application deployment descriptors:

    1. Navigate the tree in the left pane, clicking on parent elements until you find the element you want to edit.

    2. Click the element. A form appears in the right pane that lists either its attributes or sub-elements.

    3. Edit the text in the form in the right pane.

    4. Click Apply.

  7. To add a new element to one of the Web application deployment descriptors:

    1. Navigate the tree in the left pane, clicking on parent elements until you find the name of the element you want to create.

    2. Right-click the element and chose Configure a New Element from the drop-down menu.

    3. Enter the element information in the form that appears in the right pane.

    4. Click Create.

  8. To delete an existing element from one of the Web application deployment descriptors:

    1. Navigate the tree in the left pane, clicking on parent elements until you find the name of the element you want to delete.

    2. Right-click the element and choose Delete Element from the drop-down menu.

    3. Click Yes to confirm that you want to delete the element.

  9. Once you make all your changes to the Web application deployment descriptors, click the root element of the tree in the left pane. The root element is the either the name of the Web application WAR archive file or the display name of the Web application.

  10. Click Validate to ensure that the entries in the Web application deployment descriptors are valid.

  11. Click Persist to write your edits of the deployment descriptor files to disk in addition to WebLogic Server memory.

Editing Resource Adapter Deployment Descriptors

This section describes the procedure for editing the ra.xml and weblogic-ra.xml resource adapter deployment descriptors using the Administration Console Deployment Descriptor Editor.

For detailed information about the elements in the resource adapter deployment descriptors, refer to Programming WebLogic J2EE Connectors.

To edit the resource adapter deployment descriptors:

  1. Invoke the Administration Console in your browser: 
    http://host:port/console

    where host refers to the name of the computer upon which WebLogic Server is running and port refers to the port number to which it is listening.

  2. Click to expand the Deployments node in the left pane.

  3. Click to expand the Connectors node under the Deployments node.

  4. Right-click the name of the resource adapter whose deployment descriptors you want to edit and choose Edit Connector Descriptor from the drop-down menu. The Administration Console window appears in a new browser.

    The left pane contains a tree structure that lists all the elements in the two resource adapter deployment descriptors and the right pane contains a form for the descriptive elements of the ra.xml file.

  5. To edit, delete, or add elements in the resource adapter deployment descriptors, click to expand the node in the left pane that corresponds to the deployment descriptor file you want to edit:

  6. To edit an existing element in one of the resource adapter deployment descriptors:

    1. Navigate the tree in the left pane, clicking on parent elements until you find the element you want to edit.

    2. Click the element. A form appears in the right pane that lists either its attributes or sub-elements.

    3. Edit the text in the form in the right pane.

    4. Click Apply.

  7. To add a new element to one of the resource adapter deployment descriptors:

    1. Navigate the tree in the left pane, clicking on parent elements until you find the name of the element you want to create.

    2. Right-click the element and chose Configure a New Element from the drop-down menu.

    3. Enter the element information in the form that appears in the right pane.

    4. Click Create.

  8. To delete an existing element from one of the resource adapter deployment descriptors:

    1. Navigate the tree in the left pane, clicking on parent elements until you find the name of the element you want to delete.

    2. Right-click the element and chose Delete Element from the drop-down menu.

    3. Click Yes to confirm that you want to delete the element.

  9. Once you make all your changes to the resource adapter deployment descriptors, click the root element of the tree in the left pane. The root element is the either the name of the resource adapter RAR archive file or the display name of the resource adapter.

  10. Click Validate to ensure that the entries in the resource adapter deployment descriptors are valid.

  11. Click Persist to write your edits of the deployment descriptor files to disk in addition to WebLogic Server memory.

Editing Enterprise Application Deployment Descriptors

This section describes the procedure for editing the Enterprise Application deployment descriptors (application.xml and weblogic-application.xml) using the Administration Console Deployment Descriptor Editor.

Refer to application.xml Deployment Descriptor Elements in Application Deployment Descriptor Elements, for detailed information about the application.xml and weblogic-application.xml files.

Note: The following procedure describes only how to edit the application.xml and weblogic-application.xml files; to edit the deployment descriptors in the components that make up the Enterprise application, see Editing EJB Deployment Descriptors, Editing Web Application Deployment Descriptors, or Editing Resource Adapter Deployment Descriptors.

To edit the Enterprise Application deployment descriptor:

  1. Invoke the Administration Console in your browser: 
    http://host:port/console

    where host refers to the name of the computer upon which WebLogic Server is running and port refers to the port number to which it is listening.

  2. Click to expand the Deployments node in the left pane.

  3. Click to expand the Applications node under the Deployments node.

  4. Right-click the name of the Enterprise Application whose deployment descriptor you want to edit and choose Edit Application Descriptor from the drop-down menu. The Administration Console window appears in a new browser.

    The left pane contains a tree structure that lists all the elements in the application.xml file and the right pane contains a form for its descriptive elements, such as the display name and icon file names.

  5. To edit an existing element in the application.xml deployment descriptor, follow these steps:

    1. Navigate the tree in the left pane, clicking on parent elements until you find the element you want to edit.

    2. Click the element. A form appears in the right pane that lists either its attributes or sub-elements.

    3. Edit the text in the form in the right pane.

    4. Click Apply.

  6. To add a new element to the application.xml deployment descriptors:

    1. Navigate the tree in the left pane, clicking on parent elements until you find the name of the element you want to create.

    2. Right-click the element and choose Configure a New Element from the drop-down menu.

    3. Enter the element information in the form that appears in the right pane.

    4. Click Create.

  7. To delete an existing element from the application.xml deployment descriptor:

    1. Navigate the tree in the left pane, clicking on parent elements until you find the name of the element you want to delete.

    2. Right-click the element and chose Delete Element from the drop-down menu.

    3. Click Yes to confirm that you want to delete the element.

  8. Once you make all your changes to the application.xml deployment descriptor, click the root element of the tree in the left pane. The root element is the either the name of the Enterprise application EAR archive file or the display name of the Enterprise application.

  9. Click Validate if you want to ensure that the entries in the application.xml deployment descriptor are valid.

  10. Click Persist to write your edits of the deployment descriptor files to disk in addition to WebLogic Server memory.

 

Packaging Web Applications

If your Web application is accessed by a programmatic Java client, see 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 anywhere on your hard drive. 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.

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

  8. Execute the following command to automatically generate the web.xml and weblogic.xml deployment descriptors in the WEB-INF subdirectory: 
    java weblogic.marathon.ddinit.WebInit 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 manually in the WEB-INF subdirectory manually.

    Note: See Assembling and Configuring Web Applicationsfor 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: 
    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.Deployer command-line utility.

    Note: Now that you have packaged your Web application, see Deploying Applications for instructions on deploying applications in WebLogic Server.

 

Packaging Enterprise JavaBeans

You can stage one or more Enterprise JavaBeans (EJBs) in a directory and package them in an EJB JAR file. If your EJB is accessed by a programmatic Java client, see Packaging Client Applications which describes how WebLogic Server loads your EJB classes.

Staging and Packaging EJBs

To stage and package an Enterprise JavaBean (EJB):

  1. Create a temporary staging directory anywhere on your hard drive (for example, c:\stagedir).

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

  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.marathon.ddinit.EJBInit staging-dir

    where staging-dir refers to the staging directory. This utility generates deployment descriptors for EJB 2.0.

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

    Note: See Programming WebLogic Enterprise JavaBeansfor 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, 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 WebLogic Server.

    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.

    Note: Now that you have packaged your EJB, see Deploying 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.ejbc. 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.

For more information, refer to "Packaging EJBs for the WebLogic Server Container" in Programming WebLogic Enterprise JavaBeans

 

Packaging Resource Adapters

After you stage one or more resource adapters in a directory, you package them in a Java Archive (JAR). Before you package your resource adapters, be sure you read and understand the chapter entitled "WebLogic Server Application Classloading" in this guide, which describes how WebLogic Server loads classes.

To stage and package a resource adapter:

  1. Create a temporary staging directory anywhere on your hard drive.

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

  3. Create a JAR to store the resource adapter Java classes. Add this JAR to the top level of the staging directory.

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

  5. 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 at: http://java.sun.com/dtd/connector_1_0.dtd

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

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

  7. When the resource adapter classes and deployment descriptors are set up in the staging directory, you can create the RAR with a JAR command such as: 
    jar cvf jar-file.rar -C staging-dir

    This command creates a RAR that you can deploy on a WebLogic Server or package in an enterprise application archive (EAR).

    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 are relative to the directory where you staged the resource adapters.

 

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, along with the Enterprise Application deployment descriptor files, in another JAR file with an EAR extension.

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

A supplemental deployment descriptor, weblogic-application.xml contains additional WebLogic-specific deployment information. This deployment descriptor is optional and is only needed if you want to configure application scoping.

Application scoping refers to configuring resources for a particular enterprise application rather than for an entire WebLogic Server configuration. Examples of resources include the XML parser used by an application, the EJB entity cache, the JDBC connection pool, and so on. The main advantage of application scoping is that it isolates the resources for a given application to the application itself.

Another advantage of using application scoping is that by associating the resources with the EAR file, you can run this EAR file on another instance of WebLogic Server without having to configure the resources for that server.

For information about application scoping, see Application Scoped JDBC Connection Pools and XML Application Scoping.

Refer to weblogic-application.xml Deployment Descriptor Elements in Application Deployment Descriptor Elements, for weblogic-application.xml deployment descriptor elements.

Packaging Enterprise Applications: Main Steps

If your enterprise application is accessed by a programmatic Java client, see 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 anywhere on your hard drive.

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

  5. Create the application.xml deployment descriptor file that describes the enterprise application in the META-INF directory. See Application Deployment Descriptor Elements, for detailed information about the elements in this file.

  6. Optionally create the weblogic-application.xml file manually in the META-INF directory, as described in Application Deployment Descriptor Elements.

  7. 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.Deployer command-line utility.

    Note: Now that you have packaged your enterprise application, see Deploying Applications for instructions on deploying applications in WebLogic Server.

 

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-client.xml Deployment Descriptor Elements in Client Application 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:

Note: For more information on deploying, refer to WebLogic Server Deployment.

 

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 4-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:

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 4-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 4-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

 

Back to Top Previous Next