Using the Deployment Descriptor editor

JBuilder includes a Deployment Descriptor editor you can use to change Inprise deployment information (such as transaction policies and security roles in an EJB deployment descriptor file). You can also alter the method of persisting an enterprise bean.

JBuilder's Deployment Descriptor editor provides a way to modify the existing Inprise deployment descriptors. For general information about deployment descriptors, see "Deploying enterprise beans."


Displaying the Deployment Descriptor editor

To display the Deployment Descriptor editor, double-click the EJB group in the project pane. The deployment descriptor editor appears.

Note that a tree of the EJB group appears in the structure pane. Click the EJB Deployment Descriptor node in the structure pane to see the Properties page of the Deployment Descriptor editor:


Viewing the deployment descriptor of an enterprise bean

To view information about an enterprise bean in the deployment descriptor editor, double-click the bean in the structure pane. Or click the Contents tab to display the contents of the EJB group and then double-click the icon of bean you want to view. When you do, several more tabs appear in the in the Deployment Descriptor editor:

You can click any of these tabs at the bottom of the Deployment Descriptor editor to view other pages. Use the editor to make any changes you want to the deployment information for the bean.

To view the source code of each descriptor, click the EJB DD Source tab. For each deployment descriptor in the EJB group, a tab appears with the name of the file on the tab. Select the tab of the file you want to view.

You can view additional information about a deployment descriptor by using the structure pane:

Expand the node of the enterprise bean you're interested in in the structure pane. You'll see some or all of these additional nodes: Home Interface, Remote Interface, Method Permissions, and Container Transactions. Selecting any of these nodes displays additional information about the bean. For example, selecting Home Interface displays in the contents pane icons with the names of the methods in the home interface, and selecting Remote Interface displays the icons with names of the methods in the remote interface. You can also use the Security Roles and Data Sources nodes in the structure pane to display information on and edit security roles and data sources.


Adding information for a new enterprise bean

To add an enterprise bean to the deployment descriptor,
  1. Select the type of bean you wish to add.

    A name dialog box appears.

  2. In the dialog box, enter the name of the enterprise bean you want to add and choose OK.

    The new bean appears in the structure pane.

  3. Select the bean in the structure pane.

    A series of panels for the enterprise bean appears in the content pane. Use the tabs at the bottom to display the panel you want to use to enter information about the new bean.


Changing bean information

To change bean information, select the bean in the structure pane. A series of panels for the enterprise bean appears in the content pane. Use the tabs at the bottom to display the panel you want to use to modify the existing information about the new bean.

If you're comfortable working in XML and with deployment descriptor source code, you can select the EJB DD Source tab and make your changes directly in the source code.


Enterprise bean information

This section describes the type of information you can create and store for enterprise beans in the deployment descriptor.

Main panel

Use the Main panel to enter or change general information about the enterprise bean.

This is the Main panel for a session bean:

This is the Main panel for an entity bean:

The Main panel includes this information:

For Session beans, the Main panel also includes the following:

For Entity beans, the Main panel also includes the following:

Environment panel

The Environment panel lists all the enterprise bean's environment entries. Environment entries allow you to customize the bean's business logic when the bean is assembled or deployed. The environment allows you to customize the bean without accessing or changing the bean's source code.

Each enterprise bean defines its own set of environment entries. All instances of an enterprise bean share the same environment entries. Enterprise bean instances aren't allowed to modify the bean's environment at runtime.

To add an environment entry,

  1. Click Add to create a new entry.

    A new, blank row appears.

  2. Enter a property in the Property column and a property value in the Value column.

  3. Choose a property type from the Type menu.

  4. Continue to add environment entries as you desire.

To remove a row,

  1. Select the row.
  2. Click the Remove button.

These are some things to keep in mind about the environment entries:

EJB references panel

The EJB References panel lists all the enterprise bean references to the homes of other enterprise beans the bean requires.

Each EJB reference describes the interface requirements that the referencing enterprise bean has for the referenced bean. You can define references between beans within the same JAR file or from an external enterprise bean (one that is outside the JAR file), such as a session bean to an entity bean. Each reference contains these fields:

These are important points to remember about EJB references:

Security role references panel

The security role references panel lists all the enterprise bean's references to security roles. The panel links security role references used by the bean developer to specific security roles defined by the application assembler or deployer.

Before you can add a security role reference, one or more security roles must be already defined or the Add button on this panel is disabled. For information about creating and assigning security roles for application deployment, see "Adding security roles and method permissions."

To add a role, click the Add button and fill in the three fields:

Resource references panel

The resource references panel lists all the enterprise bean's resource factory references. This enables the application assembler and/or the bean deployer to locate all references used by the enterprise bean. Each entity bean with container-managed persistence must have a resource reference.

To add a resource reference, click the Add button and fill in the following fields:

Persistence panel

The Persistence panel appears only for entity beans. It specifies how persistence is managed for the enterprise bean. Information displayed on the panel varies depending on whether persistence is bean-managed or container-managed.

The persistence panel includes these fields:

For beans with container-managed persistence, the following additional information is included to enable you to map fields in the bean to columns in a database table:

To set up the entity bean for container-managed persistence, select Container as the Persistence Type. If you use the EJB Entity Modeler to generate the bean, Container will be already selected. The panel displays the pimary key class name, which you can't change. In the CMP Description field, you can enter optional text describing the bean.

Each field in your entity bean that will be container-managed has the CMP field checked. For each field, you enter the name of the column to which it maps. If you used the EJB Entity Modeler, JBuilder has already mapped these columns for you. You can edit the Column Name and Column Type if you choose. You can enter text describing each field in the Description field, but it's not required.

The Deployment Descriptor editor uses JDBC to obtain metadata on existing tables. You can conveniently hook up existing entity beans to existing tables. For example, you might purchase a third-party enterprise bean and want to use it with a table in your database. To populate both the Column Name and Column Type fields, click the Get Meta Data button and the metadata is retrieved and displayed.

Finders panel

The Finders panel specifies the "where" clauses used by the container-managed bean to execute finder methods defined by the bean.

You'll find this information on the finders panel:

To specify a finder method,

  1. Click the Add button.

    A Finder dialog box appears.

  2. Select the method signature for the finder method you want from the drop-down list.

  3. Modify the argument names, if you wish, and specify the proper Where clause for the find operation.

Here's an example:

Properties panel

The Properties panel contains varying information depending upon the context. When you select an enterprise bean in the structure pane, the following Properties pane appears:

