Purpose

This tool mentor relates to the following J2EE-specific information:

• Information on J2EE archives, see Concept: Java 2 Platform Enterprise Edition (J2EE) Overview.
• Information on J2EE Modules, see Concept: Java 2 Platform Enterprise Edition (J2EE) Overview.
• For more information on J2EE Applications, see Guideline: J2EE Application.
• Information on Assembling J2EE Modules, see Guideline: Assembling J2EE Modules.
• Information on Assembling J2EE Applications, see Guideline: Assembling J2EE Applications.

Overview

XDE provides automation for creating J2EE archives, for modeling what components are to be deployed in the archives, and for modeling what nodes (containers and servers) the J2EE archives are to be deployed to. These activities are performed in XDE deployment models.

The following steps are performed in this tool mentor:

• Setting up the Assembly Workspace
• Defining the Archives
• Defining the Deployment Descriptors
• Validating the Archives

For More Information

Links to topics in the Rational XDE™ online Help are marked with .

Setting Up the Assembly Workspace

In XDE, the assembly workspace is the XDE deployment models (EJB, Web, and EAR). Thus, in this step, the necessary XDE deployment models are created. For recommendations on what projects and deployment models should be defined, see the Model Structure Guidelines for Rational XDE Developer.

Some of the deployment models may already have been created when the XDE projects were created. However, the assembler may choose to create additional separate "assembly workspaces" to support deployment for testing and deployment for production.

In XDE separate assembly workspaces may be implemented using separate XDE deployment models, or by defining individual archives in the same deployment model (i.e., separate archives for testing, production, etc.).  The advantage of the latter approach is a reduction in the number of XDE models and it is a little easier to add, remove, and change J2EE components, archive files, etc. in the archives consistently when they are in the same model. However, managing current modifications to the same model is drawback of this approach. A separate model also makes it easier to limit access to the contents of production archives, when they need to be carefully controlled.

