# @ejbgen:entity Annotation

Defines the class-scope properties of an entity bean.

## Scope

Class tag for an entity bean.

## Syntax

@ejbgen:entity

ejb-name="NameCMPBean"

prim-key-class="PKClassName"

[abstract-schema-name="AbstractSchemaName"]

[cache-between-transactions="True/False"]

[check-exists-on-method="True/False"]

[clients-on-same-server="True/False"]

[concurrency-strategy="ConcurrencyStrategyOption"]

[data-source-name="DataSourceName"]

[database-type="DatabaseOption"]

DEPRECATED [db-is-shared="True/False"]

[default-dbms-tables-ddl="DDLFileName."]

[default-transaction="DefaultTransactionOption"]

[delay-database-insert-until="ejbCreate/ejbPostCreate"]

[delay-updates-until-end-of-tx="True/False"]

[disable-warning="WarningsList"]

[dispatch-policy="DispatchPolicyQueue"]

[enable-batch-operations="True/False"]

[enable-call-by-reference="True/False"]

[enable-dynamic-queries="True/False"]

[finders-load-bean="True/False"]

[home-call-router-class-name="ClasName"]

[home-is-clusterable="True/False"]

[home-load-algorithm="LoadAlgorithmOption"]

[idle-timeout-seconds="TimeoutValue"]

[invalidation-target="ReadOnlyBean"]

[lock-order="number"]

[max-beans-in-cache="number"]

[optimistic-column="columnName"]

[order-database-operations="True/False"]

[persistence-type="CMP"]

[prim-key-class-nogen="True/False"]

[read-timeout-seconds="Seconds"]

[reentrant="True/False"]

[run-as="RoleName"]

[run-as-identity-principal="PrincipalName"]

[table-name="TableName"]

[trans-timeout-seconds="Seconds"]

[use-caller-identity="True/False"]

[use-select-for-update="True/False"]

[validate-db-schema-with="MetaData/TableQuery"]

[verify-columns="VerificationOption"]

[verify-rows="Read/Modified"]

## Attributes

ejb-name

Required. Specifies the (descriptive) name of the entity bean. When you create a new entity bean with the file name <name>Bean.ejb or <name>.ejb, the ejb-name will be <name> by default (but you can change this if desired). For more information, see How Do I: Create an Enterprise JavaBean?

prim-key-class

Required. Specifies the Java class of the primary key. When a compound primary key is used, this class will be auto-generated during the build process. When you use the ejbCreate dialog in Design view to create one or more ejbCreate methods, the primary-key-class will be automatically specified. For more information, see How Do I: Add a Create Method to an Entity Bean?

abstract-schema-name

Optional. Gives the abstract schema name for the CMP entity bean. When you create a new entity bean, by default the ejb-name and the abstract-schema-name are the same, but you can change this if desired. For more information on default naming, see the ejb-name attribute above. A unique abstract-schema-name is required when the entity bean definition contains query methods. For more information, see Query Methods and EJB QL.

cache-between-transactions

Optional. Specifies whether to cache the persistent data of an entity bean across (between) transactions. When left unspecified, it defaults to false. Caching options are discussed in detail in Accelerating Entity Bean Data Access.

check-exists-on-method

Optional. Valid values are true and false. When left unspecifed, the default is true. When true, the EJB container checks the database to verify that the CMP entity bean persistent record still exists at the end of a business method invocation, provided that this method did not already access any of the bean instance's persistent data.

clients-on-same-server

Optional. Specifies whether all clients are co-located with the entity bean on the same server. Valid values are true and false. When this attribute is left unspecified, its defaults to false. If set to True, the server instance will not multicast JNDI announcements for the EJB when it is deployed, that is, it turns off JNDI replication so that the EJB's JNDI name is only bound to the local server, hence reducing the startup time for large clusters.

concurrency-strategy

Optional. Defines the concurrency strategy for the entity bean. Valid values are ReadOnly, Exclusive, Optimistic, and Database. When left unspecified, the default is Database. Concurrency options are discussed in detail in Accelerating Entity Bean Data Access.

data-source-name

Optional. Specifies the data source that holds the database table(s) the entity bean uses.

database-type

Optional. Specifies the database type of the underlying Database Management System (DBMS). This attribute needs to be specified for WebLogic features that require database-specific implementations, such as eager loading of relationships (see Accelerating Entity Bean Data Access). Valid values are DB2, Informix, Oracle, SQLServer, Sybase, and PointBase.

db-is-shared

This feature is deprecated. Use cache-between-transactions instead.

default-dbms-tables-ddl

Optional. When you specify a file name for this attribute, the EJB container will write an exact copy of the table creation scripts it uses to enable the automatic table creation feature for the EJB to this file. For more information, see the create-tables attribute of @ejbgen:jar-settings Annotation.

default-transaction

Optional. Specifies the default transaction attribute to be applied to all methods that do not have a transaction attribute setting. Valid values are NotSupported, Supports, Required, RequiresNew, Mandatory, and Never. When the default-transaction is left unspecified, it defaults to Supports. When the transaction-type is set to Bean, the default-transaction attributed is ignored. For more information, see EJBs and Transactions.

delay-database-insert-until

Optional. The delay-database-insert-until attribute specifies the precise time when a new CMP bean is inserted into the database. Valid values are ejbCreate and ejbPostCreate. This attribute interacts with the order-database-operations attribute (see the Remarks below).

delay-updates-until-end-of-tx

Optional. Specifies whether updates will be executed at commit time at the end of a transaction. When left unspecified, this attribute defaults to True. This attribute interacts with the order-database-operations attribute (see the Remarks below).

disable-warning

Optional. Provide a comma-separated list of warnings that will be suppressed during deployment of this entity bean. The following warnings can be suppressed (for more information on deployment errors and warning messages, see the WebLogic Server documentation topic EJB Subsystem Messages). To suppress the warning, specify the warning message code in this attribute:

> - BEA-010054. The <ejbName> has a class <className> that is in the classpath. This class should only be located in the ejb-jar file.
> - BEA-010202. Call-by-reference is not enabled for the EJB <ejbName>. The server will have better performance if it is enabled. To enable call-by-reference, set the enable-call-by-reference property, located in the Tuning section of the Property Editor, to True.
> - BEA-010001. While deploying EJB <ejbName>, class <className> was loaded from the system classpath. As a result, this class cannot be reloaded while the server is running. To prevent this behavior in the future, make sure the class is not located in the server classpath.
> - BEA-010200. The EJB Module <moduleName> has a class <className> that contains a member. To update this class or any of its superclasses, you must redeploy the entire EJB Module. You cannot update these classes using the dynamic EJB impl class update feature.

Note. To disable deployment warnings for all EJBs in the project, use the disable-warning attribute of ejbgen:jar-settings.

dispatch-policy

Optional. Specifies the dispatch policy queue for this bean. If this attribute is not specified, the server's default execute thread pool is used.

enable-batch-operations

Optional. This attribute specifies whether to allow the EJB container to perform batch operations, including batch inserts, batch updates and batch deletes. When the attribute is not specified, it defaults to True. This attribute interacts with the order-database-operations attribute (see the Remarks below).

enable-call-by-reference

Optional. Specifies whether the container will call this EJB by reference. When left unspecified this attribute defaults to False. Setting this attribute to True will improve performance, but this can only be done under certain circumstances. For more information, see Accelerating Entity Bean Data Access.

enable-dynamic-queries

Optional. Specifies whether dynamic queries are enabled. When left unspecified, the attribute defaults to False. For more information, see Query Methods and EJB QL.

finders-load-bean

Optional. Specifies whether the bean's method will indeed honor field-group and relationship-caching settings. When left unspecified, this attribute defaults to true. When set to false, query methods will just load the primary key values of the beans returned by the query. For more information about eager loading for query methods and relationships, see Accelerating Entity Bean Data Access.

home-call-router-class-name

Optional. Specifies the name of a custom class to use for routing bean method calls. This class must implement weblogic.rmi.cluster.

home-is-clusterable

Optional. Specifies whether this bean can be deployed from multiple servers in a cluster.

home-load-algorithm

Optional. Specifies the algorithm to use for load-balancing between replicas of the EJB home. Valid values are RoundRobin, Random, WeightBased, RoundRobinAffinity, RandomAffinity, and WeightBasedAffinity.

idle-timeout-seconds

Optional. Specifies the maximum duration in seconds that an EJB will stay in the cache before it is removed. When left unspecified, there is no timeout. For more information, see Accelerating Entity Bean Data Access.

invalidation-target

Optional. Specifies the ejb-name of a read-only entity bean to be invalidated when the current CMP bean has been modified. For more information, see Accelerating Entity Bean Data Access.

lock-order

Optional. Specifies the relative database locking order of this bean relative to other beans during a cascade delete operation. Valid values are 0...n. When left unspecified, the EJB container determines lock order. Typically you should only use this attribute if the lock order used by the EJB container results in a database deadlock.

max-beans-in-cache

Optional. Specifies the maximum number of beans in the entity bean cache. When left unspecified, the default is 1000. If 0 is specified, there is no maximum. This attribute only applies to the entity bean's cache, and is ignored when an application-level cache is used instead for this bean. If this maximum has been reached, existing instances might be passivated to make room for new instances. For more information, see Accelerating Entity Bean Data Access.

optimistic-column

Optional. Specifies the column that holds the timestamp or version number for optimistic concurrency. For more information, see Accelerating Entity Bean Data Access.

order-database-operations

Optional. Specifies whether to sort the database operations - insert, update, delete - at commit time to take into account data dependencies. When left unspecified, this attribute defaults to True. This attributes interacts with various other attributes (see the Remarks below).

persistence-type

Optional. Specifies the type of the entity bean. The only valid value is CMP. When left unspecified, the default is CMP.

prim-key-class-nogen

Optional. Set this attribute to True if you have defined the compound primary key class for this entity bean and don't want WebLogic to use a auto-generated primary key class. When not specified, this attribute defaults to False.

read-timeout-seconds

Optional. Specifies the number of seconds before a read-only bean's cached data times out and needs to be refreshed. When left unspecified, the default is 600. To never time out, set this attribute to 0. For more information, see Accelerating Entity Bean Data Access.

reentrant

Optional. Specifies whether an entity bean is reentrant (can be used concurrently). If not specified, this attribute defaults to False.

run-as

Optional. Specifies the EJB-scoped security role this bean should run under. To use this attribute, use-caller-identity must be False. Also make sure that the security role is defined using the @ejbgen:role-mapping Annotation. For more information, see Role-Based Security.

run-as-identity-principal

Optional. Specifies the name of the principal to run as in case the security role specified with the run-as attribute maps to several principals. To specify this attribute you must also specify the run-as attribute. You must specify the run-as-identity-principal attribute when the run-as security role is externally defined. For more information, see Role-Based Security.

table-name

Optional. Specifies the table to which this entity bean is mapped. By default the same name as the ejb-name is used. For more information on default naming, see the ejb-name attribute above.

trans-timeout-seconds

Optional. Specifies the transaction timeout (in seconds). If not specified, this attribute defaults to 30 seconds.

use-caller-identity

Optional. Specifies whether or not this entity bean runs using the caller's security identity. When not specified, this attribute defaults to True. You must set this attribute to False to use the run-as and run-as-identity-principal attributes. For more information, see Role-Based Security.

use-select-for-update

Optional. When set to true, this attribute causes SELECT ... FOR UPDATE to be used when the bean is loaded from the database. This locks the bean's record(s) in the database for the duration of the transaction it is involved in.

validate-db-schema-with

Optional. This attribute specifies the method used to validate the table(s) created by the EJB container for the CMP entity bean. Valid values are MetaData and TableQuery. If you specify MetaData, WebLogic uses the JDBC metadata to validate the schema. If you specify TableQuery, WebLogic queries the tables directly to verify that they match the definition of the CMP bean. When this attribute is left unspecified, TableQuery is used. Also see the section Automatic Table Creation of the @ejbgen:jar-settings Annotation.

verify-columns

Optional. Specifies how optimistic concurrency verifies that the columns have or have not been modified during transactions. Valid values are Read, Modified, Version, and Timestamp. In order to use this attribute, the concurrency-strategy attribute needs to be set to Optimistic. For more information, see Accelerating Entity Bean Data Access.

verify-rows

Optional. Specifies how optimistic concurrency verifies that the rows have or have not been modified during transactions. Valid values are Read and Modified, In order to use this attribute, the concurrency-strategy attribute needs to be set to Optimistic. For more information, see Accelerating Entity Bean Data Access.

## Remarks

The following comments apply to this tag's use:

- By default, the order-database-operations and enable-batch-operations attributes are set to True. This means that database operations - inserts, updates, deletes - are not actually executed until commit time at the end of a transaction. Related database operations are grouped and executed in batch, typically resulting in performance enhancement. For more information, see Accelerating Entity Bean Data Access. When your database driver does not support batch operations, set the enable-batch-operations attribute to False.
- When the order-database-operations attribute is set to True, the delay-updates-until-end-of-tx and delay-database-insert-until attributes are ignored.
- When the order-database-operations attribute is set to False, insert and delete database operations are executed at the end of each method while update operations are performed during commit time. To execute database updates at the end of each method, set the delay-updates-until-end-of-tx attribute to False.
- When the order-database-operations attribute is set to False, you can delay database inserts until ejbPostCreate by specifying this value in the delay-database-insert-until attribute. If you set a relationship field in the ejbPostCreate method, the delay-database-insert-until attribute should be set to ejbCreate. For more information, see Entity Relationships.

Related Topics

@ejbgen:file-generation Annotation

@ejbgen:cmr-field Annotation

@ejbgen:cmp-field Annotation

@ejbgen:jar-settings Annotation

Getting Started with Entity Beans

Accelerating Entity Bean Data Access

Role-Based Security