Entity bean assembly settings

An entity bean encapsulates persistent data, which is stored in a data source, and associated methods to manipulate that data.

EJB name

Specifies a logical name for the enterprise bean. This name must be unique within the EJB module. There is no relationship between this name and the JNDI name.

Display name

Specifies a short name that is intended to be displayed by GUIs.

Description

Contains text that describes the entity bean.

EJB class

Specifies the full name of the enterprise bean class (for example, com.ibm.ejs.doc.account.AccountBean).

Remote - Home

(Required for EJB 1.x) Specifies the full name of the enterprise bean's home interface class (for example, com.ibm.ejs.doc.account.AccountHome).

Remote - Interface

(Required for EJB 1.x) Specifies the full name of the enterprise bean's remote interface class (for example, com.ibm.ejs.doc.account.Account).

Local interface - Home

(Required for EJB 1.x) Specifies the full name of the enterprise bean's local home interface class (for example, com.ibm.ejs.doc.account.AccountLocalHome).

Local interface - Interface

(Required for EJB 1.x) Specifies the full name of the enterprise bean's local interface class (for example, com.ibm.ejs.doc.account.AccountLocal).

Persistence type

Specifies whether an entity bean manages its own persistent storage or whether storage is managed by the container.
Data type String
Range Valid values are Bean managed and Container managed.

Reentrant

Specifies whether the entity bean is reentrant. If an enterprise bean is reentrant, it can call methods on itself or call another bean that calls a method on the calling bean. Only entity beans can be reentrant.

If an entity bean is not reentrant and a bean instance is executing a client request in a transaction context and another client using the same transaction context makes a request on the same bean instance, the EJB container throws the java.rmi.RemoteException exception to the second client. If a bean is reentrant, the container cannot distinguish this type of illegal loopback call from a legal concurrent call, so the bean must be coded to detect illegal loopback calls.

Primary key class

Specifies the full name of the bean's primary key class (for example, com.ibm.ejs.doc.account.AccountKey). Composite primary keys map to multiple fields in the entity bean class (or to data structures built from the primitive Java data types) and must be encapsulated in a primary key class.

More complicated enterprise beans are likely to have composite primary keys, with multiple instance variables representing the primary key. A subset of the container-managed fields is used to define the primary key class associated with each instance of an enterprise bean.

Primary key field

Specifies the name of a simple primary key. Simple primary keys map to a single field in the entity bean class and are made up of primitive Java data types (such as integer or long). If exactly one CMP field is the primary key, it can be specified here.
Data type String
Range Valid values are the name of any one CMP field or Compound key, which appears when the primary key class is set

Version

Specifies the version of EJB specification with which a container-managed persistence (CMP) entity bean complies.
Data type String
Range Valid values are 1.x or 2.x

Abstract schema name

Specifies the name of the abstract schema type of an EJB Version 2.x CMP entity bean. It is used in EJB Query Language (QL) queries.

For example, the abstract schema name might be Order for an entity bean whose local interface is com.acme.commerce.Order.

Small icon

Specifies the name of a JPEG or GIF file that contains a small image (16x16 pixels). The image is used as an icon to represent the entity bean in a GUI.

Large icon

Specifies the name of a JPEG or GIF file that contains a large image (32x32 pixels). The image is used as an icon to represent the entity bean in a GUI.

Security identity

Specifies that a principal's credential properties are to be handled as indicated in the Run-As mode property. If this setting is enabled, the Run-As mode property can be edited.

Run-As mode

Specifies the credential information to be used by the security service to determine the permissions that a principal has on various resources.

At appropriate points, the security service determines whether the principal is authorized to use a particular resource based on the principal's permissions. If the method call is authorized, the security service acts on the principal's credential properties according to the Run-As mode setting of the enterprise bean.

Data type Enumerated integer
Range Valid values are Use identity of caller and Use identity assigned to specified role

Additional information about valid settings follows:

Use identity of caller

The security service makes no changes to the principal's credential properties.

Use identity assigned to specified role

