Packaging Enterprise Applications

There are a number of ways to package and deploy EJB archives and Web application components for your application. As indicated in Figure 8.1 earlier in this chapter, the three primary options are these:

1. Deploying the EJB archives directly to the server as independent applications. Web application components are deployed alongside the EJB archive file as independent applications, and they access the EJB components using remote interfaces.

2. Deploying the EJB archives in an enterprise application archive ( .ear ) file containing all EJB archives, Web application archives, and enterprise application descriptor files.

3. Deploying the EJB archives in an exploded enterprise application directory structure containing all EJB archives, Web application archives, and enterprise-application descriptor files.

The first option, direct deployment of EJB archives and Web applications, is depicted in Figure 8.6. Each EJB archive and Web application is deployed as an independent J2EE application in WebLogic Server using one of the standard deployment techniques (discussed later in this chapter).

Figure 8.6:  EJBs and Web apps deployed as separate applications.

This technique is not recommended for the following reasons:

• The applications are loaded with separate, independent application classloaders (see Figure 8.7). Because each application classloader is independent, classes loaded by one application classloader are not visible to other application classloaders. This means that in order for your Web applications to invoke one of your EJBs, the Web applications must include client .jar files containing client- related EJB classes (typically remote interfaces, home interfaces, primary key classes, and any classes used as arguments or return types to any methods in the public interfaces) to communicate with the EJB components. As the number of Web applications and EJB archives increases , the management of these client .jar files becomes tedious and error prone.

  
  Figure 8.7:  Separate classloader used for each application.

• All communication between applications loaded by independent application classloaders must use remote interfaces and Serializable objects to prevent ClassCastException errors because each application has its own versions of the shared classes.

• Applications are difficult to manage as a single unit because they are not, in fact, a single application in the view of the server. For example, controlling the order of deployment during server startup is difficult in this technique, and many of the application staging and deployment features present in the latest version of WebLogic Server will be unable to process multiple applications as a single deployment unit.

• There is no way to combine entity-bean caches or configure application-wide resources in this technique because these features are available only when enterprise applications are employed for deployment.

Note that all classloaders used for the separate applications are children of the Java system classloader. The classes in the system classloader are defined by the CLASSPATH used for the server process itself during startup. Any components in a child classloader may reference classes present in parent classloaders, meaning that your EJB and Web applications can use classes loaded by the system classloader.

One alternative to placing client .jar files for each EJB archive in each Web application might appear to be the placement of such files in the system classpath, making the client classes available to all child classloaders and therefore to all of your application components. Don t fall into this trap! There are two very good reasons to avoid this system classloader shortcut:

• Placing application-related classes in the system classpath prevents a complete redeployment of your application because classes loaded by the system classloader cannot be removed and reloaded.

• Classes in the parent classloader cannot reference classes in children classloaders. If any class in the system classloader attempts to use a class found only in the EJB archive or Web application lib or classes directory, you will get a NoClassDefFoundError exception. If you solve this problem by moving more and more classes to the system classpath, pretty soon you ll find that every class in your application winds up in the system classloader and all hope for hot redeployment is gone.

We recommend that only classes required for system-wide components be present in the system classpath and therefore loaded by the Java system classloader. Examples include classes in JDBC driver .jar files, the weblogic.jar file, and the Java tools.jar file. Even classes such as logging utilities and frameworks used by your application do not belong in the system classpath. There is a better location for such libraries in an enterprise application. We ll cover this topic in detail later in this chapter.

Best Practice  

Place only system classes, such as JDBC drivers and WebLogic classes, in the system classpath. Don t place client .jar files or any other application-specific classes in the system classpath or you will likely encounter NoClassDefFoundError problems.

Although it might be tempting to deploy your application as separate independent archives for small applications or for larger applications in the early stages of development, we recommend that you avoid this technique for all applications containing EJB archive files. Once you get in the habit of using remote interfaces and copying client .jar files to Web applications, it may be difficult to migrate to the better techniques discussed later.

Best Practice  

Avoid deploying EJB archives and Web applications as separate, independent applications in WebLogic Server.

Enterprise Application Directory Structure

The other two options for EJB deployment involve creating an enterprise application containing all of the EJB archives and Web application components. The options differ only in the final packaging step: Should the enterprise application be deployed as an exploded directory or as a single enterprise archive ( .ear ) file? We ll address that question last and begin by reviewing the contents of an enterprise application and examining the enterprise-application descriptor files that allow us to configure the application components.

Figure 8.8 presents the standard directory structure and contents of an enterprise application. The key difference from the previous EJB deployment option is the bigapp enterprise application root directory. This directory contains all of the individual application components and represents a single directory in the applications directory for the server. The server treats everything in the bigapp directory as a single J2EE application, eliminating many of the problems associated with the previous deployment option.

