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."
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:
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.
To add an entity bean, click the icon on the Deployment Descriptor editor toolbar.
A name dialog box appears.
The new bean appears 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.
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.
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:
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,
A new, blank row appears.
To remove a row,
These are some things to keep in mind about the environment entries:
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:
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:
To add a resource reference, click the Add button and fill in the following fields:
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.
You'll find this information on the finders panel:
To specify a finder method,
A Finder dialog box appears.
Here's an example:
To add a property to an enterprise bean selected in the structure pane,
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:
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.ignoreColumnsOnInsert
property. For more information about primary key generation, see the /Inprise/AppServer/examples/ejb/pkgen example.
ejb.cmp.getPrimaryKeyAfterInsertSql
property. For more information about primary key generation, see the /Inprise/AppServer/examples/ejb/pkgen example.
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.
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.
com.inprise.ejb.cmp.Manager
. An instance of this class is used to perform container-managed persistence (CMP).
unsetEntityContext()
. The default setting is 1000.
ejbPassivate()
. The default setting is 1000.
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.
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.
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."
For a description of the transaction attributes available, see "Managing transactions."
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,
A New DataSource dialog box appears.
The new data source is added to the tree in the structure pane.
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.
The Deployment Descriptor editor attempts to make the connection with the specified data source. The results are posted in the message log.
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. |
To modify the properties of a data source,
The Type value is set automatically, depending on your selection from the Name list.
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. |
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.
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.
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,
Each defined security role appears as a column heading.
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: