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.
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.
188.8.131.52 Editing deployment descriptors
WebLogic provides several ways in which you can edit the XML deployment descriptors for an application/module:
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.
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.
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.
DDInit also is available as the ddcreate Ant task.
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. 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.
 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:
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:
jar cvf myjar.jar -C c:/ejb-staging
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:
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.
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:
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:
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.
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.
Managing the Web Server
Using JNDI and RMI
Using CMP and EJB QL
Packaging and Deployment
Performance, Monitoring, and Tuning
Logging and Internationalization