A principal that has been assigned to the specified security role is used for the execution of the bean's methods. This association is part of the application binding in which the role is associated with a user ID and password of a user who is granted that role.

Role name

Specifies the name of a security role. If Run-As mode is set to Use identity assigned to specified role, a principal that has been granted this role is used.

Description

Contains further information about the security role.

Concurrency control

Specifies how the bean is to handle concurrent access to its data. This setting is applicable only for EJB 1.x-compliant entity beans.

This property is an IBM extension to the standard J2EE deployment descriptor.

Data type String
Range Valid values are Optimistic or Pessimistic

Inheritance root

Specifies whether the enterprise bean is at the root of an inheritance hierarchy.

This property is an IBM extension to the standard J2EE deployment descriptor.

Bean Cache - Activate at

Specifies the point at which an enterprise bean is activated and placed in the cache. Removal from the cache and passivation is also governed by this setting.

This property is an IBM extension to the standard J2EE deployment descriptor.

Data type String
Default Transaction
Range Valid values are Once, Transaction, and Activity session

More information about valid values follows:

Once

Indicates that the bean activates when it is first accessed in the server process, and passivates (and is removed from the cache) at the discretion of the container, for example, when the cache becomes full.

Transaction

Indicates that the bean activates at the start of a transaction and passivates (and is removed from the cache) at the end of the transaction.

Activity session

Indicates that the bean activates and passivates as follows:

  • On an ActivitySession boundary, if an ActivitySession context is present on activation

  • On a transaction boundary, if a transaction context (but no ActivitySession context) is present on activation

  • Otherwise, on an invocation boundary

The values of the Activate at and Load at settings govern which commit options are used, as follows:

  • For commit option A (implies exclusive database access), use Activate at = Once and Load at = Activation.

    This option reduces database I/O (avoids calls to the ejbLoad function) but serializes all transactions accessing the bean instance. Option A can increase memory usage by maintaining more objects in the cache, but can provide better response time if bean instances are not generally accessed concurrently by multiple transactions. To use Option A successfully, set Concurrency control to Pessimistic.

    Note for Network Deployment users: When workload management is enabled, you cannot use Option A. You must use settings that result in the use of options B or C.

  • For commit option B (implies shared database access), use Activate at = Once and Load at = Transaction.

    Option B can increase memory usage by maintaining more objects in the cache. However, because each transaction creates its own copy of an object, there can be multiple copies of an instance in memory at any given time (one per transaction), requiring database access at each transaction. If an enterprise bean contains a significant number of calls to the ejbActivate function, using Option B is beneficial because the required object is already in the cache. Otherwise, this option does not provide significant benefits over Option A.

  • For commit option C (implies shared database access), use Activate at = Transaction and Load at = Transaction.

    This option reduces memory usage by maintaining fewer objects in the cache; however, there can be multiple copies of an instance in memory at any given time (one per transaction). This option can reduce transaction contention for enterprise bean instances that are accessed concurrently but not updated.

Bean Cache - Load at

Specifies when the bean loads its state from the database. The value of this setting implies whether the container has exclusive or shared access to the database.

This property is an IBM extension to the standard J2EE deployment descriptor.

Data type String
Default Transaction
Range Valid values are Activation and Transaction

Additional information about valid values follows:

Activation

Indicates that the bean loads when it is activated (regardless of Activate at setting) and implies that the container has exclusive access to the database.

Transaction

Indicates that the bean loads at the start of a transaction and implies that the container has shared access to the database.

The Activate at and Load at settings govern which commit options are used. The commit options are described in the Enterprise JavaBeans specification. For more information about this setting and achieving a given commit behavior, see Bean Cache - Activate at.

Commit option

Specifies which commit option is used as a result of bean cache settings. The commit options are described in the Enterprise JavaBeans specification.
Data type String
Range Valid values are A, B, and C

Local Transactions - Unresolved action

Specifies the action that the EJB container must take if resources are uncommitted by an application in a local transaction.

This property is an IBM extension to the standard J2EE deployment descriptor. This setting is applicable only when Resolution control is set to Application. A local transaction context is created when a method runs in what the EJB specification refers to as an unspecified transaction context.

