EJB Deployment Descriptor editor

The EJB deployment descriptor editor is used to modify EJB JAR files and associated Java™ files.

The EJB deployment descriptor editor is organized with pages and sections that represent the various properties and settings in the EJB deployment descriptor. Additionally, the editor includes sections and pages related specifically to WebSphere® Application Server bindings and extensions to the EJB specification.

The core function is typically located at the top of an editor page. To see core pages and sections, set focus on the editor and press alt-shift-c. The core pages, sections, headers, and tabs will highlight blue and remain in this state until you press alt-shift-c again. The extensions and bindings are usually nested sections and found at the bottom of the editor pages. Collapsing a section hides the content, but leaves the heading information. This is useful in filtering through the data and properties on each page. The editor remember the sections that you collapse when you close and reopen the editor. Also, you can resize sections by dragging a hidden border at the end or beginning of each section.

Another important feature of the editor is the enhanced wizard support. You can open wizards from the editor that walk you through creation and modification of the various elements. The wizards help you determine problems while stepping through the creation process. If an error occurs, or if you enter invalid data, the wizard displays a warning or error message at the top of the wizard page. Wizards offer the ability to create or edit many objects at one time, and you can work on multiple beans at the same time.

The EJB editor modifies the following resources:

Although the EJB deployment descriptor editor pages can change depending on the capabilities that you have enabled (Window > Preferences > Workbench > Capabilities) the EJB deployment descriptor editor typically displays the following main tabbed pages:

Overview page

Use the Overview page to view, create, and modify the basic properties of the EJB module. This should be the first place that you look for editor content. The body of this page is a user interface representation of the ejb-jar.xml file. The core XML tags of the ejb-jar.xml are broken down into the following sections:

General Information
Use this section to add a display and description name. These names are used for identification on the Web server and J2EE view.
Usage
Use this section to view a list of links to editors that are associated with the EJB JAR. For example, if the EJB JAR was defined in an EAR, the EAR name would appear as a link. Clicking on the link launches the EAR deployment descriptor editor.
Enterprise JavaBeans™
Use this section to view a list of links corresponding to the beans in the EJB. Clicking on a link takes you to the Beans page and highlights the enterprise bean.
Assembly Descriptor
This section has a Details button that links to the Assembly page. The Assembly page has sections and wizards for security roles, method permissions, container transactions, and the excludes list.
EJB Client JAR
This section displays the name of the EJB client JAR file that is created for the EJB module. If no EJB client JAR file has been created, you can click the Create button to open the EJB Client JAR Creation wizard and create the JAR file.
References
This section also has a Details button that links to the References page.
Relationships 2.0
This section is available for EJB 2.0 modules only. The relationship section contains a list of existing relationships. All creation and modification of a relationship can be done here.
Icons
Use this section to assign an icon for the EJB JAR. This is primarily used for identification at run time.
WebSphere Extensions
Displays only if the project is targeted to a WebSphere Application Server. This section contains 1.x Relationships and Inheritance composites. Each area has an Edit button that launches a wizard to update the deployment descriptor properties for the selected bean.
WebSphere Bindings
Displays only if the project is targeted to a WebSphere Application Server.

For EJB 1.1 modules:

  • JNDI Default DataSource Binding: Use this section to specify the DataSource JNDI name, the JNDI user ID, and DataSource password.
For EJB 2.0 modules:
  • Backend ID: Use this section to determine the persister classes that get loaded at deployment.
  • JNDI CMP Factory Connection Binding: Use this section to specify the JNDI name container authorization type. You can choose either container-managed authentication or component-managed authentication.

Bean page

Use the Bean page to create, modify, and remove function and resources from enterprise beans. The left side of the Bean page shows a list of beans in the EJB project. On the right side, a scrollable section contains the details for the selected bean. For example, if you select an EJB 1.x CMP entity bean, only the sections that are relevant to that type of bean are displayed.

The beans page includes the following sections:

General section
All enterprise beans have a general section that gives you quick access to common information. For EJB 1.1 CMP entity beans, the section contains the display name, reentrant type, description, and CMP Fields. EJB 2.x CMP entity beans also have a field for abstract schema name. The display name and description field are used for identification within the J2EE view and on the Web server. You can use the reentrant field when you do not want a bean to be accessed until it has finished with its current execution. Abstract schema name is set and used when you are creating EJBQL statements. The Attribute section allows you to create and remove attributes. Attributes are mapped fields that access the database to persist and retrieve data.