To add a property to an enterprise bean selected in the structure pane,

  1. Click the Add button to add a row to the panel.

  2. From the Name drop-down list, select the property you want to add.

  3. Specify a value in the Value field.

    You specify some values by selecting a value from a drop-down list, others require you to enter an appropriate value such as a string or integer value, and one presents a check box for boolean values--checking the check box indicates the value is true. Here is the list of possible values and their descriptions:

    ejb.cmp.primaryKeyGenerator
    Specifies a class, written by the user, that implements the com.inprise.ejb.cmp.PrimaryKeyGenerator interface and generates primary keys. For more information about primary key generation, see the /Inprise/AppServer/examples/ejb/pkgen example.

    ejb.cmp.getPrimaryKeyBeforeInsertSql
    Specifies the SQL the CMP engine executes to generate a primary key when the next INSERT occurs. The CMP engine updates the entity bean with this primary key value. This property is usually used in conjunction with Oracle Sequences. For more information about primary key generation, see the /Inprise/AppServer/examples/ejb/pkgen example.

    ejb.cmp.getPrimaryKeyAfterInsertSql
    Specifies the SQL the CMP engine executes to generate a primary key after the next INSERT. The CMP engine updates the entity bean with this primary key value. When specifying this property, you must also specify the ejb.cmp.ignoreColumnsOnInsert property. For more information about primary key generation, see the /Inprise/AppServer/examples/ejb/pkgen example.

    ejb.cmp.ignoreColumnsOnInsert
    Specifies the name of the column the CMP must not set during the INSERT. This property is used in conjunction with the ejb.cmp.getPrimaryKeyAfterInsertSql property. For more information about primary key generation, see the /Inprise/AppServer/examples/ejb/pkgen example.

    ejb.cmp.checkExistenceBeforeCreate
    Suppresses the existence check that occurs before creating a new entity bean. The EJB 1.1 specification requires that the container first check for the existence of an entity bean (that is, check for the existence of a row in the table) and throw a javax.ejb.DuplicateKeyException if such an entity is found. For performance reasons, you might want to eliminate this extra access to the database and rely on the fact that the database will prevent duplicate values from being inserted.

    ejb.cmp.jdbcAccesserFactory
    Specifies a factory for a user-implemented instance of the com.inprise.ejb.cmp.JdbcAccessor interface. This interface gives you a way to write specific code to get a value from a java.sqlResultSet or to set a value to a java.sql.PreparedStatement. The default value is none.

    ejb.cmp.manager
    Specifies the name of a class implementing the interface com.inprise.ejb.cmp.Manager. An instance of this class is used to perform container-managed persistence (CMP).

    ejb.maxBeansInPool
    Specifies the maximum number of beans in the ready pool. If the ready pool exceeds this limit, entities will be removed from the container by calling unsetEntityContext(). The default setting is 1000.

    ejb.maxBeansInCache
    Specifies the maximum number of beans in the Option A cache (see ejb.transactionCommitMode which follows). If the cache exceeds this limit, entities will be moved to the ready pool by calling ejbPassivate(). The default setting is 1000.

    ejb.transactionCommitMode
    Indicates the disposition of an entity bean with respect to a transaction. The values are:

    A or Exclusive -- This entity has exclusive access to the particular table in the database. Thus, the state of the bean at the end of the last committed transaction can be assumed to be the state of the bean at the beginning of the next transaction. The beans are cached across transactions.

    B or Shared --This entity shares access to the particular table in the database. However, for performance reasons, a particular bean remains associated with a particular primary key between transactions to avoid extraneous calls to ejbActivate() and ejbPassivate() between transactions. The bean stays in the active pool. This setting is the default.

    C or None -- This entity shares access to the particular table in the database. A particular bean does not remain associated with a particular primary key between transactions, but goes back to the ready pool after every transaction. This is generally not a useful setting.

    ejb.cmp.optimisticConcurrencyBehavior
    You can specify one of the following:
    • UpdateAllFields
    • UpdateModifiedFields
    • VerifyModifiedFields
    • VerifyAllFields

    UpdateAllFields: Issues an update on all fields, regardless of whether they were modified. Given a CMP bean with three fields: "key", "value1" and "value2", stored in a table called "MyTable", the following update will be issued at the end of every transaction, regardless of whether the bean was modified:

        UPDATE MyTable SET (value1 = <value1>, value2 = <value2>) 
             WHERE key = <key>
    

    UpdateModifiedFields: This is the default setting. Issues an update only on the fields that were modified, or suppresses the update altogether if the bean was not modified. With the above bean, if only "value1" was modified, the following update is issued:

        UPDATE MyTable SET (value1 = <value1>) 
              WHERE key = <key>
    

    This can give a significant performance boost for following reasons:

    1) Very often your data access is read-only. In such cases, not sending an update to the database is desirable. Inprise have seen great performance boosts from this single optimization.

    2) Many databases write logs depending on which columns were modified. For example, SQL Server will log the update if a TEXT or IMAGE field is updated, regardless of whether the column's value actually changed. Note that the database often does not (or cannot) distinguish between updating a column to hold the same value it used to hold (which is what occurs with "UpdateAllFields"), and actually modifying the column's value. Suppressing the update for the case where the value did not actually change can have a very significant performance impact when using such DBMSs.

    3) There is less JDBC-based network traffic going to the database and less work going on in the JDBC driver. The network issue is, generally, not significant, but the JDBC driver issue is significant. Our performance measurements indicate that as many as 70% of the CPU's time is spent in the JDBC driver in large-scale EJB applications. Often, this is due to the fact that many commercial JDBC drivers have not been sufficiently performance tuned. Even for well-tuned drivers, the less work they have to do, the better.

    VerifyModifiedFields: In this mode, the CMP engine issues a tuned update while verifying that the fields it is updating are consistent with the values that were previously read in. So, for the previous example, where only "value1" was modified, the following update is issued:

        UPDATE MyTable SET (value1 = <value1>) 
              WHERE key = <key> AND value1 = <old-value1>
    

    VerifyAllFields: This mode is similar to VerifyModifiedFields, except that all fields are verified. So the update would be:

        UPDATE MyTable SET (value1 = <value1>) 
              WHERE key = <key> AND value1 = <old-value1> AND value2 = <old-value2>
    
    These two verify settings can be used to replicate the SERIALIZABLE isolation level in the Container. Often your application requires serializable isolation semantics. However, asking the database to implement this for you can have a significant performance impact. Our tests show using SERIALIZABLE with Oracle instead of a less restricted isolation level, can slow down an application over 50%. The main reason for this slowdown is that Oracle provides optimistic concurrency using a row-level locking model. With the above two settings, you are basically asking the CMP engine to implement optimistic concurrency using field-level locking. And with any concurrent system, the smaller the granularity of the locking, the better the concurrency.

    ejb.findByPrimaryKeyBehavior
    Indicates the desired behavior of the findByPrimaryKey() method. The values are:

    Verify -- The standard behavior for findByPrimaryKey() is to verify that the specified primary key exists in the database.

    Load -- This behavior causes the bean's state to be loaded into the container when findByPrimaryKey() is invoked, if the finder call is running in an active transaction. The assumption is that found objects will typically be used, and it is optimal to load the object's state at find time. This setting is the default.

    None -- This behavior indicates that findByPrimaryKey() should be a no-op. Basically, this causes the verification of the bean to be deferred until the object is actually used. Since it is always the case that an object could be removed between calling find and actually using the object, for most programs this optimization will not cause a change in client logic.

