Introduction

A J2EE Module is the smallest independent unit of deployment in a J2EE application. There are different kinds of J2EE Modules, as described in Concept: Java 2 Platform Enterprise Edition (J2EE) Overview.

The number and size of J2EE Modules affects how easy it is to deploy and test a J2EE application. It also affects the ease in which components can be reused for other applications, and how easily the system can be adapted to other deployment configurations.

For information on assembling J2EE Modules, see Guideline: Assembling J2EE Modules.

For information on deploying J2EE Modules, see Guideline: Deploying J2EE Modules and Applications.

Identifying J2EE Modules

J2EE Modules are created during integration, but they reflect decisions made in implementation (and actually design). J2EE Modules are commonly used to package Artifact: Implementation Subsystem, which commonly map to Artifact: Design Subsystem.

J2EE Modules should contain closely related EJBs and helper classes that are only used by those EJBs. Generally such relationships are identified in design, and these classes would be grouped into a Design Subsystem. The identification of Design Subsystems should already have considered the issues of re-use, replacement, and support for multiple deployment configurations. However, when modules are allocated for deployment to specific nodes, then weaknesses in the design may become apparent, and changes to the Design Subsystems (and/or Implementation Subsystems) may be needed.

Identify J2EE Modules to contain components targeted to a single container. Web components are packaged in Web modules and EJB components are packaged in EJB modules, and Application Client components are packaged in Application Client modules.

Regular Java classes that are used by multiple modules should be packaged in separate J2EE Modules. The resulting JAR files appear in class-path references in the modules that require them (or in the transitive closure of such class-path references).

In summary, when identifying J2EE Modules, start by identifying one module for each Implementation Subsystem, unless the subsystem contains components to be deployed to different containers, and then define separate modules for each of the containers.

Modeling J2EE Modules

J2EE Modules are represented in the Implementation Model as UML artifacts with a stereotype that identifies its type: <<EJB-JAR>>, <<JAR>>, or <<WAR>>.

The composition of components (such as EJBs or servlets) into a J2EE module can be shown graphically by drawing an <<implements>> dependency from the contained component to the module it is packaged in, as shown in the following diagram. <<JARInclude>> dependencies can also be drawn to show the inclusion of an entire Java package in the archive.

Another option is to represent the archive as a package and show the contained components within the package as shown in the following diagram.

In addition to modeling what components are packaged in the archive, you can also model properties of the components, which are ultimately documented in the archive's deployment descriptor.

An example of how to model some EJB component properties is provided below.

The above diagram shows the assembly of three EJBs, BankEJB, LoanEJB, CustomerEJB, and LoanManagerEJB into the same module, EJBJARArchive1. Notice the modeling of the EJB method properties, the security roles, and the transactions. In this example, the CustomerEJB runs under the transaction type specified by CustomerTrans (e.g., "Required"). The source code uses the role name "user", which is mapped to the "Customer" user role in the deployment descriptor. Also, all methods in LoanEJB and CustomerEJB are executed with "Customer's" credentials, even if the invoking user belongs to a different role. Similarly, LoanManagerEJB methods are executed as "Admin". Finally, no methods can be accessed by users in BankEJB.

An example of how to model some Web component properties is provided below.

The above diagram shows the assembly of a servlet into a Web module. Notice the modeling of the the security roles and constraints, where users of type "Customer" run methods in the show results servlet as themselves, subject to security constraints defined by the properties of WebSecurityContraint1.

The deployment of a J2EE module to a node can be shown in the Deployment Model. See Guideline: Describing Distribution for J2EE Applications for further discussion on modeling the mapping from modules to deployment nodes.

Deployment Descriptors

Each J2EE Module contains a J2EE-standard deployment descriptor, plus zero or more vendor-specific descriptors. The different kinds of deployment descriptors are described in Concept: Java 2 Platform Enterprise Edition (J2EE) Overview. In general, the standard J2EE deployment descriptors capture primarily design and implementation decisions. Decisions that RUP would refer to as "deployment decisions", such as which nodes a component executes on, and how a component is configured for particular node, is captured in vendor-specific deployment descriptors.

Deployment descriptors serve two separate purposes:

• A means of communicating design decisions to the container. For example, the deployment descriptor for a session EJB has a "session-type" which states whether the session EJB is stateful or stateless. This must be consistent with the design and code - one cannot simply change this in the deployment descriptor.
• A means of tailoring behavior without recompiling code. For example, one can use the deployment descriptor to define which roles are authorized to call specific methods. This CAN be changed without changes in the EJB's code.

The contents of the deployment descriptor are set when the J2EE Module is created and when it is assembled into a J2EE Application. For more information on assembling J2EE Modules, see Guideline: Assembling J2EE Modules. For more information on assembling J2EE Applications, see Guideline: Assembling J2EE Applications.