Double-click a bean to open the Java source code in the Java editor.

Class and Interface Files
For EJB 1.1 and EJB 2.x beans. Use this section to modify Java resources associated with the bean. For example, if you want to open the bean Java class and add business logic, you could double-click the bean class or select the bean class in the table and click Open. The Open button launches a Java editor that supports editing enterprise beans. The class interface section also gives you the ability to change Java resources to other existing resources. Clicking the Browse button can access this reuse function. You will be prompted with a resource browse dialog. You can also use the remove function that launches a wizard that helps you delete resources.
Environment Variables
For EJB 1.1 and EJB 2.x beans. Use this section to add, remove, and modify environment variables. Double-clicking a variable in the editor highlights the appropriate element in the Source view.

Environment variables are constant variables that you define in Web and EJB components. For example, if you define a Circle bean, you could create an environment variable called PI and set the value to 3.1415926. If you had another enterprise bean or servlet called Cone, it could access the PI variable by doing a JNDI lookup.

Icons
For EJB 1.1 and EJB 2.x beans. The icon section is similar to the EJB JAR section. Use this section to assign an icon on the bean level. This is primarily used for identification at runtime.
Message-Driven Destination
For EJB 2.x message-driven beans. Use this section to specify the destination type and subscription durability for the message-driven bean.
Relationships
For EJB 2.x CMP entity beans. Use this section to create and work with relationships for EJB 2.0 CMP entity beans.
Access Beans
For EJB 1.1 and EJB 2.x session and entity beans. Not available for message-driven beans. Use this section to create and edit access beans. Access beans are convenient ways to gain access to your enterprise beans.
Queries
For EJB 2.x CMP entity beans. Use this section to create finder methods and assign finder statements to those methods. You can also remove finder descriptors. A finder method resides on the home interface. Finder Descriptors are assigned to these methods. The finder descriptor is used to query the database to return specific bean instances. Click Add to open the finder wizard that gives you the option to create or use an existing finder method. After the method is created, the wizard helps you to add descriptor information.
WebSphere Bindings
Displays only if the project is targeted to a WebSphere Application Server. For EJB 1.1 and EJB 2.x beans. Use this section to specify binding properties for the WebSphere Application Server. The datasource is used to lookup the designated database at runtime. You must create the datasource in the server configuration. If you are using WebSphere Application Server, you can do this using the server tools. The user name and password are used for verification upon access of the database.
WebSphere Extensions
Displays only if the project is targeted to a WebSphere Application Server. For EJB 1.1 and EJB 2.x beans. Use this section to specify additional extensions for use with the WebSphere Application Server. The following sections or fields are available, depending on the type and level of the selected bean:
Session timeout
For session beans, use this section to specify a timeout value and activity session type.
Relationships
For EJB 1.1 CMP entity beans. Use this section to define relationships.
Finders
For EJB 1.1 CMP entity beans. Use this section to create finder methods and assign finder statements to those methods. You can also remove finder descriptors. A finder method resides on the home interface. Finder Descriptors are assigned to these methods. The finder descriptor is used to query the database to return specific bean instances. Click Add to open the finder wizard that gives you the option to create or use an existing finder method. After the method is created, the wizard helps you to add descriptor information.
Bean Cache
Use this section to define the bean cache settings.
Compensation
Use this section to enable the bean to use WebSphere Application Server support for the Web Services Business Activity standard.

Select the Run EJB methods under a business activity scope check box to specify that the application component must execute under a business activity scope that is associated with its unit of work. The business activity scope is a demarcation boundary for any compensation handlers registered by the component or any other components running under the same scope. Business activity scopes are distributed between remote runtimes using the mechanisms described in the Web Services Business Activity (WS-BusinessActivity) specification.

If you choose to run EJB methods under a business activity scope, you can optionally specify a compensation handler to perform corrective actions if the business activity fails. The compensation handler class name is the name of an application class that implements the com.ibm.websphere.wsba.CompensationHandler interface and is deployed as part of the application. Compensation handlers are called when the business activity scope ends, and are passed any compensation data that was supplied by the application during forward execution of the scope.

Global Transaction
Global transaction settings are WebSphere Application Server extensions to the Enterprise JavaBeans specification. If an application uses two or more resources, then an external transaction manager is needed to coordinate the updates to both resource managers in a global transaction.
Local Transaction 2.0
Use this section to define the local transaction settings.
Locale Invocation
Using these settings can maximize the performance of the EJB running on WebSphere Application Server.
Data Cache
For EJB 2.x CMP entity beans. Use this section to specify lifetime in cache and lifetime in cache usage.
Concurrency Control
For 1.1 CMP entity beans. By default, optimistic locking is not enabled, which means that if an entity bean is accessing a row in the database, another bean will not be able to edit that row until the original bean has released it. If an edit is attempted while the row is locked an exception will be thrown.

References page

Use the References page to define references for the enterprise beans in the project. WebSphere Bindings for the references, such as the JNDI name for the reference, are also set on this page. Select a bean and click Add to open the Add Reference wizard. See Defining references for J2EE modules for more information.

The Reference page is setup like the bean page, where the selection in the left main section dynamically changes the right side detail sections.

WS Handler page

Use the Handlers page to define Web service handlers for each Web service reference that is defined for the enterprise beans in the EJB module. See Defining Web service handlers for more information.

Assembly page

Use this page to define security roles, method permissions, and method transactions. It also allows you to exclude methods from security constraints. The Assembly page has the following sections:

Security Roles
Use this section to define security roles. Security roles are needed in order to build the method permissions. This section lists the security roles that are defined and displays details for the selected security role.
Method Permissions
Use this section to add permissions to beans on the method level. This section contains a tree that has a list of existing method permissions. When you create a new method permission, you will see it in the tree. If you expand the tree, the bean and methods that are defined in the method permission are displayed.
Container Transactions
To add a container transaction, click Add to launch the Container Transaction wizard. Clicking the Remove button while any tree object is selected will remove the Transaction.
Excludes List
For EJB 2.x modules, use this section to mark method elements as uncallable by the deployment descriptor.

Access page

Use the Access page to define access intent, isolation level, and security identity properties variables for CMP entity beans. Depending on the EJB version level of the EJB project, the access page displays different sections, including WebSphere extensions. Available sections include the following sections:

Security Identity (Bean level)
Use this section to add security identities.
Default Access Intent for Entities 2.x (Bean Level)
Use this section to define default access intent for bean-level security identity.
Access Intent for Entities 2.x (Method Level)
Use this section to define access intent for method-level security identity.
Access Intent for Entities 1.x
A WebSphere Application Server extension. Use this section to define default access intent for bean-level security identity.
Isolation level
A WebSphere Application Server extension. Use this section to define default access intent for bean-level security identity.
Security Identity (Method level)
A WebSphere Application Server extension. Use this section to add security identities.

WS Extension page

Use this page to define Web service client security extensions for WebSphere Application Server.

WS Binding page

Use this page to define Web service client bindings for WebSphere Application Server.

Mediation Handlers page

Use this page to edit the deployment descriptor file for your mediation handler enterprise bean, and save it as an EAR file ready to export to WebSphere Application Server.

A mediation handler is a Java program that acts as the unit of deployment and administration in mediations. It has mediation parameters that control its behaviour. Mediation handlers are the components of mediation handler lists. Each mediation handler executes some specific message processing at run-time, for example:
  • Transforming a message from one format into another.
  • Routing messages to one or more target destinations that were not specified by the sending application.
  • Augmenting messages by adding data from a data source.

Source page

Use the Source page to view and modify the XML source code associated with deployment descriptor (ejb-jar.xml) for the EJB module. The Source page is an XML editor. The XML changes dynamically when the EJB deployment descriptor editor is edited. When you make changes to the XML source, the other pages of the EJB deployment descriptor editor reflect these changes.

Changes in the EJB deployment descriptor editor are not committed until the editor is saved. If the editor is closed without saving, then the changes are not committed. This also includes the changes that are made to the Java files and the bindings and extension files, which can be edited by the EJB deployment descriptor editor. If an existing Java editor is currently opened and a change is made in the EJB deployment descriptor editor that causes code to be generated into the Java file that is currently opened, the changes will be generated into the open editor. If the EJB deployment descriptor editor is saved, the Java changes will also be saved. If the EJB deployment descriptor editor is closed without saving, all changes will be thrown away except the change that is currently in the open Java editor. Those changes will remain because there was another reference to the file that was currently opened. You will only be prompted to save the EJB deployment descriptor editor if there are no other references to it or its resources. If there are two EJB deployment descriptor editors opened in two different perspectives, or you have an EJB deployment descriptor editor and EJB deployment descriptor editor open in one or more perspectives, the changes will appear in both and you will only be prompted to save when the last is closed.

Related tasks
Defining Web service handlers

Feedback