For information about the Properties panel in other contexts, see "Setting data source properties" and "Assigning method permissions."

Container transactions

Enterprise beans that use container-managed transactions must have the transaction policies set by the container. The Deployment Descriptor editor enables you to set container-managed transaction policies and then associate these policies with methods in the enterprise bean's home and remote interfaces.

Adding a container transaction

To add a container transaction,
  1. Double-click the enterprise bean in the structure pane to expand the bean's tree.

  2. Click Container Transactions in the structure pane.

  3. Click the Add button to add a row to the grid.

  4. In the row, select the Interface that exposes the method: either the home or remote interface, or select * to indicate both the home and remote interface.

  5. From the drop-down list of Methods available, select the method, or select * to select all the methods this transaction pertains to.

  6. From the drop-down list of Transaction Attributes, select the attribute you want the transaction to have.

    For a description of the transaction attributes available, see "Managing transactions."

  7. Enter a description in the Description field to describe the transaction. This information is optional.


Working with data sources

To view information on a data source in your deployment descriptor, expand the Data Sources node in the structure pane and select one of the data sources in the tree. The Deployment Descriptor editor displays this Data Source panel. You can use the panel to modify the information on the selected data source. Only entity beans have a data source.

The Deployment Descriptor editor enables you to specify a new data source for entity beans and to set the isolation level for the data transactions.

To add a new data source to the deployment descriptor,

  1. Click the icon on the Deployment Descriptor toolbar.

    A New DataSource dialog box appears.

  2. Enter the name of new data source and choose OK.

    The new data source is added to the tree in the structure pane.

  3. Select the data source in the tree.

  4. Enter the information for the new data source.

    The data source is defined by a data source name, the URL location of the data source, and (if required) a user name and password to access the source. The panel also includes the class name of the JDBC driver and JDBC properties.

  5. When you've specified the data source connection, you can choose the Test Connection button.

    The Deployment Descriptor editor attempts to make the connection with the specified data source. The results are posted in the message log.

Setting isolation levels

The term isolation level refers to the degree to which multiple, interleaved transactions are prevented from interfering with each other in a multi-user database. These are possible transaction violations:

The transaction isolation levels set in the deployment descriptor are defined based on the permitted violations just described.

Attribute Syntax Description
Uncommitted TRANSACTION_READ_UNCOMMITTED Allows all three violations
Committed TRANSACTION_READ_COMMITTED Allows non-repeatable reads and phantoms, but doesn't allow a dirty read.
Repeatable TRANSACTION_REPEATABLE_READ Allows phantoms, but not the other two violations.
Serializable TRANSACTION_SERIALIZABLE Doesn't allow any of the three violations.

