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, you must also 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.
- If the Boundary attribute is set to ActivitySession, then the
local transactions are enlisted as ActivitySession resources and directed
to complete by the ActivitySession.
- If the the Boundary attribute is set to BeanMethod, then the local
transactions are committed at method end by the container.
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).
Setting 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.
-
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.