Packaging

The J2EE specification defines how a J2EE application and its components ought to be packaged. It also describes the structure and format of the different component types: web applications, EJB modules, enterprise applications, client applications, and resource adapters. For each component type, the specification describes the files needed and their locations within the directory structure. WebLogic requires that you adhere to the J2EE standard when packaging J2EE applications and modules.

A typical J2EE application includes the Java classes for the servlets and EJBs, their XML deployment descriptors, static web content (HTML files, images, etc.), and third-party utility libraries. Components that need to be deployed to WebLogic also may require WebLogic-specific XML descriptor files, and even container classes for any JSP pages, EJBs, and RMI objects. Except for connector modules, all J2EE modules also can be deployed in an exploded format. This means that although the deployment descriptors are still necessary, the module need not be bundled into a JAR. This is handy particularly during development, when you want to be able to easily change the contents of a module and its descriptor files.

The rest of this section outlines the traditional way of packaging and deploying J2EE applications. See the Section 12.6 later in this chapter to learn about WebLogic's innovative directory structure, which eases the task of building and deploying J2EE applications during development.

12.1.1 Deployment Descriptors

As we've seen already, J2EE modules and applications use XML-formatted deployment descriptors to specify additional semantics on the contents of the JAR and deploy-time configuration settings. WebLogic defines its own set of deployment descriptors that supplement the default XML descriptors required by the J2EE standard. For example, you can use the weblogic.xml descriptor file in a web application to configure session handling (timeouts, persistence, and cookie names), JSP pages (the Java compiler, precompilation, JSP base class), references to other J2EE resources, and more.

Table 12-1 lists the standard deployment descriptors that are essential to the different J2EE component types, and their WebLogic-specific counterparts.

Table 12-1. Deployment descriptors for J2EE components

Component	J2EE	WebLogic
Web Application	WEB-INF/web.xml	WEB-INF/weblogic.xml
Enterprise JavaBean	META-INF/ejb-jar.xml	META-INF/weblogic-ejb-jar.xml META-INF/weblogic-cmp-rdbms-jar.xml
Resource Adapter	META-INF/ra.xml	META-INF/weblogic-ra.xml
Web Service	None	WEB-INF/web-services.xml
Enterprise Application	META-INF/application.xml	META-INF/weblogic-application.xml
Client Application	application-client.xml	client-application.runtime.xml

If you have purchased third-party J2EE components that do not include any WebLogic-specific deployment descriptors, you may have to modify the JARs to include the WebLogic-specific XML descriptor file(s) needed by that component.

12.1.1.1 Editing deployment descriptors

WebLogic provides several ways in which you can edit the XML deployment descriptors for an application/module:

WebLogic Builder

This is the preferred way to edit the deployment descriptors. It provides a convenient GUI for creating the XML descriptors for a J2EE component, while hiding all of the underlying XML and ensuring that only valid XML descriptor files are generated.

XML Editor

You can use a plain text editor or any XML editor that supports DTDs. For instance, you could use BEA's Java-based, standalone XML editor. It allows you to view the XML document either as a hierarchical XML tree or in raw XML form, and supports validation checks against the DTD.

DDInit

You can use the DDInit tool to generate skeleton deployment descriptors. For instance, you can run the following command to generate the web.xml and weblogic.xml deployment descriptors for an exploded WAR:

java weblogic.marathon.ddinit.WebInit exploded-war-staging-dir

Similarly, you can run the following command to generate the XML descriptors for an exploded EJB JAR:

java weblogic.marathon.ddinit.EJBInit exploded-ejb-staging-dir

In this case, DDInit will manufacture a valid ejb-jar.xml descriptor file for your EJBs that complies with the EJB 2.0 standard. If the ejb-jar.xml file already exists, this command will use it to generate the weblogic-ejb-jar.xml descriptor file.

These tools generate skeleton XML descriptors for the component by making a best guess for a number of configuration settings. Typically, you will need to modify the generated deployment descriptor files and supply the appropriate values for those settings.

 

DDInit also is available as the ddcreate Ant task.

Administration Console

You can use the Administration Console to edit deployment descriptors for a deployed J2EE application or module. If an application is deployed in an exploded format, the Configuration/Descriptor tab of most components provides you with a way to edit the most important descriptors.[1] Because the Administration Console can be used to modify only those deployment descriptors for J2EE components that already were deployed to WebLogic, you must ensure that the component is packaged properly and equipped with essential information in its deployment descriptors.

[1] WebLogic 7.0 provides an Edit Descriptor option for most components instead. Choosing this option opens a new browser window with a GUI-based editor. This provides much of the same functionality as the WebLogic Builder tool.