Data type String
Default Rollback
Range Valid values are Commit and Rollback

Additional information about these settings follows:

Commit

At end of the local transaction context, the container instructs all unresolved local transactions to commit.

Rollback

(Default) At end of the local transaction context, the container instructs all unresolved local transactions to roll back.

Local Transactions - Resolution control

Specifies how the local transaction is to be resolved before the local transaction context ends: by the application through user code or by the EJB container.

This property is an IBM extension to the standard J2EE deployment descriptor.

Data type String
Range Valid values are Application and ContainerAtBoundary

Additional information about these settings follows:

Application

When this setting is used, your code must either commit or roll back the local transaction. If this does not occur, the runtime environment logs a warning and automatically commits or rolls back the connection as specified by the Unresolved action setting.

ContainerAtBoundary

When this setting is used, the container takes responsibility for resolving each local transaction. This provides you with a programming model similar to global transactions in which your code simply gets a connection and performs work within it. User code does not have to handle local transactions.

Connections are never committed automatically by the resource adapter when this value is configured for the bean Unresolved action is not used. An application cannot call Connection.LocalTransaction.begin() when using this policy and receives an exception from the resource adapter if it does so.

When using a Resolution control of ContainerAtBoundary, applications must get connection handles after the local transaction context boundary has been started by the container. The application should close the connection before the end of the boundary, although any work performed on the connection is not committed or rolled back until the local transaction context ends. This model of connection usage is sometimes referred to as the "get-use-close" model.

This value is supported only for EJB components that use container-managed transactions. It is not supported for web components or for enterprise beans that use bean-managed transactions.

Local Transactions - Boundary

Specifies the duration of a local transaction context.

This property is an IBM extension to the standard J2EE deployment descriptor.

Data type String
Default BeanMethod
Range Valid values are BeanMethod and ActivitySession

Additional information about valid settings follows:

BeanMethod

When this setting is used, the local transaction begins when the method begins and ends when the method ends.

ActivitySession

When this setting is used, the local transaction must be resolved within the scope of any ActivitySession in which it was started or, if no ActivitySession context is present, within the same bean method in which it was started.

This property can be changed on WebSphere Application Server Enterprise only.

Local Relationship Roles - Name

Within a local relationship between EJB 1.x-compliant entity beans, the logical name for the view an entity bean presents to other beans in the relationship.

For example, in a relationship between Account and Customer beans, the role of the Account instance relative to the Customer instance might be savingsAccount.

This property is an IBM extension to the standard J2EE deployment descriptor. This is separate from the container-managed relationships defined in the Enterprise JavaBeans specification, Version 2.0.

Local Relationship Roles - Source EJB Name

The name of the entity bean for which the role is defined.

This property is an IBM extension to the standard J2EE deployment descriptor.

Local Relationship Roles - is Forward

Specifies how deployment code for navigating the relationship is generated. This setting is applicable only for navigable relationships.

If isForward is enabled (set to true), deployment code is generated in the source bean. That is, navigation of the relationship proceeds forward from the source to the target.

Otherwise, deployment code is generated in the target bean. That is, navigation of the relationship proceeds from the target to the source.

This property is an IBM extension to the standard J2EE deployment descriptor. For more information, see the documentation for the Deployment Tool for Enterprise JavaBeans.

Local Relationship Roles - is Navigable

Specifies whether data in related beans may be retrieved through queries to the source bean.

This property is an IBM extension to the standard J2EE deployment descriptor.

Lifetime in cache

The lifetime, in seconds, of cached data for an instance of this bean type.

This value indicates how long the cached data is to exist beyond the end of the transaction in which the data was retrieved. This might avoid another retrieval from persistent storage if the same bean instance were to be used in later transactions. How this value is interpreted depends on the value of Lifetime in cache usage.

This property is an IBM extension to the standard J2EE deployment descriptor.

Data type Long
Units Seconds
Default 0
Range 0 to 261 - 1

Lifetime in cache usage

Indicates how the lifetime-in-cache setting is to be used by the caching mechanism.