Figure 8.8:  Standard enterprise application directory structure.

The EJB archives and Web application components are placed at the root level of the enterprise application directory structure along with a required META-INF directory and any other directories required by your application. We recommend creating a lib directory to contain utility archive files loaded using the manifest Class- Path technique discussed later in this chapter. Note that WebLogic Server 8.1 adds support for a special set of directories in the enterprise application, APP-INF/lib and APP-INF/classes , which WebLogic Server automatically examines and loads in the top-level application classloader without requiring manifest Class-Path entries.

A critical difference in this deployment option relates to the structure of the classloaders used to load an enterprise application containing both EJB archives and Web components. In the first option each archive and Web application was loaded as a separate application in a separate classloader descended directly from the Java system classloader (see Figure 8.7). When EJB archives and Web applications are placed in an enterprise application structure, however, WebLogic Server uses the classloader structure depicted in Figure 8.9.

Figure 8.9:  Classloader hierarchy in enterprise application.

All EJB archives, along with utility classes referenced in an EJB archive file s manifest Class-Path entry or located in the APP-INF directory structure, are loaded by a single top-level application classloader, thereby permitting local interfaces and pass-by-reference semantics between components in these EJB archives. More importantly, the Web application classloaders are children of the application classloader rather than siblings of it. Recall that a child classloader is able to reference all classes loaded by its parent classloader, so the Web application components also have full access to the classes in the EJB archives. This child-sees-parent visibility has two important ramifications :

• Web applications may use local EJB interfaces and pass-by-reference semantics with EJB components located in the same enterprise application. There is no need to use remote interfaces or Serializable parameters and return types, although their use is not precluded in this option.

• There is no need for the Web applications to include client .jar files because they have full visibility to these classes by virtue of the parent application classloader.

Figure 8.10 presents the enterprise application directory structure for the bigrez.com example application. Bigrez.com relies on parent-child classloader visibility and the ability of Web application components such as JSP pages and Action controller classes to communicate directly with EJB components using local interfaces and pass-by-reference semantics. It also relies on the accessibility of container-managed relationship fields in Web application components, a technique that works only with local interfaces. In other words, the direct interaction approach is not possible unless components are located in a single enterprise application. For more information about WebLogic Server classloaders, please see the WebLogic Server documentation at http://edocs.bea.com/wls/docs81/programming/ classloading .html .

Note that Figure 8.10 represents the structure of an enterprise application containing exploded Web applications. Just as the enterprise application itself can be archived or exploded, the Web applications in it can be archived or exploded. Generally, it makes sense to leave the Web applications exploded if the enterprise application itself is exploded and to use archived Web applications within archived enterprise applications. Leaving Web applications exploded in development also has advantages when making changes to JSP and HTML files in the Web application. As described in Chapter 5, changes to these display components can be deployed to the exploded application without requiring a complete redeployment of the Web application.

Assembling all of these components in their correct location in the enterprise application is covered later in the chapter, along with a walkthrough of the build scripts that perform this activity in the bigrez.com application. Before moving on to these packaging topics, however, we first need to complete our discussion of the enterprise-application structure itself by describing the contents of the META-INF and lib directories.

Figure 8.10:  BigRez.com enterprise application directory structure.

Enterprise Application Descriptor Files

The META-INF directory in the enterprise application directory structure contains two descriptor files used to control the deployment of the components and resources in the enterprise application. The first descriptor file is application.xml , a standard file required by the J2EE specification. The second file, weblogic-application.xml , is a WebLogic Server-specific descriptor file used to configure shared caches and resources common to all components in the enterprise application. We ll examine the contents of these descriptors and walk through the bigrez.com versions to understand their use and highlight best practices.

Standard application.xml Descriptor File

The application.xml descriptor file is defined by the J2EE specification and is used by WebLogic Server to control basic configuration and deployment of the application. Table 8.1 outlines the high-level sections of the application.xml file and lists the key elements used in each section.

Table 8.1:  Sections of the application.xml Descriptor File

APPLICATION.XML SECTION	PURPOSE AND KEY TOP-LEVEL XML ELEMENTS
Deployment attributes	Defines graphics and descriptions used by deployment and management tools. < icon > , < display- name > , < description >
Module definitions	Defines the location of each module (application) contained in the enterprise application. < module > , < connector > , < ejb > , < web >
Security information	Defines application-wide security roles available for all modules. < security-role >

The bigrez.com version of application.xml , presented in Listing 8.1, includes module definitions for the EJB archive file and the two Web applications.

Listing 8.1:  BigRez.com application.xml descriptor file.

 <!DOCTYPE application PUBLIC