Skip navigation.
Downloads | Product Documentation | Support

Programming WebLogic Enterprise JavaBeans

# Important Information for EJB 1.1 Users

BEA strongly recommends that new users implement their distributed business applications using EJB 2.0 beans. However, if your existing application implements EJB 1.1 beans, please read the following sections, which contain important design and implementation information specific to EJB 1.1. This section includes a detailed reference to EJB 1.1 deployment descriptors.

- Writing for RDBMS Persistence for EJB 1.1 CMP
- Using WebLogic Query Language (WLQL) for EJB 1.1 CMP
- Using SQL for CMP 1.1 Finder Queries
- Tuned EJB 1.1 CMP Updates in WebLogic Server
- Using is-modified-method-name to Limit Calls to ejbStore()
- 5.1 weblogic-ejb-jar.xml Deployment Descriptor File Structure
- 5.1 weblogic-ejb-jar.xml Deployment Descriptor Elements
- 1.1 weblogic-cmp-jar.xml Deployment Descriptor File Structure
- 1.1 weblogic-cmp-jar.xml Deployment Descriptor Elements

# Writing for RDBMS Persistence for EJB 1.1 CMP

Clients use finder methods to query and receive references to entity beans that fulfill query conditions. This section describes how to write finders for WebLogic-specific 1.1 EJBs that use RDBMS persistence. You use EJB QL, a portable query language, to define finder queries for 2.0 EJBs with container-managed persistence.

WebLogic Server provides an easy way to write finders.

1. Write the method signature of a finder in the `EJBHome` interface.
2. Define the finder's query expressions in the `ejb-jar.xml` deployment file.

`appc` creates implementations of the finder methods at deployment time, using the queries in `ejb-jar.xml`.

The key components of a finder for RDBMS persistence are:

- The finder method signature in `EJBHome`.
- A `query` stanza defined within `ejb-jar.xml`.
- An optional `finder-query` stanza within `weblogic-cmp-jar.xml`.

The following sections explain how to write EJB finders using XML elements in WebLogic Server deployment files.

## Finder Signature

Specify finder method signatures using the form `find` `MethodName``()`. Finder methods defined in `weblogic-cmp-jar.xml` must return a Java collection of EJB objects or a single object.

Note: You can also define a `findByPrimaryKey(primkey)` method that returns a single object of the associated EJB class.

## finder-list Stanza

The `finder-list` stanza associates one or more finder method signatures in `EJBHome` with the queries used to retrieve EJB objects. The following is an example of a simple `finder-list` stanza using WebLogic Server RDBMS-based persistence:

>     <finder-list>

>          <finder>

>               <method-name>findBigAccounts</method-name>

>               <method-params>

>                    <method-param>double</method-param>

>               </method-params>

>               <finder-query><![CDATA[(> balance $0)]]></finder-query>

>          </finder>

>     </finder-list>

Note: If you use a non-primitive data type in a `method-param` element, you must specify a fully qualified name. For example, use `java.sql.Timestamp` rather than `Timestamp`. If you do not use a qualified name, `appc` generates an error message when you compile the deployment unit.

## finder-query Element

The `finder-query` element defines the WebLogic Query Language (WLQL) expression you use to query EJB objects from the RDBMS. WLQL uses a standard set of operators against finder parameters, EJB attributes, and Java language expressions. See Using WebLogic Query Language (WLQL) for EJB 1.1 CMP for more information on WLQL.

Note: Always define the text of the `finder-query` value using the XML `CDATA` attribute. Using `CDATA` ensures that any special characters in the WLQL string do not cause errors when the finder is compiled.

A CMP finder can load all beans using a single database query. So, 100 beans can be loaded with a single database round trip. A bean-managed persistence (BMP) finder must do one database round trip to get the primary key values of the beans selected by the finder. As each bean is accessed, another database access is also typically required, assuming the bean wasn't already cached. So, to access 100 beans, a BMP might do 101 database accesses.

# Using WebLogic Query Language (WLQL) for EJB 1.1 CMP

WebLogic Query Language (WLQL) for EJB 1.1 CMP allows you to query 1.1 entity EJBs with container-managed persistence. In the `weblogic-cmp-jar.xml` file, each `finder-query` stanza must include a WLQL string that defines the query used to return EJBs. Use WLQL for EJBs and their corresponding deployment files that are based on the EJB 1.1 specification.

## WLQL Syntax

WLQL strings use the prefix notation for comparison operators, as follows:

>     (operator operand1 operand2)

Additional WLQL operators accept a single operand, a text string, or a keyword.

## WLQL Operators

The following are valid WLQL operators.

Operator | Description | Sample Syntax
--- | --- | ---
`=` | Equals | `(= operand1 operand2)`
`<` | Less than | `(< operand1 operand2)`
`>` | Greater than | `(> operand1 operand2)`
`<=` | Less than or equal to | `(<= operand1 operand2)`
`>=` | Greater than or equal to | `(>= operand1 operand2)`
`!` | Boolean not | `(! operand)`
`&` | Boolean and | `(& operand)`
`|` | Boolean or | `(| operand)`
`like` | Wildcard search based on % symbol in the supplied `text_string` or an input parameter | `(like` `text_string``%)`
`isNull` | Value of single operand is null | `(isNull operand)`
`isNotNull` | Value of single operand is not null | `(isNotNull operand)`
`orderBy` | Orders results using specified database columns Note: Always specify a database column name in the `orderBy` clause, rather than a persistent field name. WebLogic Server does not translate field names specified in `orderBy`. | `(orderBy '``column_name``')`
`desc` | Orders results in descending order. Used only in combination with `orderBy`. | `(orderBy '``column_name` `desc')`

## WLQL Operands

Valid WLQL operands include:

- Another WLQL expression
- A container-managed field defined elsewhere in the `weblogic-cmp-jar.xml` file

Note: You cannot use RDBMS column names as operands in WLQL. Instead, use the EJB attribute (field) that maps to the RDBMS column, as defined in the attribute-map in `weblogic-cmp-jar.xml`.

- A finder parameter or Java expression identified by `$``n`, where `n` is the number of the parameter or expression. By default, `$``n` maps to the nth parameter in the signature of the finder method. To write more advanced WLQL expressions that embed Java expressions, map `$``n` to a Java expression.

Note: The `$n` notation is based on an array that begins with 0, not 1. For example, the first three parameters of a finder correspond to `$0`, `$1`, and `$2`. Expressions need not map to individual parameters. Advanced finders can define more expressions than parameters.

## Examples of WLQL Expressions

The following example code shows excerpts from the `weblogic-cmp-jar.xml` file that use basic WLQL expressions.

- This example returns all EJBs that have the `balance` attribute greater than the `balanceGreaterThan` parameter specified in the finder. The finder method signature in EJBHome is:

>     public Enumeration findBigAccounts(double balanceGreaterThan)

>          throws FinderException, RemoteException;

The sample `<finder>` stanza is:

>     <finder>

>          <method-name>findBigAccounts</method-name>

>          <method-params>

>               <method-param>double</method-param>

>          </method-params>

>          <finder-query><![CDATA[(> balance $0)]]></finder-query>

>     </finder>

Note that you must define the `balance` field n the attribute map of the EJB's persistence deployment file.

Note: Always define the text of the `finder-query` value using the XML `CDATA` attribute. Using `CDATA` ensures that any special characters in the WLQL string do not cause errors when the finder is compiled.