Setting data source properties

When a data source is selected in the Deployment Descriptor editor, a Properties tab appears as well as the Data Source tab. The Properties panel allows you to set properties that affect the Inprise container-managed persistence (CMP) engine.

To modify the properties of a data source,

  1. Select the data source in the structure pane.

  2. Click the Properties tab.

  3. On the Properties panel, select a property to set from the Name drop-down list.

    The Type value is set automatically, depending on your selection from the Name list.

  4. Select a value in the Value column for your property.

  5. Add additional properties by clicking the Add button to add a new row, and then select the Name and Value entries for that new property.

These are the possible properties:

Property Description
uniqueSequence Determines whether the CMP engine should declare a unique sequence for the primary key columns. Usually this is achieved by declaring the appropriate columns to be primary keys (see primaryKeyDeclaration).
batchUpdates Indicates whether the CMP engine should batch updates to the database. This can have a significant performance benefit for transactions that update a number of entities that update a number of entities, and should be used if the driver supports it. Unfortunately, most don't support batch updates yet. The default value is false.
reuseStatements Determines whether the CMP engine should reuse prepared statements across transactions. Reusing prepared statements has a significant performance impact, and they should be used unless the JDBC driver exhibits are reused. The default value is true.
notNullDeclaration Determines whether the Java fields that can't be null (such as int or float) should map to non-null columns. The default value is true.
dialect Determines the type of the data source, such as whether its a JDataStore, Oracle, Informix, or other data source. Select the dialect value from the Value drop-down list. If you don't set this field, the CMP engine creates tables for JDataStore only. The default value is none.
primaryKeyDeclaration Determines whether the CMP engine declares the primary key columns in the table to be primary keys. Some databases don't support primary key declarations. The default value is true.


Adding security roles and method permissions

The Deployment Descriptor editor enables you to create or edit security roles in the deployment descriptor. After you create security roles, you can then associate methods in the enterprise bean's home and remote interfaces with these roles, thereby defining the security view of the application.

This section describes how to use the Deployment Description editor to create the security roles and assign enterprise bean methods to the roles. The section "Security role references panel" describes how to use the Roles panel to assign user groups and/or user accounts to the roles.

Defining security roles in the deployment descriptor is optional.

Creating a security role

To create a security role in the deployment descriptor,
  1. Click the icon on the Deployment Descriptor toolbar.

  2. In the dialog box that appears, enter the name of the new security role and choose OK.

The new role appears under the Security Roles node in the structure pane. If you don't see it, be sure to expand the Security Roles node. Also, a Properties panel for the role appears:

You can enter a description for the new role on the Properties panel. The description is optional.

Assigning method permissions

Once you've defined a security role, you can specify which methods in the home and remote interfaces of an enterprise bean the security role is allowed to invoke.

You aren't required to associate a security role with methods in a bean's home or remote interface. In these cases, none of the security roles defined in the deployment descriptor are allowed to invoke these methods.

To assign method permissions,

  1. Expand the bean's node in the structure pane to reveal its Method Permissions subnode.

  2. Select the Method Permission node to display a Properties panel.

    Each defined security role appears as a column heading.

  3. Click the Add button to add a row to the panel.

  4. In the new row, choose either Home or Remote or * to indicate both from the drop-down list in the Interface field.

  5. From the Method drop-down list, select the method you are granting permission to call, or select *, which indicates permission to call all the methods.

  6. Check the check box for each security role you want to give permission to call the specified methods.

  7. As a final step, you can enter an optional description in the Description field to describe the permission the row defines.

Verifying descriptor information

After you've finished editing the descriptor file, you can verify that the descriptor information is in the correct format, the required bean class files are present, and so on.

To verify descriptor information, click the Verify icon () on the Deployment Descriptor editor toolbar. Before choosing Verify, you can set Verify options by clicking the icon.

The Set Class Path is used for byte-code reflection, not for source code reflection. To enable byte-code reflection, add this statement to the Preferences section of the Inprise/AppServer/console/plugins/iaspt.ini file.

To set the class path, click the icon and use the dialog box that appears to set the new class path.

Verify does the following: