Introduction

Assembling a J2EE Module results in the following Implementation Elements:

• J2EE archive (WAR, EJB-JAR, and JAR files), and its
• Deployment descriptors (XML files) that describe the contents of the archive and describe how the contained components are intended to function within the deployment container

For more information on J2EE Modules, see Guideline: J2EE Modules.

Defining the Archive

In this step, the application component provider identifies the components that are to be packaged in the module.

Multiple archives may be produced for different purposes. For example, separate archives for testing, debugging, or delivery to different "production" deployment configurations. The testing archives would contain testing classes and classes built with debug flags, while the production archives would not contain test classes and would not be built with debug flags. The intended context of the archive being assembled affects the assembly workspace that is set up.

Defining the Deployment Descriptors

The key step in assembling a J2EE Module is defining the deployment descriptor. Much of this information should have been captured in the design of each component, and so defining the deployment descriptor is largely about ensuring consistency with the design. If you are using round-trip engineering, then there may also be tool support for generating the deployment descriptor.

Each archive contains a J2EE-standard deployment descriptor, plus zero or more vendor-specific descriptors. The standard descriptors, ejb-jar.xml for EJB-JARs, and web.xml for WARs, contain sections that need to completed for testing and other "non-production" deployments, plus sections that will be prepared by the final application assembler for production deployment.

Each descriptor contains information of interest to application component providers, as well as application assemblers. For example, ejb-jar.xml contains three major sections (for the purposes of our discussion): <enterprise-beans>...</enterprise-beans>, <relationships>...</relationships>, and <assembly-descriptor>...</assembly-descriptor>.  The application component provider defines the properties of the EJBs, such as CMP fields, in the <enterprise-beans>...</enterprise-beans> section. The application component provider also defines the optional relationships between EJBs in the <relationships>...</relationships> section. The <assembly-descriptor>...</assembly-descriptor> section is where transactions, security roles, method permissions, etc. are defined. Normally, only the application assembler will worry about this section. The assembler may decide to modify the contents of the other two sections, but this is less common. The situation is similar for WAR archives. For more information on application assembly, see Guideline: Assembling J2EE Applications.

If, during design, you defined mappings between database tables in the Data Model and container-managed persistent (CMP) entity EJB's, those mappings should be reflected in the mapping directives in the vendor-specific descriptors (mapping directives are not part of the standard EJB descriptor). For more information on mapping CMP entity EJBs to database tables,, see Guideline: Designing Entity Beans.

If multiple components are to be packaged in the same archive (see step: Defining the Archive), the application component provider must integrate their deployment descriptor information. For example, when combining EJBs into one EJB-JAR, the application component provider must harmonize information in the deployment descriptors, such as security roles, and cross-references.

Validating the Archive

It is a good idea to valid the contents of the archive before attempting deployment, as obscure errors, especially on the application server side, may result in obscure or non-existent error messages. For example, duplicate JNDI names cannot be used by any of the components packaged in the archive.