- The following example shows how to use compound WLQL expressions. Also note the use of single quotes (') to distinguish strings:

>     <finder-query><![CDATA[(& (> balance $0) (! (= accountType 'checking')))]]></finder-query>

- The following example finds all the EJBs in a table. It uses the sample finder method signature:

>     public Enumeration findAllAccounts()

>          throws FinderException, RemoteException

The sample `<finder>` stanza uses an empty WLQL string:

>     <finder>

>          <method-name>findAllAccounts</method-name>

>          <finder-query></finder-query>

>     </finder>

- The following query finds all EJBs whose lastName field starts with "M":

>     <finder-query><![CDATA[(like lastName M%)]]></finder-query>

- This query returns all EJBs that have a null `firstName` field:

>     <finder-query><![CDATA[(isNull firstName)]]></finder-query>

- This query returns all EJBs whose balance field is greater than 5000, and orders the beans by the database column, id:

>     <finder-query><![CDATA[WHERE >5000 (orderBy 'id' (> balance 5000))]]></finder-query>

- This query is similar to the previous example, except that the EJBs are returned in descending order:

>     <finder-query><![CDATA[(orderBy 'id desc' (> ))]]></finder-query>

# Using SQL for CMP 1.1 Finder Queries

WebLogic Server allows you to use a SQL string instead of the standard WLQL query language to write SQL for a CMP 1.1 finder query. The SQL statement retrieves the values from the database for the CMP 1.1 finder query. Use SQL to write a CMP 1.1 finder query when a more complicated finder query is required and you cannot use WLQL.

For more information on WLQL, see Using WebLogic Query Language (WLQL) for EJB 1.1 CMP.

To specify this SQL finder query:

1. In the `weblogic-cmp-jar.xml` file write a SQL query using the `finder-sql` element in the `weblogic-cmp-jar.xml` file as follows.

`findBigAccounts(double cutoff)` as follows:

>     <finder-sql><![CDATA{balance >$0]]></finder-sql>

Use values like $0, or $1 in the SQL string to reference the parameters to the finder method. The WebLogic Server EJB container replaces the `$` parameters but will not interpret the SQL query.

2. The Container emits the following SQL:

`SELECT <columns> FROM table WHERE balance > ?`

The SQL should be the WHERE clause of an SQL statement. The Container prepends the SELECT and FROM clauses. The WHERE clause may contain arbitrary SQL.

If you use characters in your SQL query that may confuse an XML parser, such as the.greater than (>) symbol and the less than (<) symbol, make sure that you declare the SQL query using the CDATA format shown in the preceding sample SQL statement.

You can use any amount of vendor-specific SQL in the SQL query.

# Tuned EJB 1.1 CMP Updates in WebLogic Server

EJB container-managed persistence (CMP) automatically support tuned updates because the container receives `get` and `set` callbacks when container-managed EJBs are read or written. Tuning EJB 1.1 CMP beans helps improve their performance.

WebLogic Server now supports tuned updates for EJB 1.1 CMP. When `ejbStore` is called, the EJB container automatically determines which container-managed fields have been modified in the transaction. Only modified fields are written back to the database. If no fields are modified, no database updates occur.

With previously versions of WebLogic Server, you could to write an `isModified` method that notified the container whether the EJB 1.1 CMP bean had been modified. `isModified` is still supported in WebLogic Server, but BEA Systems recommends that you no longer use `isModified` methods and instead allow the container to determine the update fields.

This feature is enabled for EJB 2.0 CMP, by default. To enable tuned EJB 1.1 CMP updates, make sure that you set the following deployment descriptor element in the `weblogic-cmp-jar.xml` file to `true`.

>     <enable-tuned-updates>true</enable-tuned-updates>

You can disable tuned CMP updates by setting this deployment descriptor element as follows:

>     <enable-tuned-updates>false</enable-tuned-updates>

In this case, `ejbStore` always writes all fields to the database.

# Using is-modified-method-name to Limit Calls to ejbStore()

The `is-modified-method-name` deployment descriptor element applies to EJB 1.1 container-managed-persistence (CMP) beans only. This element is found in the`weblogic-ejb-jar.xml` file. WebLogic Server CMP implementation automatically detects modifications of CMP fields and writes only those changes to the underlying datastore. BEA Systems recommends that you not use `is-modified-method-name` with bean-managed-persistence (BMP) because you would need to create both the `is-modified-method-name` element. and the`ejbstor`e method.

By default, WebLogic Server calls the `ejbStore()` method at the successful completion (commit) of each transaction. `ejbStore()` is called at commit time regardless of whether the EJB's persistent fields were actually updated, and results in a DBMS update. WebLogic Server provides the `is-modified-method-name` element for cases where unnecessary calls to `ejbStore()` may result in poor performance.

To use `is-modified-method-name`, EJB providers must first develop an EJB method that "cues" WebLogic Server when persistent data has been updated. The method must return "false" to indicate that no EJB fields were updated, or "true" to indicate that some fields were modified.

The EJB provider or EJB deployment descriptors then identify the name of this method by using the value of the `is-modified-method-name` element. WebLogic Server calls the specified method name when a transaction commits, and calls `ejbStore()` only if the method returns "true." For more information on this element, see is-modified-method-name.

# 5.1 weblogic-ejb-jar.xml Deployment Descriptor File Structure

`The WebLogic Server 5.1 weblogic-ejb-jar.xml` file defines the EJB document type definitions (DTD)s you use with EJB 1.1 beans. These deployment descriptor elements are WebLogic-specific. The top level elements in the WebLogic Server 5.1 `weblogic-ejb-jar.xml` are as follows:

- `description`
- `weblogic-version`

- `weblogic-enterprise-bean`
- `ejb-name`
- `caching-descriptor`
- `persistence-descriptor`
- `clustering-descriptor`
- `transaction-descriptor`
- `reference-descriptor`
- `jndi-name`
- `transaction-isolation`

- `security-role-assignment`

# 5.1 weblogic-ejb-jar.xml Deployment Descriptor Elements

The following sections describe WebLogic-Server 5.1 `weblogic-ejb-jar.xml` deployment descriptor elements.

## caching-descriptor

The `caching-descriptor` stanza affects the number of EJBs in the WebLogic Server cache as well as the length of time before EJBs are passivated or pooled. The entire stanza, as well as each of its elements, is optional. WebLogic Server uses default values where no elements are defined.

The following is a sample `caching-descriptor` stanza that shows the caching elements described in this section:

>     <caching-descriptor>

>        <max-beans-in-free-pool>500</max-beans-in-free-pool>

>        <initial-beans-in-free-pool>50</initial-beans-in-free-pool>

>        <max-beans-in-cache>1000</max-beans-in-cache>

>        <idle-timeout-seconds>20</idle-timeout-seconds>

>        <cache-strategy>Read-Write</cache-strategy>

>        <read-timeout-seconds>0</read-timeout-seconds>

>     </caching-descriptor>

### max-beans-in-free-pool

Note: This element is valid only for stateless session EJBs.

WebLogic Server maintains a free pool of EJBs for every bean class. This optional element defines the size of the pool. By default, `max-beans-in-free-pool` has no limit; the maximum number of beans in the free pool is limited only by the available memory.

### initial-beans-in-free-pool

Note: This element is valid only for stateless session EJBs.

If you specify a value for `initial-bean-in-free-pool`, WebLogic Server populates the free pool with the specified number of bean instances at startup. Populating the free pool in this way improves initial response time for the EJB, since initial requests for the bean can be satisfied without generating a new instance.

`initial-bean-in-free-pool` defaults to 0 if the element is not defined.

### max-beans-in-cache

Note: This element is valid only for stateful session EJBs and entity EJBs.

This element specifies the maximum number of objects of this class that are allowed in memory. When `max-bean-in-cache` is reached, WebLogic Server passivates some EJBs that have not been recently used by a client. `max-beans-in-cache` also affects when EJBs are removed from the WebLogic Server cache.

The default value of `max-beans-in-cache` is 100.

### idle-timeout-seconds

`idle-timeout-seconds` defines the maximum length of time a stateful EJB should remain in the cache. After this time has elapsed, WebLogic Server may remove the bean instance if the number of beans in cache approaches the limit of `max-beans-in-cache`.

`idle-timeout-seconds` defaults to 600 if you do not define the element.

### cache-strategy

The `cache-strategy` element can be one of the following:

- `Read-Write`
- `Read-Only`

The default value is `Read-Write`.

### read-timeout-seconds

The `read-timeout-seconds` element specifies the number of seconds between `ejbLoad()` calls on a `Read-Only` entity bean. By default, `read-timeout-seconds` is set to 600 seconds. If you set this value to 0, WebLogic Server calls `ejbLoad` only when the bean is brought into the cache.

## persistence-descriptor

The `persistence-descriptor` stanza specifies persistence options for entity EJBs. The following shows all elements contained in the `persistence-descriptor` stanza:

>     <persistence-descriptor>

>        <is-modified-method-name>. . .</is-modified-method-name>

>        <delay-updates-until-end-of-tx>. . .</delay-updates-until-end-of-tx>

>        <persistence-type>

>           <type-identifier>. . .</type-identifier>

>           <type-version>. . .</type-version>

>           <type-storage>. . .</type-storage>

>        </persistence-type>

>        <db-is-shared>. . .</db-is-shared>

>        <stateful-session-persistent-store-dir>

>           . . .

>        </stateful-session-persistent-store-dir>

>        <persistence-use>. . .</persistence-use>

>     </persistence-descriptor>

### is-modified-method-name

`is-modified-method-name` specifies a method that WebLogic Server calls when the EJB is stored. The specified method must return a `boolean` value. If no method is specified, WebLogic Server always assumes that the EJB has been modified and always saves it.

Providing a method and setting it as appropriate can improve performance. However, any errors in the method's return value can cause data inconsistency problems.

### delay-updates-until-end-of-tx

Set this property to `true` (the default), to update the persistent store of all beans in a transaction at the completion of the transaction. This generally improves performance by avoiding unnecessary updates. However, it does not preserve the ordering of database updates within a database transaction.

If your datastore uses an isolation level of `TransactionReadCommittedUncommitted`, you may want to allow other database users to view the intermediate results of in-progress transactions. In this case, set `delay-updates-until-end-of-tx` to `false` to update the bean's persistent store at the conclusion of each method invoke.

Note: Setting `delay-updates-until-end-of-tx` to false does not cause database updates to be "committed" to the database after each method invoke; they are only sent to the database. Updates are committed or rolled back in the database only at the conclusion of the transaction.

### persistence-type

A `persistence-type` defines a persistence service that can be used by an EJB. You can define multiple `persistence-type` entries in `weblogic-ejb-jar.xml` for testing with multiple persistence services. Only the persistence type defined in persistence-use is used during deployment.

`persistence-type` includes several elements that define the properties of a service:

- `type-identifier` contains text that identifies the specified persistence type. For example, WebLogic Server RDBMS persistence uses the identifier, `WebLogic_CMP_RDBMS`.
- `type-version` identifies the version of the specified persistence type.

Note: The specified version must exactly match the RDBMS persistence version for the WebLogic Server release. Specifying an incorrect version results in the error:

>     weblogic.ejb.persistence.PersistenceSetupException: Error initializing the CMP Persistence Type for your bean: No installed Persistence Type matches the signature of (identifier `Weblogic_CMP_RDBMS', version `version_number').

- `type-storage` defines the full path of the file that stores data for this persistence type. The path must specify the file's location relative to the top level of the EJB's JAR deployment file or deployment directory.

WebLogic Server RDBMS-based persistence generally uses an XML file named `weblogic-cmp-jar.xml` to store persistence data for a bean. This file is stored in the `META-INF` subdirectory of the JAR file.

The following shows an example `persistence-type` stanza with values appropriate for WebLogic Server RDBMS persistence:

>     <persistence-type>

>         <type-identifier>WebLogic_CMP_RDBMS</type-identifier>

>         <type-version>5.1.0</type-version>

>         <type-storage>META-INF\weblogic-cmp-jar.xml</type-storage>

>     </persistence-type>

### db-is-shared

The `db-is-shared` element applies only to entity beans. When set to `true` (the default value), WebLogic Server assumes that EJB data could be modified between transactions and reloads data at the beginning of each transaction. When set to `false,` WebLogic Server assumes that it has exclusive access to the EJB data in the persistent store.

### stateful-session-persistent-store-dir

`stateful-session-persistent-store-dir` specifies the file system directory where WebLogic Server stores the state of passivated stateful session bean instances.

### persistence-use

The `persistence-use` property is similar to persistence-type, but it defines the persistence service actually used during deployment. `persistence-use` uses the type-identifier and type-version elements defined in a `persistence-type` to identify the service.

For example, to actually deploy an EJB using the WebLogic Server RDBMS-based persistence service defined in persistence-type, the `persistence-use` stanza would resemble:

>     <persistence-use>

>        <type-identifier>WebLogic_CMP_RDBMS</type-identifier>

>        <type-version>5.1.0</type-version>

>     </persistence-use>

## clustering-descriptor

The `clustering-descriptor` stanza defines the replication properties and behavior for EJBs deployed in a WebLogic Server cluster. The `clustering-descriptor` stanza and each of its elements are optional, and are not applicable to single-server systems.

The following shows all elements contained in the `clustering-descriptor` stanza:

>     <clustering-descriptor>

>        <home-is-clusterable>. . .</home-is-clusterable>

>        <home-load-algorithm>. . .</home-load-algorithm>

>        <home-call-router-class-name>. . .</home-call-router-class-name>

>        <stateless-bean-is-clusterable>. . .</stateless-bean-is-clusterable>

>        <stateless-bean-load-algorithm>. . .</stateless-bean-load-algorithm>

>        <stateless-bean-call-router-class-name>. . .</stateless-bean-call-router-class-name>

>        <stateless-bean-methods-are-idempotent>. . .</stateless-bean-methods-are-idempotent>

>     </clustering-descriptor>

### home-is-clusterable

You can set this element to either `true` or `false`. When `home-is-clusterable` is true, the EJB can be deployed from multiple WebLogic Servers in a cluster. Calls to the home stub are load-balanced between the servers on which this bean is deployed, and if a server hosting the bean is unreachable, the call automatically fails over to another server hosting the bean.

### home-load-algorithm

`home-load-algorithm` specifies the algorithm to use for load balancing between replicas of the EJB home. If this property is not defined, WebLogic Server uses the algorithm specified by the server property, `weblogic.cluster.defaultLoadAlgorithm`.

You can define `home-load-algorithm` as one of the following values:

- `round-robin`: Load balancing is performed in a sequential fashion among the servers hosting the bean.
- `random`: Replicas of the EJB home are deployed randomly among the servers hosting the bean.
- `weight-based`: Replicas of the EJB home are deployed on host servers according to the servers' current workload.

### home-call-router-class-name

`home-call-router-class-name` specifies the custom class to use for routing bean method calls. This class must implement `weblogic.rmi.extensions.CallRouter()`. If specified, an instance of this class is called before each method call. The router class has the opportunity to choose a server to route to based on the method parameters. The class returns either a server name or null, which indicates that the current load algorithm should select the server.

### stateless-bean-is-clusterable

This property is similar to `home-is-clusterable`, but it is applicable only to stateless session EJBs.

### stateless-bean-load-algorithm

This property is similar to `home-load-algorithm`, but it is applicable only to stateless session EJBs.

### stateless-bean-call-router-class-name

This property is similar to `home-call-router-class-name`, but it is applicable only to stateless session EJBs.

### stateless-bean-methods-are-idempotent

You can set this element to either `true` or `false`. Set `stateless-bean-methods-are-idempotent` to `true` only if the bean is written such that repeated calls to the same method with the same arguments has exactly the same effect as a single call. This allows the failover handler to retry a failed call without knowing whether the call actually completed on the failed server. Setting this property to `true` makes it possible for the bean stub to automatically recover from any failure as long as another server hosting the bean can be reached.

Note: This property is applicable only to stateless session EJBs.

## transaction-descriptor

The `transaction-descriptor` stanza contains elements that define transaction behavior in WebLogic Server. Currently, this stanza includes only one element:

>     <transaction-descriptor>

>        <trans-timeout-seconds>20</trans-timeout-seconds>

>     <transaction-descriptor>

### trans-timeout-seconds

The `trans-timeout-seconds` element specifies the maximum duration for the EJB's container-initiated transactions. If a transaction lasts longer than `trans-timeout-seconds`, WebLogic Server rolls back the transaction.

If you specify no value for `trans-timeout-seconds`, container-initiated transactions timeout after five minutes, by default.

## reference-descriptor

The `reference-descriptor` stanza maps references in the `ejb-jar.xml` file to the JNDI names of actual resource factories and EJBs available in WebLogic Server.

The `reference-descriptor` stanza contains one or more additional stanzas to define resource factory references and EJB references. The following shows the organization of these elements:

>     <reference-descriptor>

>        <resource-description>

>           <res-ref-name>. . .</res-ref-name>

>           <jndi-name>. . .</jndi-name>

>        </resource-description>

>        <ejb-reference-description>

>           <ejb-ref-name>. . .</ejb-ref-name>

>           <jndi-name>. . .</jndi-name>

>        </ejb-reference-description>

>     </reference-descriptor>

### resource-description

The following elements define an individual `resource-description`:

- `res-ref-name` specifies a resource reference name. This is the reference that the EJB provider places within the `ejb-jar.xml` deployment file.
- `jndi-name` specifies the JNDI name of an actual resource factory available in WebLogic Server.

### ejb-reference-description

The following elements define an individual `ejb-reference-description`:

- `ejb-ref-name` specifies an EJB reference name. This is the reference that the EJB provider places within the `ejb-jar.xml` deployment file.
- `jndi-name` specifies the JNDI name of an actual EJB available in WebLogic Server.

### enable-call-by-reference

By default, EJB methods called from within the same EAR pass arguments by reference. This increases the performance of method invocation since parameters are not copied.

If you set `enable-call-by-reference` to `false`, parameters to EJB methods are copied (pass by value) in accordance with the EJB 1.1 specification. Pass by value is always necessary when the EJB is called remotely (not from within the same application).

### jndi-name

The `jndi-name` element specifies a jndi-name for a bean, resource, or reference.

## transaction-isolation

The `transaction-isolation` stanza specifies the transaction isolation level for EJB methods. The stanza consists of one or more `isolation-level` elements that apply to a range of EJB methods. For example:

>     <transaction-isolation>

>     	<isolation-level>Serializable</isolation-level>

>     	<method>

>     		<description>...</description>

>     		<ejb-name>...</ejb-name>

>     		<method-intf>...</method-intf>

>     		<method-name>...</method-name>

>     		<method-params>...</method-params>

>     	</method>

>     </transaction-isolation>

The following sections describe each element in `transaction-isolation`.

### isolation-level

The `transaction-isolation` element defines method-level transaction isolation settings for an EJB. Allowable values include:

- `TRANSACTION_SERIALIZABLE`—Simultaneously executing this transaction multiple times has the same effect as executing the transaction multiple times in a serial fashion.
- `TRANSACTION_READ_COMMITTED`—The transaction can view only committed updates from other transactions
- `TRANSACTION_READ_UNCOMMITTED`—The transaction can view uncommitted updates from other transactions.
- `TRANSACTION_REPEATABLE_READ`—Once the transaction reads a subset of data, repeated reads of the same data return the same values, even if other transactions have subsequently modified the data.

These additional values are supported only for Oracle databases, and only for container-managed persistence (CMP) EJBs:

- `TRANSACTION_READ_COMMITTED_FOR_UPDATE`—Supported only for Oracle databases, and only for container-managed persistence (CMP) EJBs. This value sets the isolation level to `TRANSACTION_READ_COMMITTED`, and for the duration of the transaction, all SQL `SELECT` statements executed in any method are executed with `FOR UPDATE` appended to them. This causes the selected rows to be locked for update. If Oracle cannot lock the rows affected by the query immediately, then it waits until the rows are free. This condition remains in effect until the transaction does a `COMMIT` or `ROLLBACK.`

This isolation level can be used to avoid the error:

`java.sql.SQLException: ORA-08177: can't serialize access for this transaction`

which can occur when using the `TRANSACTION_SERIALIZABLE` isolation level with Oracle databases.

- `TRANSACTION_READ_COMMITTED_FOR_UPDATE_NO_WAIT`—Supported only for Oracle databases, and only for container-managed persistence (CMP) EJBs.

This value sets the isolation level to `TRANSACTION_READ_COMMITTED`, and for the duration of the transaction, all SQL `SELECT` statements executed in any method are executed with `FOR UPDATE NO WAIT` appended to them. This causes the selected rows to be locked for update.

In contrast to the `TRANSACTION_READ_COMMITTED_FOR_UPDATE` setting, `TRANSACTION_READ_COMMITTED_FOR_UPDATE_NO_WAIT` causes the Oracle DBMS to`NOT WAIT` if the required locks cannot be acquired immediately—the affected `SELECT` query will fail and an exception will be thrown by the Container.

Refer to your database documentation for more information support for different isolation levels.

### method

The `method` stanza defines the EJB methods to which an isolation level applies. `method` defines a range of methods using the following elements:

- `description` is an optional element that describes the method.
- `ejb-name` identifies the EJB to which WebLogic Server applies isolation level properties.
- `method-intf` is an optional element that indicates whether the specified method(s) reside in the EJB's home or remote interface. The value of this element must be "Home" or "Remote". If you do not specify `method-intf`, you can apply an isolation to methods in both interfaces.
- `method-name` specifies either the name of an EJB method or an asterisk (*) to designate all EJB methods.
- `method-params` is an optional stanza that lists the Java types of each of the method's parameters. The type of each parameter must be listed in order, using individual `method-param` elements within the `method-params` stanza.

For example, the following method stanza designates all methods in the "AccountBean" EJB:

>     <method>

>     	<ejb-name>AccountBean</ejb-name>

>     	<method-name>*</method-name>

>     </method>

The following stanza designates all methods in the remote interface of "AccountBean:"

>     <method>

>     	<ejb-name>AccountBean</ejb-name>

>     	<method-intf>Remote</method-intf>

>     	<method-name>*</method-name>

>     </method>

## security-role-assignment

The `security-role-assignment` stanza maps application roles in the `ejb-jar.xml` file to the names of security principals available in WebLogic Server.

`security-role-assignment` can contain one or more pairs of the following elements:

- `role-name` is the application role name that the EJB provider placed in the `ejb-jar.xml` deployment file.
- `principal-name` specifies the name of an actual WebLogic Server principal.

# 1.1 weblogic-cmp-jar.xml Deployment Descriptor File Structure

`weblogic-cmp-jar.xml` defines deployment elements for a single entity EJB that uses WebLogic Server RDBMS-based persistence services.

The top-level element of the WebLogic Server 1.1 `weblogic-cmp-jar.xml` consists of a `weblogic-enterprise-bean` stanza:

>     description

>     weblogic-version

>     <weblogic-enterprise-bean>

>        <pool-name>finance_pool</pool-name>

>        <schema-name>FINANCE_APP</schema-name>

>        <table-name>ACCOUNT</table-name>

>        <attribute-map>

>           <object-link>

>              <bean-field>accountID</bean-field>

>              <dbms-column>ACCOUNT_NUMBER</dbms-column>

>           </object-link>

>           <object-link>

>              <bean-field>balance</bean-field>

>              <dbms-column>BALANCE</dbms-column>

>           </object-link>

>        </attribute-map>

>        <finder-list>

>           <finder>

>              <method-name>findBigAccounts</method-name>

>              <method-params>

>                 <<method-param>double</method-param>

>              </method-params>

>           <finder-query><![CDATA[(> balance $0)]]></finder-query>

>           <finder-expression>. . .</finder-expression>

>           </finder>

>        </finder-list>

>     </weblogic-enterprise-bean>

# 1.1 weblogic-cmp-jar.xml Deployment Descriptor Elements

## RDBMS Definition Elements

This section describes the RDBMS definition elements.

### enable-tuned-updates

`enable-tuned-updates` specifies that when `ejbStore` is called that the EJB container automatically determine which container-managed fields have been modified and then writes only those fields back to the database.

### pool-name

`pool-name` specifies name of the WebLogic Server connection pool to use for this EJB's database connectivity. See Using connection pools for more information.

### schema-name

`schema-name` specifies the schema where the source table is located in the database. This element is required only if you want to use a schema that is not the default schema for the user defined in the EJB's connection pool.

Note: This field is case sensitive, although many SQL implementations ignore case.

### table-name

`table-name` specifies the source table in the database. This element is required in all cases.

Note: The user defined in the EJB's connection pool must have read and write privileges to the specified table, though not necessarily schema modification privileges. This field is case sensitive, although many SQL implementations ignore case.

## EJB Field-Mapping Elements

This section describes the EJB field-mapping elements.

### attribute-map

The `attribute-map` stanza links a single field in the EJB instance to a particular column in the database table. The `attribute-map` must have exactly one entry for each field of an EJB that uses WebLogic Server RDBMS-based persistence.

### object-link

Each `attribute-map` entry consists of an `object-link` stanza, which represents a link between a column in the database and a field in the EJB instance.

### bean-field

`bean-field` specifies the field in the EJB instance that should be populated from the database. This element is case sensitive and must precisely match the name of the field in the bean instance.

The field referenced in this tag must also have a `cmp-field` element defined in the `ejb-jar.xml` file for the bean.

### dbms-column

`dbms-column` specifies the database column to which the EJB field is mapped. This tag is case sensitive, although many databases ignore the case.

Note: WebLogic Server does not support quoted RDBMS keywords as entries to `dbms-column`. For example, you cannot create an attribute map for column names such as "create" or "select" if those names are reserved in the underlying datastore.

## Finder Elements

This section describes the finder elements.

### finder-list

The `finder-list` stanza defines the set of all finders that are generated to locate sets of beans.

`finder-list` must contain exactly one entry for each finder method defined in the home interface, except for `findByPrimarykey`. If an entry is not provided for `findByPrimaryKey`, one is generated at compilation time.

Note: If you do provide an entry for `findByPrimaryKey`, WebLogic Server uses that entry without validating it for correctness. In most cases, you should omit an entry for `findByPrimaryKey` and accept the default, generated method.

### finder

The `finder` stanza describes a finder method defined in the home interface. The elements contained in the `finder` stanza enable WebLogic Server to identify which method in the home interface is being described, and to perform required database operations.

### method-name

`method-name` defines the name of the finder method in the home interface. This tag must contain the exact name of the method.

### method-params

The `method-params` stanza defines the list of parameters to the finder method being specified in method-name.

Note: WebLogic Server compares this list against the parameter types for the finder method in the EJB's home interface; the order and type for the parameter list must exactly match the order and type defined in the home interface.

### method-param

`method-param` defines the fully-qualified name for the parameter's type. The type name is evaluated into a `java.lang.Class` object, and the resultant object must precisely match the respective parameter in the EJB's finder method.

You can specify primitive parameters using their primitive names (such as "double" or "int"). If you use a non-primitive data type in a `method-param` element, you must specify a fully qualified name. For example, use `java.sql.Timestamp` rather than `Timestamp`. If you do not use a qualified name, `appc` generates an error message when you compile the deployment unit.

### finder-query

`finder-query` specifies the WebLogic Query Language (WLQL) string that is used to retrieve values from the database for this finder.

Note: Always define the text of the `finder-query` value using the XML `CDATA` attribute. Using `CDATA` ensures that any special characters in the WLQL string do not cause errors when the finder is compiled.

### finder-expression

`finder-expression` specifies a Java language expression to use as a variable in the database query for this finder.

Future versions of the WebLogic Server EJB container will use the EJB QL query language (as required by the EJB 2.0 specification). EJB QL does not provide support for embedded Java expressions. Therefore, to ensure easier upgrades to future EJB containers, create entity EJB finders without embedding Java expressions in WLQL.