Besides this, you can use the EJBGen tool to generate the deployment descriptors and the home and interface files for an EJB module automatically. This utility generates the XML descriptors by inspecting your source code for predefined JavaDoc tags that provide additional semantic information. This approach is described in Chapter 10.

12.1.2 Web Applications

In order to package a web application for WebLogic, you need to execute the following sequence of steps:

1. Create a temporary staging folder on disk (say, c:/war-staging), and then copy all of your HTML files, JSP pages, images, and any other resources referenced by your web application into this folder. The staging folder serves as the document root for your web application. Therefore, the directory structure for the resources must be preserved under this folder.
2. Copy all compiled servlet classes and helper classes into the WEB-INF/classes folder under the staging directory. This includes the home and remote interfaces for EJBs referenced by your servlets and EJBs.
3. If you've packaged helper classes in a JAR, place these JARs into the WEB-INF/lib folder under the staging directory.
4. Place JSP tag libraries under the WEB-INF folder. The path to the TLD, or the tag library JAR, is then referenced either directly from within a JSP, or indirectly through the tag-lib-uri subelement in the web.xml descriptor.
5. Create the web.xml and weblogic.xml descriptor files for the web application, and place these in the WEB-INF folder under the staging directory.
6. Once you've organized the contents of the staging folder, package them into a JAR file:

    jar cvf mywebapp.war -C c:/war-staging

A web archive always must have a .war file extension. It can be either packaged as a J2EE module within an enterprise application (EAR), or deployed independently using either the Administration Console or the deployer tool.

12.1.3 EJB Components

In order to package an EJB JAR for WebLogic, you need to execute the following tasks:

1. Create a temporary staging folder on disk (say, c:/ejb-staging), and then copy all of the EJB's compiled Java classes into this folder.
2. Create a META-INF folder under the staging directory, and generate the ejb-jar.xml and weblogic-ejb-jar.xml descriptor files for the EJB module. If the EJB module includes CMP entity beans, you also need to supply the weblogic-cmp-rdbms-jar.xml descriptor file, which captures the configuration settings for WebLogic's RDBMS-based persistence framework.
3. Once you've set up the contents of the staging folder, package them into a JAR file:

    jar cvf myjar.jar -C c:/ejb-staging

4. After this, pass the JAR file through the appc compiler, which generates the required container classes for the EJBs.

    java weblogic.appc -output myejbs.jar myjar.jar

An EJB JAR always must have a .jar file extension. The resulting EJB JAR then can be packaged as a J2EE module within an enterprise application (EAR), or deployed independently using either the Administration Console or the deployer tool.

12.1.4 Resource Adapters

In order to package J2EE connectors, you need to perform the following tasks:

1. Create a temporary staging folder on disk (say, c:/rar-staging), and then copy all of the compiled Java classes for the resource adapter into this folder.
2. Package the contents of this staging directory into a JAR:

   jar cvf myrar.jar -C c:/rar-staging

   Place the resulting JAR back in the staging folder, and remove the exploded contents of the JAR from the staging directory.

3. Create a META-INF folder under the staging directory, and place the XML descriptor files ra.xml and weblogic-ra.xml into this folder. You may have to generate only the weblogic-ra.xml descriptor if you've purchased a third-party resource adapter.
4. Once you've set up the structure of the staging folder, package them into a JAR:

    jar cvf myconnector.rar -C c:/rar-staging

The resulting RAR file can then either be packaged as a J2EE module within an enterprise application (EAR), or deployed independently using the Administration Console or the deployer tool. Resource adapter archive files always must end with a .rar file extension.

12.1.5 Enterprise Applications

Example 12-1 depicts the structure of a typical enterprise application (EAR).

Example 12-1. Internal structure of an enterprise application (EAR)

META-INFapplication.xml
META-INFweblogic-application.xml
ejb_jar1.jar 
ejb_jar2.jar
...
my_webapp1.war
my_webapp2.war
...
shared-lib.jar

In order to bundle the J2EE modules within an EAR file, you need to perform the following tasks:

1. Create a temporary staging directory say, c:/staging.
2. Copy the necessary web applications (WAR files), EJB components (EJB JARs), J2EE connectors (RAR files), and any shared libraries into the staging folder.
3. Create a META-INF directory under the staging folder c:/staging. Place the standard application.xml descriptor and the optional weblogic-application.xml descriptor into the META-INF folder.
4. Package the contents of this staging folder into an EAR file (myapp.ear):

   jar cvf myear.ear -C c:/staging

