Section 2.2. Component Modules

2.2. Component Modules

A component module is the smallest unit of deployment in the J2EE deployment model. A module is simply a jar file containing all of the bits and pieces that define a set of components. Each module contains components of the same type so that they can be easily delegated to the containers that handle them.

2.2.1. Module Jar Files

Each component module is packaged as a jar file with a specific layout for the elements that make up the components. Table 2-2 summarizes the different module jar files and deployment descriptors used for the different J2EE component types:

Table 2-2. Component module format summary

Component type	Module jar file suffix	Deployment descriptor filename and location
Web	.war("web archive")	WEB-INF/web.xml
Enterprise JavaBeans	.jar	META-INF/ejb-jar.xml
Applet	.jar	Not applicable
Application client	.jar	META-INF/application-client.xml
Resource adapter	.rar ("resource archive")	META-INF/rar.xml

In addition to the deployment descriptor locations specified Table 2-2, each component module jar file also has a specific file layout that's required for the elements that make up the components. In a war file, for example, all individual class files included in the module must be placed in the WEB-INF/classes directory, all class libraries are placed in the WEB-INF/lib directory, and so on.

2.2.2. Deployment Descriptors

Each component module (except for applet jar files) includes a standard J2EE deployment descriptor. These descriptors are key to the assembly and deployment process in J2EE. The deployment descriptor knits together all the bits and pieces in the module jar file into actual components and describes to the container how each component should be managed. Without the deployment descriptor, the module jar just looks like a bag of Java classes and other files to the container.

Component deployment descriptors specify these major sets of information for the container:

Module descriptive information

In most cases, a component module as a whole can be given some descriptive information, such as a name, a description, and so on. This information can be used by application server management tools and server logs to provide human-readable information about the components deployed in the server.

Component elements

Each component (EJB, web, or resource connector) is made up of one or more parts. A web component is implemented as either a servlet class or a JSP file. An entity EJB is implemented as a bean implementation class, one or more client interfaces, one or more home interfaces, and a primary key class. For each component in the module jar file, the container needs to be told the parts that make up the component.

Configuration data for component services

Each type of component makes use of specific services provided by the container. Some of these services are optional; some are part of the standard runtime management provided by the container. Web components use basic instantiation and lifecycle services, optional security services, and so on. EJBs use more elaborate lifecycle services, security services, persistence services, transaction management services, and so on. Where there are options in terms of how these services are managed at runtime, the deployment descriptor allows you to specify these options.

Resource and component dependencies

A component may make use of various resources that are expected to be deployed in its runtime environment in the application server. These may include JDBC DataSources used to make database connections, JavaMail Sessions used to create and send/receive email messages, and so on. Also, components can make use of other components. A web component might make use of a session EJB to perform some key tasks on behalf of users of its interface, and the session EJB may in turn make use of an entity EJB to access persistent data. These dependencies on external resources and components need to be declared in the deployment descriptor as well.

The full format of each of the various component deployment descriptors is described in Appendix A and the details of their use are demonstrated in the examples in Chapters 3, 4, 6, and 12. The following example demonstrates the general assembly process for component modules , including the use of deployment descriptors.^[*]

^[*] You may also want to take a look at Chapter 21, which describes XDoclet and annotations. One important use of these tools is to automate the process of generating deployment descriptors.

2.2.3. Component Module Assembly Example

Suppose we have a web application that maintains profiles for each user, and a profile contains various preferences for the behavior of the application. The profile data is stored in a database, and an EJB component is used to represent each profile within the application. The application also includes a JSP web component that provides an editor for profiles, where each user can specify his preferences. The JSP makes use of the profile EJB to access the profile data stored in the database.

Given this architecture, our application needs a web component module to deploy the JSP and an EJB module to deploy the profile EJB. Each of these modules will need its own deployment descriptor and will be packaged into a jar file to be assembled into the final application.

2.2.3.1. EJB module descriptor

Moving from the bottom up (from the database to the EJB component to the web UI), we can look at the deployment descriptor for our profile EJB component. The deployment descriptor is listed in Figure 2-4. If you look through the XML descriptor, you'll notice that it includes all of the categories of information we mentioned in the previous section: module descriptive information, component element declarations, component service configuration, and resource/component references.

This module has only one EJB component, and we declare its name and the classes that make up its implementation within the <enterprise-beans> section of the descriptor. We also configure the container services for this component. In this case, we specify that the EJB will be using bean-managed persistence, that it will not be reentrant, and that the security management should adopt the identity of the caller when determining access rights to the component. The meaning of these service configurations is explained in Chapter 6. Finally, we declare the external resources and components that the EJB component requires in order to operate. In this case, our EJB will need a JDBC DataSource to access the persistent profile data stored in the database. Here, we declare that our EJB code looks for the DataSource under the JNDI name jdbc/ProfileDB. This implies that, somewhere in the Java code that implements the EJB, we perform a JNDI lookup similar to the following:

 Context ctx = new InitialContext(  ); DataSource profileDB =   (DataSource)ctx.lookup("java:comp/env/jdbc/ProfileDB");

Figure 2-4. Profile EJB deployment descriptor

Our resource declaration in the EJB deployment descriptor instructs the container about this dependence so that the container can ensure that there is indeed a DataSource configured at that name in its JNDI service when we deploy the module. If there isn't, the container can stop the deployment with an error, allowing you to adjust the server configuration and redeploy the module. This is preferable to deploying an application and finding out at runtime that something is broken.

2.2.3.2. Web module descriptor

The deployment descriptor for the web component is listed in Figure 2-5. This descriptor would be included in the web module jar in the WEB-INF/web.xml file. This sample deployment descriptor also demonstrates the four categories of information found in component descriptors. After the module description, we declare web components and the code that defines them using <servlet> elements. In this case, we have a single web component, our profile viewing JSP, and we declare it by giving it a name and specifying the JSP file in the module jar file that serves as the component. Following that, we specify some configuration parameters to the web container, telling it how to manage our component. In this case, we simply tell the container what URLs should be mapped to our web component and how long user sessions should last. Finally, we declare any resources that our components require to operate at runtime. As we mentioned earlier, these references are specified using the JNDI name that the component code uses to locate them at runtime, and they will be resolved to actual resources and components in the application server's JNDI service. In this case, we declare the EJB component that the JSP uses to access the profile data. We've specified that the JSP will look for the EJB home interface using the JNDI name ejb/Profile, which implies that somewhere in the component code we perform a JNDI lookup like this:

 cntx = new InitialContext(  ); ProfileHome profileHome =   (ProfileHome)cntx.lookup("java:comp/env/ejb/Profile");