This property is an IBM extension to the standard J2EE deployment descriptor.

If your application uses CMP beans in which the underlying data changes infrequently, you might gain significantly better performance by using this setting with Lifetime in cache. Typically, data read from persistent storage is held temporarily in an internal cache until the state of the instance is restored. Cached data normally does not persist beyond state restoration or the end of the transaction in which the finder method was called. By setting Lifetime in cache usage to a value other than Off, you indicate that the cached data is to be held for a longer time, potentially hours or days, before invalidating the version of the data in the cache and fetching a new version. Avoiding a trip to persistent storage greatly speeds up access to such beans by applications.

In addition, the use of a value other than Off requires that finders on the bean have an access type of Optimistic Read (if you are only reading instances of the bean) or Optimistic Update (if you plan to occasionally update instances of the bean).

Set Bean Cache - Activate at to activation and Bean Cache - Load at to Once also minimizes retrievals from persistent storage. However, this settings combination might not be supported by certain CMP beans because it results in the ejbLoad() method being called once instead of at the beginning of each transaction in which they are used. The lifetime-in-cache settings combination is independent of CMP bean implementation, though it does incur the modest overhead of calling ejbLoad() on each use.

Data type Enumerated int
Units Not applicable
Default 0 (Off)
Range Valid values are Clock Time, Elapsed Time, Week Time, or Off

Additional information about valid values follows:

Off

When this value is used, the value of Lifetime in cache is ignored. Beans of this type are cached only in a transaction-scoped cache. The cached data for this instance expires after the transaction in which it was retrieved is completed.

Elapsed Time

When this value is used, the value of Lifetime in cache is added to the time at which the transaction in which the bean instance was retrieved is completed. The resulting value becomes the time at which the cached data expires. The value of Lifetime in cache can add up to minutes, hours, days, and so on.

Clock Time

When this value is used, the value of Lifetime in cache represents a particular time of day. The value is added to the immediately preceeding or following midnight to calculate a future time value, which is then treated as for Elapsed Time. Using Clock Time enables you to specify that all instances of this bean type are to have their cached data invalidated at, for example, 3 AM, no matter when they were retrieved. This is important if, for example, the data underlying this bean type is batch-updated at 3 AM every day.

The selection of midnight (preceding or following) depends on the value of Lifetime in cache. If Lifetime in cache plus the value that represents the preceeding midnight is earlier than the current time, the following midnight is used.

When you use Clock Time, the value of Lifetime in cache is not supposed to represent more than 24 hours. If it does, the cache manager subtracts 24-hour increments from it until a value less than or equal to 24 hours is achieved. To invalidate data at midnight, set Lifetime in cache to 0.

Week Time

Usage of this value is the same as for Clock Time, except that the value of Lifetime in cache is added to the preceeding or following Sunday midnight (11:59 PM Saturday plus 1 minute). When Week Time is used, the value of Lifetime in cache can represent more than 24 hours but not more than 7 days.

Default Access Intent

Specifies the default access intent under which the entity should load.

Applicability of the following table: [Fix Pack 5.0.2 and later]

Data type String
Units Not applicable
Default Not applicable
Range Valid settings are wsPessimisticUpdate, wsPessimisticUpdate-NoCollision, wsPessimisticUpdate-Exclusive, wsPessimisticUpdate-WeakestLockAtLoad, wsPessimisticRead, wsOptimisticUpdate, or wsOptimisticRead.

JNDI name

Specifies the JNDI name of the bean's home interface. This is the name under which the enterprise bean's home interface is registered and therefore, is the name that must be specified when an EJB client does a lookup of the home interface.

Data source - JNDI name

Specifies the JNDI name for the bean's data source.

Default Authorization - User ID

Specifies the default user ID for connecting to a data source.

Default Authorization - Password

Specifies the default password for connecting to a data source.

CMP Resource - JNDI name

Specifies the JNDI name for the resource by which CMP data is stored.

CMP Resource - Resource authentication

Specifies the scope at which resources are to be authenticated: by the container or by the resource.