An enterprise application archive always must end with a .ear file extension. The application.xml descriptor file must adhere to the J2EE standard. Example 12-2 reveals the contents of the standard application.xml descriptor for the sample EAR, as depicted earlier in Example 12-1.

Example 12-2. Sample application.xml descriptor for an EAR

 My Application
 
 
 my_webapp1.war
 /
 
 
 
 
 my_webapp2.war
 /admin
 
 
 
 ejb_jar1.jar
 
 
 ejb_jar2.jar
 
 

Here, the enterprise application includes the web application my_webapp1.war, which is made available under the default context root /, and another, my_webapp2.war, which is available under the /admin context. In other words, if a WebLogic instance hosts both the web applications in the EAR, the HTTP request http://server:7001/foo.jsp fetches foo.jsp from the my_webapp1.war module, while the HTTP request http://server:7001/admin/login.jsp fetches login.jsp from the my_webapp2.war module.

You also can deploy enterprise applications in the exploded directory format. In this case, if the exploded EAR contains a web application that also exists in exploded format, then the web-uri element in the application.xml descriptor file must refer to the folder that holds the resources of the web application. Thus, if the mywebapp folder is the document root for a web application in the EAR, the web-uri element should be specified as follows:

 
 
 mywebapp
 /mywebapp
 
 
 ...

Later, we discuss how to include shared libraries and utility classes and make them visible to other J2EE modules within an enterprise application.

The weblogic-application.xml descriptor lets you configure application-wide resources and WebLogic-specific tuning information. These resources include application-scoped JDBC pools, XML parsers, and entity-EJB caches resources that are available only to the enterprise application, and not to the entire WebLogic configuration. Example 12-3 shows the sample structure of the weblogic-application.xml descriptor file for an enterprise application.

Example 12-3. Sample weblogic-application.xml descriptor for an EAR

 
 
 GlobalEntityCache
 
 10
 
 Exclusive
 
 
 
 
 
 weblogic.xml.babel.jaxp.SAXParserFactoryImpl
 
 
 weblogic.apache.xerces.jaxp.DocumentBuilderFactoryImpl
 
 
 weblogic.apache.xalan.processor.TransformerFactoryImpl
 
 
 
 My Mapping
 -//OReilly and Associates//DTD WL//EN
 http://www.oreilly.com/dtds/wl.dtd
 dtds/wl.dtd
 cache-at-initialization
 300
 
 

Application-scoped pools are covered in Chapter 5, whereas application-scoped entity caches are discussed in Chapter 10. Chapter 18 explains how to configure application-scoped parser factories and entity resolution mappings.

12.1.6 Client Applications

The J2EE specification also defines a standard way to package client J2EE applications. A client application module is packaged as a JAR, which includes the compiled Java classes that run in the client's VM. It also encapsulates deployment descriptors that specify the EJBs and other WebLogic resources needed by the client application. For each client application module, you need to supply the standard application-client.xml descriptor and an optional WebLogic-specific deployment descriptor. In fact, you can package the client application modules within an EAR, along with other server-side J2EE modules that comprise the enterprise application. By doing this, both client-side and server-side modules can be distributed as a single unit.

In order to package a client application module, you need to execute the following sequence of steps:

1. Create a temporary staging folder say, c:/client-staging and then copy all of the required files of the client into this folder. You also may place a batch file or script under the staging folder to start the client application.
2. Create a classes subfolder that holds the Java classes and JAR files, and modify the startup script so that the client's classpath includes the locations of these classes.
3. Modify the client JAR's manifest file /META-INF/MANIFEST.MF to include an entry for the Main-Class attribute.
4. Now that you've packaged the client-application JAR into an EAR, you can use the ClientDeployer tool to extract the client module from the EAR:

    java weblogic.ClientDeployer myapp.ear myclient

   Here myclient.jar is a J2EE client module packaged within the EAR myapp.ear. The ClientDeployer tool generates a client.properties file and then adds it to the client-application JAR.

5. Once the client-application JAR has been extracted from the EAR, you must use the weblogic.j2eeclient.Main utility to bootstrap the J2EE client and point it to a running WebLogic instance:

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

The j2eeclient.Main utility establishes the client's local JNDI context using the T3 URL of a running WebLogic instance, before invoking the client from the entry-point specified by the client JAR's manifest file. The client's deployment descriptor may reference any resource that is bound to the global JNDI tree: EJB home objects, JMS connection factories and destinations, JDBC data sources, and Mail Sessions. All of these references are resolved and bound to the client's local ENC, available under the java:comp/env/ context. In addition, the j2eeclient.Main utility makes a UserTransaction object available to the client's local JNDI tree under java:comp/UserTransaction.