Tools Guide

Chapter 10   Deployment Descriptor Editor

The Deployment Descriptor Editor provides a quick and easy way to construct and populate J2EE-compatible deployment descriptors. This chapter describes the Deployment Descriptor Editor and includes these topics:

• About deployment descriptors

• About the Deployment Descriptor Editor

• Using the Deployment Descriptor Editor

About deployment descriptors

A deployment descriptor is an XML document that provides information about the components of a J2EE module (such as a WAR or an EJB JAR) or application (such as an EAR). The deployment descriptor provides data that is required for both of the following:

• Application assembly—to describe how a component is or should be used

• Deployment—to define deployment needs such as roles and resource references

Sun has defined the contents and structure for a deployment descriptor for each J2EE component. For more information, see J2EE Deployment Descriptor DTDs in the online Reference.

How deployment descriptors are created   Workbench automatically constructs and adds a J2EE-compatible deployment descriptor file to your project in the appropriate location, as follows:

As you add J2EE components to a project, Workbench adds the corresponding elements to the deployment descriptor when it has enough information to do so.

About the Deployment Descriptor Editor

The Deployment Descriptor Editor allows you to fine-tune the deployment descriptor by modifying or completing entries that Workbench is unable to complete automatically.

The Deployment Descriptor Editor displays the deployment descriptor elements as expandable nodes. The nodes correspond to elements of the deployment descriptor DTD. All possible deployment descriptor entries are represented graphically, so you can use the interface to help you add the appropriate entries without having to memorize the DTD.

Here is a sample Deployment Descriptor Editor for an EJB project:

TIP   You can view or edit the deployment descriptor in raw XML by choosing the XML tab. The Deployment Descriptor Editor opens in the mode (raw XML or tree view) in use when it was last saved.

Nodes displayed in bold (like Environment and Persistent Fields) allow child nodes to be added or removed. You can add or remove these nodes by right-clicking and selecting from the popup menu.

Many of the nodes require additional information, and you can provide this information by completing a property sheet. To display the Property Inspector for a node, highlight the node, right-click, and select Properties.

To save the changes to the deployment descriptor file in the archive, select File>Save (or click the Save icon).

Using the Deployment Descriptor Editor

You can use the Deployment Descriptor Editor either to fine-tune the default deployment descriptor created by Workbench or to create a new deployment descriptor.

To create a deployment descriptor:

1. Open the project for which you want to create the new deployment descriptor.

2. Select File>New.

3. Select the J2EE tab.

4. Select Deployment Descriptor and click OK.

   Workbench constructs the deployment descriptor shell based on the contents of the project and displays the shell in the Edit Pane.

To associate a deployment descriptor with a project:

NOTE   If you created a deployment descriptor outside the Workbench environment, you can still use it with a Workbench project by following these steps.

1. Open the Workbench project that you want to associate the deployment descriptor with.

2. Choose the Directory Pane.

3. Double-click the deployment descriptor you want.

   You are prompted to associate the descriptor with the current project, a different project (which you can choose), or to edit the deployment descriptor in XML mode.

4. Choose the option to associate the descriptor with the current project, then choose OK.

   Workbench opens the deployment descriptor in the Deployment Plan Editor.

5. Save the deployment descriptor to complete the association.

To modify a deployment descriptor:

1. Open the project whose deployment descriptor you want to modify.

2. Highlight the project file (the SPF), right-click, and select Open Deployment Descriptor from the popup menu.

   You are prompted for your Build preferences.

   Once you specify the Build preferences, the Deployment Descriptor Editor opens the file ready for editing.

To add a deployment descriptor element:

1. Open the deployment descriptor for editing.

2. Highlight the descriptor element, right-click, and choose Add from the popup menu.

   The editor adds a new element with the title UntitledXXX.

3. Highlight the new element, right-click, and choose Properties from the popup menu to launch the Property Inspector so you can define any necessary values.

To remove a deployment descriptor element:

1. Open the deployment descriptor for editing.

2. Make sure the Descriptor tab (not XML tab) is selected.

3. Highlight the descriptor element you want to remove, right-click, and select Delete from the popup menu.

   NOTE   If Delete is not available as a menu option, the element is not removable.

Validating a deployment descriptor

The Deployment Descriptor Editor automatically checks your work as follows:

But you can force validation anytime.

To force validation of a deployment descriptor:

• Choose Validate Archive from the Project menu.

  This validates both the deployment descriptor and the archive.

Tools Guide

Copyright © 2002, SilverStream Software, Inc. All rights reserved.