XDE deployment models can be created "by hand" (see Creating Java Deployment Models , or they can be created using XDE's J2EE deployment wizards at the same time the archive is created (see the next step: Defining the Archives). The XDE deployment wizards create or update the appropriate EJB or Web deployment model, as well as an EAR model that contains the "enclosing" EAR, which is required for deployment to most application servers.

See the remaining steps in this tool mentor for information on populating the XDE deployment models.

Defining the Archives

In this step, you create the archives, if they do not already exist, and decide what elements should be packaged in the archives.

J2EE Module archives, EJB-JARs and WARs, are modeled in the EJB and Web deployment models, respectively. In these deployment models, you model what elements are to be deployed in those archives.

J2EE Application archives, EARs, are modeled in the EAR deployment model. In the EAR deployment model, you model what J2EE Module archives are packaged in the EAR, as well as what application server node the EAR is to be deployed on. For more information on mapping archives to nodes, see Deploy Relationships . The nodes contain information about the type of server and information needed for deployment. If the application server is a type supported by XDE, then XDE allows you to specify some properties (such as application-level security roles) for the server to aid deployment. For more information, see Deployment Nodes (Java) . See also Application Servers (Java) .

In XDE, you can use the J2EE Application Deployment wizards to set up XDE deployment models, which includes creating the models, creating the archives, identifying the elements to be deployed in those archives, and specifying the node the archive should be deployed on. In the EJB and Web deployment models, you define the elements to be included in the J2EE Module archives, and the deployment wizard sets up the relationships between the archive files and the components. In the EAR deployment model, you define which archives go into the EAR (the deployment wizard sets up the default relationships with the archives in the EJB and Web deployment models) and you define the application server "nodes" to which the archive is deployed. For more information on the XDE deployment wizards, see J2EE Deployment Wizards .

Some notes on the use of the XDE deployment wizards:

• The XDE models containing the elements to be packaged in the archives need to be open prior to invoking the wizards so that the elements appear in the drop down boxes and can be selected for inclusion in the archive.
• The wizards only add elements to the archives. The wizards cannot remove previously specified items, even if they are unchecked in the wizards on subsequent invocations.
• If you have more than one archive in an XDE deployment model, XDE treats one of them as the "default" archive. This is the archive that you specify during the last step of the deployment wizard. If you are using XDE in WebSphere Studio Application Developer, this is the only archive that XDE will know about, because Application Developer requires a separate project for each archive. Hence you won't be able to use Application Developer tools to work on "non-default" archives.
• You can run the wizards repeatedly as the application evolves and new elements need to be added to existing archives, new archives need to be created, or changes are needed to the deployment information (for more information on deploying J2EE archives, see Tool Mentor: Deploying J2EE Modules and Applications Using Rational XDE Developer - Java Platform Edition).
• After running the wizards, it is a good idea to open the default diagram in each deployment model, then drag the elements that were created in the deployment models such as components and archives to the diagram and arrange them as desired.

The results of this step should be captured in deployment diagrams. For more information, see Working with Deployment Diagrams . See also Laying Out and Grouping Shapes in Diagrams .

Defining the Deployment Descriptors

In XDE, you don't really edit deployment descriptors directly. Rather, you model the deployment descriptors in the XDE deployment models and then the deployment descriptor file is constructed automatically during deployment. The XDE deployment model is essentially a model of the corresponding deployment descriptor. For more information on deployment descriptors in XDE, see Deployment Descriptor Files .

The XDE deployment wizards (discussed in the previous step: Defining the Archives) automatically populate many of the deployment descriptor properties when the archive is created and each time the deployment wizards are run. That way the deployment descriptors evolve along with the components they contain.

Some application servers require an EAR "wrapper" around the EJB-JAR, WAR, and other JAR archives for deployment, which means that the application component provider may need to assemble an EAR for testing. In such cases, the EAR that the XDE deployment wizards generate automatically is usually sufficient.

However, application assemblers are usually concerned about the details of EAR contents, especially application-wide security roles, etc., which can also be modeled in XDE. In the XDE deployment model, you can model security roles, permissions, transactions, etc. using the pop-up menus or the corresponding toolboxes. The "Connector Assistant" in each Toolbox knows what kinds of relationships to create between elements. In situations where several options are possible, a prompt is presented for user selection. For more information on the "connector assistant", see Defining Relationships for EJBs . For details on modeling WAR files, see Modeling WAR Files . For details on modeling EJB-JAR files, see Modeling Deployment .

The XDE deployment models (EJB, Web, and EAR) contain all the information required to generate the EJB, Web, and Enterprise Application ejb-jar.xml, web.xml, and application.xml deployment descriptors, respectively (some of the information is derived from the code models associated with the deployment models). These are the descriptors defined by the J2EE standard. Additional descriptors are usually required to complete deployment to most application servers. XDE generates these additional deployment descriptors for the supported application servers. For more information, see Java Application Deployment .

If you defined mappings between database tables in the Data Model and container-managed persistent (CMP) entity EJB's, those mappings will be used to generate the mapping directives in the vendor-specific descriptors (mapping directives are not part of the standard EJB descriptor). If no Data Model mappings have been defined, then default mappings will be generated for CMP entity EJB's. For more information, see Using EJBs with Databases .

XDE does not model and generate the complete contents of all vendor-specific descriptors. Instead, you can override the automatic creation of one or more of these descriptors and maintain them yourself. Each archive has a property that holds a list of files or directories that will be included in the archive, but are not modeled. The property is calledJARNonModelElements for JAR's, EJBNonModelElements for EJB-JAR's, WebNonModelElementsfor WAR's, and EARNonModelElements for EAR's. Add the deployment descriptors and other files that you want to maintain yourself to the appropriate property for the corresponding archive. For more information, see Java Application Deployment .

Validating the Archives

It is a good idea to valid your XDE deployment models before attempting deployment, as obscure errors, especially on the application server side, may result in obscure or non-existent error messages. Actually, it is not a bad idea to validate the models "as you go" (i.e., occasionally during assembly and then once before deployment, as a sanity check).

XDE provides support for checking the integrity of your models. Select the model in the Model Explorer, then invoke the context command "Validate". If problems are found task items are written to the task list. For more information, see Validating Java Models . For more information on what XDE validates for deployment models, see Deployment Validation Rules .

For More Information

In addition to modeling the J2EE archives and deployment descriptors in XDE, you can also import deployment descriptors or whole archives into XDE. For more information see Importing and Exporting in Deployment .

For more information on XDE deployment modeling, see Modeling Deployment . For more information on deployment, see Tool Mentor: Deploying J2EE Modules and Applications Using Rational XDE Developer - Java Platform Edition.