bea.com | products | dev2dev | support | askBEA

Download Docs | Site Map | Glossary
Search

Programming WebLogic Enterprise JavaBeans

weblogic-ejb-jar.xml Document Type Definitions

The following sections describe the EJB 1.1 and EJB 2.0 deployment descriptor elements found in the weblogic-ejb-jar.xml file, the weblogic-specific XML document type definitions (DTD) file. Use these definitions to create the WebLogic-specific weblogic-ejb-jar.xml file that is part of your EJB deployment.

- EJB Deployment Descriptors

- DOCTYPE Header Information

- Changed Deployment Elements in WebLogic Server 7.0 EJB

- 2.0 weblogic-ejb-jar.xml Deployment Descriptor File Structure

- 2.0 weblogic-ejb-jar.xml Deployment Descriptor Elements

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

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

EJB Deployment Descriptors

The EJB deployment descriptors contain structural and application assembly information for an enterprise bean. You specify this information by specifying values for the deployment descriptors in three EJB XML DTD files. These files are:

- ejb-jar.xml

- weblogic-ejb-jar.xml

- weblogic-cmp-rdbms-jar.xml

You package these three XML files with the EJB and other classes into a deployable EJB component, usually a JAR file, called ejb.jar.

The ejb-jar.xml file is based on the deployment descriptors found in Sun Microsystems's ejb.jar.xml file. The other two XML files are weblogic-specific files that are based on the deployment descriptors found in weblogic-ejb-jar.xml and weblogic-cmp-rdbms-jar.xml.

DOCTYPE Header Information

When you edit or create XML deployment files, it is critical to include the correct DOCTYPE header for the deployment file. In particular, using an incorrect PUBLIC element within the DOCTYPE header can result in parser errors that may be difficult to diagnose.

WebLogic provides a public location for you to access the correct text for the WebLogic Server-specific DTD file, weblogic-ejb-jar.xml. However, an identical version of this DTD file is embedded in WebLogic Server for internal use. weblogic.ejbc uses this file when the XML parser checks the sequence of the deployment descriptors files.

The correct text for the PUBLIC elements for the WebLogic Server-specific weblogic-ejb-jar.xml file are as follows.

XML File | PUBLIC Element String
--- | ---
weblogic-ejb-jar.xml | '-//BEA Systems, Inc.//DTD WebLogic 7.0.0 EJB//EN' 'http://www.bea.com/servers/wls700/dtd/weblogic-ejb-jar.dtd'
weblogic-ejb-jar.xml | '-//BEA Systems, Inc.//DTD WebLogic 6.0.0 EJB//EN' 'http://www.bea.com/servers/wls600/dtd/weblogic-ejb-jar.dtd'
weblogic-ejb-jar.xml | '-//BEA Systems, Inc.//DTD WebLogic 5.1.0 EJB//EN' 'http://www.bea.com/servers/wls510/dtd/weblogic-ejb-jar.dtd'

The correct text for the PUBLIC elements for the Sun Microsystem-specific ejb-jar.xml file are as follows.

XML File | PUBLIC Element String
--- | ---
ejb-jar.xml | '-//Sun Microsystems, Inc.//DTD Enterprise JavaBeans 2.0//EN' 'http://java.sun.com/dtd/ejb-jar_2_0.dtd'
ejb-jar.xml | '-//Sun Microsystems, Inc.//DTD Enterprise JavaBeans 1.1//EN' 'http://www.java.sun.com/j2ee/dtds/ejb-jar_1_1.dtd'

For example, the entire DOCTYPE header for a weblogic-ejb-jar.xml file is as follows:

>     <!DOCTYPE weblogic-ejb-jar PUBLIC
>     '-//BEA Systems, Inc.//DTD WebLogic 7.0.0 EJB//EN' 'http://www.bea.com/servers/wls700/dtd/weblogic-ejb-jar.dtd'>

XML files with incorrect header information may yield error messages similar to the following, when used with a utility that parses the XML (such as ejbc):

>     SAXException: This document may not have the identifier `identifier_name'

identifier_name generally includes the invalid text from the PUBLIC element.

Document Type Definitions (DTDs) for Validation

The contents and arrangement of elements in your XML files must conform to the Document Type Definition (DTD) for each file you use. WebLogic Server ignores the DTDs embedded within the DOCTYPE header of XML deployment files, and instead uses the DTD locations that were installed along with the server. However, the DOCTYPE header information must include a valid URL syntax in order to avoid parser errors.

Note: Most browsers do not display the contents of files having the .dtd extension. To view the DTD file contents in your browser, save the links as text files and view them with a text editor.

weblogic-ejb-jar.xml

The following links provide the new public DTD locations for the weblogic-ejb-jar.xml deployment files used with the WebLogic Server:

- For weblogic-ejb-jar.xml 7.0 DTD:

  http://www.bea.com/servers/wls700/dtd/weblogic-ejb-jar.dtd contains the DTD used for creating weblogic-ejb-jar.xml, which defines EJB properties used for deployment to WebLogic Server.

- For weblogic-ejb-jar.xml 6.0 DTD:

  http://www.bea.com/servers/wls600/dtd/weblogic-ejb-jar.dtd contains the DTD used for creating weblogic-ejb-jar.xml, which defines EJB properties used for deployment to WebLogic Server.

- For weblogic-ejb-jar.xml 5.1 DTD:

  weblogic-ejb-jar.dtd contains the DTD used for creating weblogic-ejb-jar.xml, which defines EJB properties used for deployment to WebLogic Server. This file is located at http://www.bea.com/servers/wls510/dtd/weblogic-ejb-jar.dtd

ejb-jar.xml

The following links provide the public DTD locations for the ejb-jar.xml deployment files used with WebLogic Server:

- For ejb-jar.xml 2.0 DTD:

  http://www.java.sun.com/dtd/ejb-jar_2_0.dtd contains the DTD for the standard ejb-jar.xml deployment file, required for all EJBs. This DTD is maintained as part of the JavaSoft EJB 2.0 specification; refer to the JavaSoft specification for information about the elements used in ejb-jar.dtd.

- For ejb-jar.xml 1.1 DTD:

  ejb-jar.dtd contains the DTD for the standard ejb-jar.xml deployment file, required for all EJBs. This DTD is maintained as part of the JavaSoft EJB 1.1 specification; refer to the JavaSoft specification for information about the elements used in ejb-jar.dtd.

Note: Refer to the appropriate JavaSoft EJB specification for a description of the ejb-jar.xml deployment descriptors.

Changed Deployment Elements in WebLogic Server 7.0 EJB

These changes were made to weblogic-ejb-jar.xml in WebLogic Server 7.0:

- cache-between-transactions was added.

- entity-cache-name was added.

- entity-cache-ref was added.

- estimated-bean-size was added.

- externally-defined was added.

- global-role was deprecated.

- idempotent-methods

- isolation-level—the new TransactionReadCommittedForUpdateNoWait value was added.

2.0 weblogic-ejb-jar.xml Deployment Descriptor File Structure

The WebLogic Server 7.0 weblogic-ejb-jar.xml deployment descriptor file describes the elements that are unique to WebLogic Server. Although you can use both WebLogic 7.0 and WebLogic 6.0 deployment descriptor elements in the EJB container, the WebLogic Server 7.0 version of weblogic-ejb-jar.xml is different from the version shipped with WebLogic Server Version 6.0.

The top level elements in the WebLogic Server 7.0 weblogic-ejb-jar.xml are as follows:

- description

- weblogic-version

- weblogic-enterprise-bean

  - ejb-name

  - entity-descriptor | stateless-session-descriptor | stateful-session-descriptor | message-driven-descriptor

  - transaction-descriptor

  - reference-descriptor

  - enable-call-by-reference

  - clients-on-same-server

  - jndi-name

- security-role-assignment

- transaction-isolation

2.0 weblogic-ejb-jar.xml Deployment Descriptor Elements

- allow-concurrent-calls

- allow-remove-during-transaction

- cache-type

- client-authentication

- client-cert-authentication

- clients-on-same-server

- confidentiality

- connection-factory-jndi-name

- description

- ejb-local-reference-description

- ejb-name

- ejb-reference-description

- ejb-ref-name

- enable-call-by-reference

- entity-cache

- entity-clustering

- entity-descriptor

- concurrency-strategy

- cache-between-transactions

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

- destination-jndi-name

- finders-load-bean

- home-call-router-class-name

- home-is-clusterable

- home-load-algorithm

- idle-timeout-seconds

- initial-beans-in-free-pool

- is-modified-method-name

- isolation-level

- jndi-name

- max-beans-in-cache

- max-beans-in-free-pool

- message-driven-descriptor

- method

- method-intf

- method-name

- method-param

- method-params

- persistence

- persistence-type

- persistence-use

- persistent-store-dir

- pool

- principal-name

- read-timeout-seconds

- reference-descriptor

- replication-type

- res-ref-name

- resource-description

- role-name

- security-role-assignment

- stateful-session-cache

- stateful-session-clustering

- stateful-session-descriptor

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

- stateless-bean-is-clusterable

- stateless-bean-load-algorithm

- stateless-bean-methods-are-idempotent

- stateless-clustering

- stateless-session-descriptor

- transaction-descriptor

- transaction-isolation

- trans-timeout-seconds

- type-identifier

- type-storage

- type-version

- ejb-local-reference-description

- enable-dynamic-queries

- entity-cache-name

- entity-cache-ref

- externally-defined

- estimated-bean-size

- idempotent-methods

- identity-assertion

- iiop-security-descriptor

- initial-context-factory

- integrity

- invalidation-target

- jms-polling-interval-seconds

- jms-client-id

- local-jndi-name

- persistence

- persistence-use

- principal-name

- provider-url

- relationship-description

- res-env-ref-name

- resource-description

- security-permission

- security-permission-spec

- security-role-assignment

- transport-requirements

- weblogic-ejb-jar

- weblogic-enterprise-bean

allow-concurrent-calls

Range of values: | true | false
Default value: | false
Requirements: | Requires the server to throw a RemoteException when a stateful session bean instance is currently handling a method call and another (concurrent) method call arrives on the server.
Parent elements: | weblogic-enterprise-bean stateful-session-descriptor

Function

The allow-concurrent-calls element specifies whether a stateful session bean instance allows concurrent method calls. By default, allows-concurrent-calls is false. However, when this value is set to true, the EJB container blocks the concurrent method call and allows it to proceed when the previous call has completed.

Example

See stateful-session-descriptor

allow-remove-during-transaction

Range of values: | True | False
Default value: | False
Requirements: |
Parent elements: | weblogic-enterprise-bean stateful-session-descriptor

Function

The allow-remove-during-transaction element specifies that the remove method on a stateful session bean can be invoked within a transaction context.

Stateful session beans implementing the Synchronization interface should not use this tag and then call remove before the transaction ends. If this is done the EJB container will not invoke the synchronization callbacks.

Example

See stateful-session-descriptor

cache-between-transactions

Range of values: | true | false
Default value: | false
Requirements: | Optional element. Valid only for entity EJBs.
Parent elements: | weblogic-enterprise-bean, entity-descriptor, persistence

Function

The cache-between-transactions element, formerly the db-is-shared element, specifies whether the EJB container will cache the persistent data of an entity bean across (between) transactions.

The cache-between-transactions element applies only to entity beans. Specify True to enable the EJB container performs long term caching of the data. Specify False to enable the EJB container to perform short term caching of the data. This is the default setting.

A Read-Only bean ignores the value of the cache-between-transactions element because WebLogic Server always performs long term caching of Read-Only data.

See Caching Between Transactions for more information.

Example

See persistence.

cache-type

Range of values: | NRU | LRU
Default value: | NRU
Requirements: |
Parent elements: | weblogic-enterprise-bean stateful-session-cache

Function

The cache-type element specifies the order in which EJBs are removed from the cache. The values are:

- Least recently used (LRU)

- Not recently used (NRU)

  The minimum cache size for NRU is 8. If max-beans-in-cache is less than 3, WebLogic Server uses a value of 8 for cache-type.

Example

The following example shows the structure of the cache-type element.

>     <stateful-session-cache>

>     <cache-type>NRU</cache-type>

>     </stateful-session-cache>

client-authentication

Range of values: | none | supported | required
Default value: |
Requirements: | n/a
Parent elements: | weblogic-enterprise-bean iiop-security-descriptor

Function

The client-authentication element specifies whether the EJB supports or requires client authentication.

Example

See iiop-security-descriptor.

client-cert-authentication

Range of values: | none | supported | required
Default value: |
Requirements: | n/a
Parent elements: | weblogic-enterprise-bean iiop-security-descriptor transport-requirements

Function

The client-cert-authentication element specifies whether the EJB supports or requires client certificate authentication at the transport level.

Example

See transport-requirements.

clients-on-same-server

Range of values: | true | false
Default value: | false
Requirements: | n/a
Parent elements: | weblogic-enterprise-bean

Function

The clients-on-same-server attribute determines whether WebLogic Server sends JNDI announcements for this EJB when it is deployed. When this attribute is "false" (the default), a WebLogic Server cluster automatically updates its JNDI tree to indicate the location of this EJB on a particular server. This ensures that all clients can access the EJB, even if the client is not collocated on the same server.

You can set clients-on-same-server to "true" when you know that all clients that will access this EJB will do so from the same server on which the bean is deployed. In this case, a WebLogic Server cluster does not send JNDI announcements for this EJB when it is deployed. Because JNDI updates in a cluster utilize multicast traffic, setting clients-on-same-server to "true" can reduce the startup time for very large clusters.

See Optimization for Collocated Objects in Using WebLogic Server Clusters for more information on collocated EJBs.

Example

The following example enables pass-by-value for EJB methods:

>     <weblogic-enterprise-bean>

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

>     	...

>     	<clients-on-same-server>true</clients-on-same-server>

>     </weblogic-enterprise-bean>

concurrency-strategy

Range of values: | Exclusive | Database | ReadOnly | Optimistic
Default value: | Database
Requirements: | Optional element. Valid only for entity EJBs.
Parent elements: | weblogic-enterprise-bean, entity-descriptor, entity-cache

Function

The concurrency-strategy element specifies how the container should manage concurrent access to an entity bean. Set this element to one of four values:

- Exclusive causes WebLogic Server to place an exclusive lock on cached entity EJB instances when the bean is associated with a transaction. Other requests for the EJB instance are block until the transaction completes. This option was the default locking behavior for WebLogic Server versions 3.1 through 5.1.

- Database causes WebLogic Server to defer locking requests for an entity EJB to the underlying datastore. With the Database concurrency strategy, WebLogic Server allocates a separate entity bean instance and allows locking and caching to be handled by the database. This is the default option.

- ReadOnly used for read-only entity beans. Activates a new instance for each transaction so that requests proceed in parallel. WebLogic Server calls ejbLoad() for ReadOnly beans are based on the read-timeout-seconds parameter.

- Optimistic holds no locks in the EJB container or database during a transaction. The EJB container verifies that none of the data updated by a transaction has changed before committing the transaction. If any updated data changed, the EJB container rolls back the transaction.

See EJB Concurrency Strategy for more information on the Exclusive and Database locking behaviors. See Read-Only Multicast Invalidation for more information about read-only entity EJBs.

Example

The following entry identifies the AccountBean class as a read-only entity EJB:

>     <weblogic-enterprise-bean>

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

>     	<entity-descriptor>

>     		<entity-cache>

>     			<concurrency-strategy>ReadOnly</concurrency-strategy>

>     		</entity-cache>

>     	</entity-descriptor>

>     </weblogic-enterprise-bean>

confidentiality

Range of values: | none | supported | required
Default value: | n/a
Requirements: | n/a
Parent elements: | weblogic-enterprise-bean iiop-security-descriptor transport-requirements n

Function

The confidentiality element specifies the transport confidentiality requirements for the EJB. Using the confidentiality element ensures that the data is sent between the client and server in such a way as to prevent other entities from observing the contents.

Example

See transport-requirements.

connection-factory-jndi-name

Range of values: | valid name
Default value: | weblogic.jms.MessageDrivenBeanConnectionFactory in config.xml
Requirements: | Requires the server to throw a RemoteException when a stateful session bean instance is currently handling a method call and another (concurrent) method call arrives on the server.
Parent elements: | weblogic-enterprise-bean message-driven-descriptor

Function

The connection-factory-jndi-name element specifies the JNDI name of the JMS ConnectionFactory that the MessageDriven Bean should look up to create its queues and topics. If this element is not specified, the default is the weblogic.jms.MessageDrivenBeanConnectionFactory in config.xml.

Example

The following example shows the structure of the connection-factory-jndi-name element:

>     <message-driven-descriptor>

>     <connection-factory-jndi-name>weblogic.jms.MessageDrivenBean
>     ConnectionFactory</connection-factory-jndi-name>

>     </message-driven-descriptor>

delay-updates-until-end-of-tx

Range of values: | true | false
Default value: | true
Requirements: | Optional element. Valid only for entity EJBs.
Parent elements: | weblogic-enterprise-bean, entity-descriptor, persistence

Function

Set the delay-updates-until-end-of-tx element to true (the default) to update the persistent store of all beans in a transaction at the completion of the transaction. This setting 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 TRANSACTION_READ_UNCOMMITTED, 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. See ejbLoad() and ejbStore() Behavior for Entity EJBs for more information.

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.

Example

The following example shows a delay-updates-until-end-of-tx stanza.

>     <entity-descriptor>

>     	<persistence>

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

>     	</persistence>

>     </entity-descriptor>

description

Range of values: | n/a
Default value: | n/a
Requirements: | n/a
Parent elements: | weblogic-ejb-jar transaction-isolation method

Function

The description element is used to provide text that describes the parent element.

Example

The following example specifies the description element.

>     <description>Contains a description of parent element</description>

destination-jndi-name

Range of values: | Valid JNDI name
Default value: | n/a
Requirements: | Required in message-driven-descriptor.
Parent elements: | weblogic-enterprise-bean message-driven-descriptor

Function

The destination-jndi-name element specifies the JNDI name used to associate a message-driven bean with an actual JMS Queue or Topic deployed in the WebLogic Server JNDI tree.

Example

See message-driven-descriptor.

ejb-name

Range of values: | Name of an EJB defined in ejb-jar.xml
Default value: | n/a
Requirements: | Required element in method stanza. The name must conform to the lexical rules for an NMTOKEN.
Parent elements: | weblogic-enterprise-bean method

Function

ejb-name specifies the name of an EJB to which WebLogic Server applies isolation level properties. This name is assigned by the ejb-jar file's deployment descriptor. The name must be unique among the names of the enterprise beans in the same ejb.jar file. The enterprise bean code does not depend on the name; therefore the name can be changed during the application-assembly process without breaking the enterprise bean's function. There is no built-in relationship between the ejb-name in the deployment descriptor and the JNDI name that the deployer will assign to the enterprise bean's home.

Example

See method.

ejb-reference-description

Range of values: | n/a (XML stanza)
Default value: | n/a (XML stanza)
Requirements: | Optional element.
Parent elements: | weblogic-enterprise-bean reference-descriptor

Function

The ejb-reference-description element maps the JNDI name in the WebLogic Server of an EJB that is referenced by the bean in the ejb-reference element.

- ejb-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.

Example

The ejb-reference-description stanza is shown here:

>     <ejb-reference-description>

>     	<ejb-ref-name>AdminBean</ejb-ref-name>

>     		<jndi-name>payroll.AdminBean</jndi-name>

>     	</ejb-reference-description>

ejb-ref-name

Range of values: | n/a
Default value: | n/a
Requirements: | Optional element.
Parent elements: | weblogic-enterprise-bean reference-description ejb-reference-description

Function

The ejb-ref-name element specifies a resource reference name. This element is the reference that the EJB provider places within the ejb-jar.xml deployment file.

Example

The ejb-ref-name stanza is shown here:

>     <reference-descriptor>

>     	<ejb-reference-description>

>     		<ejb-ref-name>AdminBean</ejb-ref-name>

>     		<jndi-name>payroll.AdminBean</jndi-name>

>     	</ejb-reference-description>

>     </reference-descriptor>

ejb-local-reference-description

Range of values: | n/a (XML stanza)
Default value: | n/a (XML stanza)
Requirements: | Optional element.
Parent elements: | weblogic-enterprise-bean reference-descriptor

Function

The ejb-local-reference-description element maps the JNDI name of an EJB in the WebLogic Server that is referenced by the bean in the ejb-local-ref element.

Example

The following example shows the ejb-local-reference-description element.

>     <ejb-local-reference-description>

>     	<ejb-ref-name>AdminBean</ejb-ref-name>

>     	<jndi-name>payroll.AdminBean</jndi-name>

>     </ejb-local-reference-description>

enable-call-by-reference

Range of values: | true | false
Default value: | true
Requirements: | Optional element.
Parent elements: | weblogic-enterprise-bean reference-descriptor ejb-reference-description

Function

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

If you set enable-call-by-reference to False, parameters to the 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).

Example

The following example enables pass-by-value for EJB methods:

>     <weblogic-enterprise-bean>

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

>     	...

>     	<enable-call-by-reference>false</enable-call-by-reference>

>     </weblogic-enterprise-bean>

enable-dynamic-queries

Range of values: | true | false
Default value: | true
Requirements: | Optional element.
Parent elements: | weblogic-enterprise-bean entity-descriptor

Function

The optional enable-dynamic-queries element must be set to true to enable dynamic queries. Dynamic queries are only available for use with EJB 2.0 CMP beans.

Example

The following example enables dynamic queries:

>     <enable-dynamic-queries>True</enable-dynamic-queries>

entity-cache

Range of values: | n/a (XML stanza)
Default value: | n/a (XML stanza)
Requirements: | The entity-cache stanza is optional, and is valid only for entity EJBs.
Parent elements: | weblogic-enterprise-bean, entity-descriptor

Function

The entity-cache element defines the following options used to cache entity EJB instances within WebLogic Server:

- max-beans-in-cache

- idle-timeout-seconds

- read-timeout-seconds

- concurrency-strategy

See EJB Life Cycle for a general discussion of the caching services available in WebLogic Server.

Example

The entity-cache stanza is shown here:

>     <entity-descriptor>

>     	<entity-cache>

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

>     		<idle-timeout-seconds>...</idle-timeout-seconds>

>     		<read-timeout-seconds>...<read-timeout-seconds>

>     		<concurrency-strategy>...</concurrency-strategy>

>     	</entity-cache>

>     	<persistence>...</persistence>

>     	<entity-clustering>...</entity-clustering>

>     </entity-descriptor>

entity-cache-name

Range of values: | n/a (XML stanza)
Default value: | n/a (XML stanza)
Requirements: | The value you specify for entity-cache-name must match the name assigned to an application level entity cache in the weblogic-application.xml file.
Parent elements: | weblogic-enterprise-bean, entity-descriptor entity-cache-ref

Function

The entity-cache-name element refers to an application level entity cache that the entity bean uses. An application level cache is a cache that may be shared by multiple entity beans in the same application.

For more information about the weblogic-application.xml file, see the application deployment descriptors.

Example

See entity-cache-ref.

entity-cache-ref

Range of values: | n/a (XML stanza)
Default value: | n/a (XML stanza)
Requirements: | The entity-cache-name element in the entity-cache-ref stanza must contain the name of the application level cache.
Parent elements: | weblogic-enterprise-bean, entity-descriptor

Function

The entity-cache-ref element refers to an application level entity cache which can cache instances of multiple entity beans that are part of the same application. Application level entity caches are declared in the weblogic-application.xml file.

Use the concurrency-strategyto define the type of concurrency you want the bean to use. The concurrency-strategy must be compatible with the application level cache's caching strategy. For example, an Exclusive cache only supports banes with a concurrency-strategy of Exclusive. While a MultiVersion cache supports the Database, ReadOnly, and Optimistic concurrency strategies.

Example

The entity-cache-ref stanza is shown here:

>     <entity-cache-ref>
>     	<entity-cache-name>AllEntityCache</entity-cache-name>
>     	<concurrency-strategy>ReadOnly</concurrency-strategy>
>     	<estimated-bean-size>20</estimated-bean-size>
>     </entity-cache-ref>

entity-clustering

Range of values: | n/a (XML stanza)
Default value: | n/a (XML stanza)
Requirements: | Optional element. Valid only for entity EJBs in a cluster.
Parent elements: | weblogic-enterprise-bean, entity-descriptor

Function

The entity-clustering element uses the following options to specify how an entity bean will be replicated in a WebLogic cluster:

- home-is-clusterable

- home-load-algorithm

- home call-router-class-name

Example

The following excerpt shows the structure of a entity-clustering stanza:

>     <entity-clustering>

>     	<home-is-clusterable>true</home-is-clusterable>

>     	<home-load-algorithm>random</home-load-algorithm>

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

>     </entity-clustering>

entity-descriptor

Range of values: | n/a (XML stanza)
Default value: | n/a (XML stanza)
Requirements: | One entity-descriptor stanza is required for each entity EJB in the .jar.
Parent elements: | weblogic-enterprise-bean

Function

The entity-descriptor element specifies the following deployment parameters that are applicable to an entity bean:

- pool

- entity-cache

- persistence

- entity-clustering

Example

The following example shows the structure of the entity-descriptor stanza:

>     <entity-descriptor>

>     	<entity-cache>...</entity-cache>

>     	<persistence>...</persistence>

>     	<entity-clustering>...</entity-clustering>

>     </entity-descriptor>

estimated-bean-size

Range of values: | n/a (XML stanza)
Default value: | n/a (XML stanza)
Requirements: | n/a
Parent elements: | weblogic-enterprise-bean entity-descriptor

Function

The estimated-bean-size- element specifies the estimated average size of the instances of an entity bean in bytes. This is the average number of byte of memory that is consumed by each instance.

Use the estimated-bean-size element when the application level cache you use to cache beans is also specified in terms of bytes and megabytes.

Although you may not know the exact number of bytes consumed by the entity bean instances, specifying a size allows you to give some relative weight to the beans that share a cache. at one time.

For example, suppose bean A ad bean B share a cache, called AB-cache, that has a size of 1000 bytes and the size of A is 10 bytes and the size of B is 20 bytes, then the cache can hold at most 100 instances of A and 50 instances of B. If 100 instance s of A are cached, this implies that 0 instances of B are cached.

Example

See entity-cache-ref.

externally-defined

Range of values: | True | False
Default value: |
Requirements: | n/a
Parent elements: | weblogic-enterprise-bean security-role-assignment

Function

The externally-defined element indicates that a particular security role is defined externally in a security realm, outside of the deployment descriptor. Because the security role and it's principal-name mapping is defined elsewhere, principal-names are not to be specified in the deployment descriptor. This tag is used as an indicative placeholder instead of a set of principal-name elements.

finders-load-bean

Range of values: | true | false
Default value: | true
Requirements: | Optional element. Valid only for CMP entity EJBs.
Parent elements: | weblogic-enterprise-bean, entity-descriptor, persistence

Function

The finders-load-bean element determines whether WebLogic Server loads the EJB into the cache after a call to a finder method returns a reference to the bean. If you set this element to true, WebLogic Server immediately loads the bean into the cache if a reference to a bean is returned by the finder. If you set this element to false, WebLogic Server does not automatically load the bean into the cache until the first method invocation; this behavior is consistent with the EJB 1.1 specification.

Example

The following entry specifies that EJBs are loaded into the WebLogic Server cache automatically when a finder method returns a reference to the bean:

>     <entity-descriptor>

>     	<persistence>

>     		<finders-load-bean>true</finders-load-bean>

>     	</persistence>

>     </entity-descriptor>

global-role

Range of values: | True | False
Default value: | True
Requirements: |
Parent elements: | weblogic-enterprise-bean security-role-assignment

Function

The global-role element indicates that a particular security role is defined "globally" in a security realm. Because the security role and its principal-name mapping is defined elsewhere, principal-names are not to be specified in the deployment descriptor. This tag is used as an indicative placeholder instead of a set of principal-name elements.

home-call-router-class-name

Range of values: | Valid router class name
Default value: | null
Requirements: | Optional element. Valid only for entity EJBs, stateful session EJBs, and stateless session EJBs in a cluster.
Parent elements: | weblogic-enterprise-bean, entity-descriptor, entity-clustering and weblogic-enterprise-bean stateful-session-descriptor stateful-session-clustering

Function

home-call-router-class-name specifies the name of a custom class to use for routing bean method calls. This class must implement weblogic.rmi.cluster.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.

Example

See entity-clustering and stateful-session-clustering.

home-is-clusterable

Range of values: | true | false
Default value: | true
Requirements: | Optional element. Valid for entity EJBs, stateless session EJBs, and stateful session EJBs in a cluster.
Parent elements: | weblogic-enterprise-bean, entity-descriptor, entity-clustering and weblogic-enterprise-bean stateful-session-descriptor stateful-session-clustering and weblogic-enterprise-bean stateless-session-descriptor stateless-clustering

Function

Use home-is-clusterable to specify whether the home interface of an entity, stateless session, or stateful session bean is clustered.

When home-is-clusterable is true for an EJB deployed to a cluster, each server instance binds the bean's home interface to its cluster JNDI tree under the same name. When a client requests the bean's home from the cluster, the server instance that does the look-up returns a EJBHome stub that has a reference to the home on each server.

When the client issues a create() or find() call, the stub routes selects a server from the replica list in accordance with the load balancing algorithm, and routes the call to the home interface on that server. The selected home interface receives the call, and creates a bean instance on that server instance and executes the call, creating an instance of the bean.

Example

See entity-clustering.

home-load-algorithm

Range of values: | round-robin | random | weight-based
Default value: | Value of weblogic.cluster.defaultLoadAlgorithm
Requirements: | Optional element. Valid only for entity EJBs and stateful session EJBs in a cluster.
Parent elements: | weblogic-enterprise-bean, entity-descriptor, entity-clustering and weblogic-enterprise-bean stateful-session-descriptor stateful-session-clustering

Function

home-load-algorithm specifies the algorithm to use for load balancing between replicas of the EJB home. If this element is not defined, WebLogic Server uses the algorithm specified by the server element, 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.

Example

See entity-clustering and stateful-session-clustering.

idempotent-method

Range of values: | n/a
Default value: | n/a
Requirements: | Clustering must be enabled for the EJB.
Parent elements: | weblogic-enterprise-bean

s

Function

The idempotent-methods element defines list of methods which are written in such a way 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 compiled on the failed server. When you enable idempotent-methods for a method, the EJB stub can automatically recover from any failure as long as it can reach another server hosting the EJB.

To enable clustering, see entity-clustering, stateful-session-clustering, and stateless-clustering.

The methods on stateless session bean homes and read-only entity beans are automatically set to be idempotent. It is not necessary to explicitly specify them as idempotent.

Example

The method stanza can contain the elements shown here:

>     <idempotent-method>
>     	<method>
>     		<description>...</description>
>     		<ejb-name>...</ejb-name>
>     		<method-intf>...</method-intf>
>     		<method-name>...</method-name>
>     		<method-params>...</method-params>
>     	</method>
>     </idempotent-method>

identity-assertion

Range of values: | none | supported | required
Default value: |
Requirements: | n/a
Parent elements: | weblogic-enterprise-bean iiop-security-descriptor

Function

The identity-assertion element specifies whether the EJB supports or requires identity assertion.

Example

See iiop-security-descriptor.

idle-timeout-seconds

Range of values: | 1 to maxSeconds, where maxSeconds is the maximum value of an int.
Default value: | 600
Requirements: | Optional element
Parent elements: | weblogic-enterprise-bean, entity-descriptor, entity-cache and weblogic-enterprise-bean, stateful-session-descriptor, stateful-session-cache

Function

idle-timeout-seconds defines the maximum length of time a stateful EJB should remain in the cache. After this time has elapsed, WebLogic Server removes the bean instance if the number of beans in cache approaches the limit of max-beans-in-cache. The removed bean instances are passivated. See EJB Life Cycle for more information.

Note: Although idle-timeout-seconds appears in the entity-cache stanza, WebLogic Server 7. 0 SP01, SP02, SP03, and SP04 do not use its value in managing the lifecycle of entity EJBs—in those service pecks, idle-timeout-seconds has no effect on when entity beans are removed from cache.

Example

The following entry indicates that the stateful session EJB, AccountBean, should become eligible for removal if max-beans-in-cache is reached and the bean has been in cache for 20 minutes:

>     <weblogic-enterprise-bean>
>        <ejb-name>AccountBean</ejb-name>
>        <stateful-session-descriptor>
>           <stateful_session-cache>
>              <max-beans-in-cache>200</max-beans-in-cache>
>              <idle-timeout-seconds>1200</idle-timeout-seconds>
>           </stateful-session-cache>
>        </stateful-session-descriptor>
>     </weblogic-enterprise-bean>

iiop-security-descriptor

Range of values: | n/a
Default value: | n/a
Requirements: | n/a
Parent elements: | weblogic-enterprise-bean

Function

The iiop-security-descriptor element specifies security configuration parameters at the bean-level. These parameters determine the IIOP security information contained in the IOR.

Example

The iiop-security-descriptor stanza can contain the elements shown here

>     <iiop-security-descriptor>

>     	<transport-requirements>...</transport-requirements>

>     	<client-authentication>supported<client-authentication>

>     	<identity-assertion>supported</identity-assertion>

>     </iiop-security-descriptor>

initial-beans-in-free-pool

Range of values: | 0 to maxBeans
Default value: | 0
Requirements: | Optional element. Valid for stateless session, entity, and message-driven EJBs.
Parent elements: | weblogic-enterprise-bean, stateless-session-descriptor, message-bean-descriptor, entity-descriptor pool

Function

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

Example

See pool.

initial-context-factory

Range of values: | true | false
Default value: | weblogic.jndi.WLInitialContextFactory
Requirements: | Requires the server to throw a RemoteException when a stateful session bean instance is currently handling a method call and another (concurrent) method call arrives on the server.
Parent elements: | weblogic-enterprise-bean message-driven-descriptor

Function

The initial-context-factory element specifies the initial contextFactory that the container will use to create its connection factories. If initial-context-factory is not specified, the default will be weblogic.jndi.WLInitialContextFactory.

Example

The following example specifies the initial-context-factory element.

>     <message-driven-descriptor>

>     <initial-context-factory>weblogic.jndi.WLInitialContextFactory
>     </initial-context-factory>

>     </message-driven-descriptor>

integrity

Range of values: | none | supported | required
Default value: |
Requirements: | n/a.
Parent elements: | weblogic-enterprise-bean iiop-security-descriptor transport-requirements

Function

The integrity element specifies the transport integrity requirements for he EJB. Using the integrity element ensures that the data is sent between the client and server in such a way that it cannot be changed in transit.

Example

See transport-requirements.

invalidation-target

Range of values: |
Default value: |
Requirements: | The target ejb-name must be a Read-Only entity EJB and this element can only be specified for an EJB 2.0 container-managed persistence entity EJB.
Parent elements: | weblogic-enterprise-bean entity-descriptor

Function

The invalidation-target element specifies a Read-Only entity EJB that should be invalidated when this container-managed persistence entity EJB has been modified.

Example

The following entry specifies that the EJB named StockReaderEJB should be invalidated when the EJB has been modified.

>     <invalidation-target>

>     	<ejb-name>StockReaderEJB</ejb-name>

>     </invalidation-target>

is-modified-method-name

Range of values: | Valid entity EJB method name
Default value: | None
Requirements: | Optional element. Valid only for entity EJBs.
Parent elements: | weblogic-enterprise-bean, entity-descriptor, persistence

Function

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 for EJB 1.1-compliant beans, and for beans that use bean-managed persistence. However, any errors in the method's return value can cause data inconsistency problems. See Using is-modified-method-name to Limit Calls to ejbStore() (EJB 1.1 Only) for more information.

Note: isModified() is no longer required for 2.0 CMP entity EJBs based on the EJB 2.0 specification However, it still applies to BMP and 1.1 CMP EJBs. When you deploy EJB 2.0 entity beans with container-managed persistence, WebLogic Server automatically detects which EJB fields have been modified, and writes only those fields to the underlying datastore.

Example

The following entry specifies that the EJB method named semidivine will notify WebLogic Server when the EJB has been modified:

>     <entity-descriptor>

>     	<persistence>

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

>     	</persistence>

>     </entity-descriptor>

isolation-level

Range of values: | TransactionSerializable | TransactionReadCommitted | TransactionReadUncommitted | TransactionRepeatableRead | TransactionReadCommittedForUpdate | TransactionReadCommittedForUpdateNoWait
Default value: | default setting of the underlying database
Requirements: | Optional element.
Parent elements: | weblogic-ejb-jar transaction-isolation

Function

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 addition 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, for container-managed persistence (CMP) beans only. 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, for container-managed persistence (CMP) beans only.

  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.

  See Setting Container-Managed Transaction Isolation Levels for background information on the Oracle-specific isolation-level values.

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

Example

See transaction-isolation.

jms-polling-interval-seconds

Range of values: | n/a
Default value: | 10 seconds
Requirements: | n/a
Parent elements: | weblogic-enterprise-bean

Function

The jms-polling-interval-seconds specifies the number of seconds between each attempt to reconnect to the JMS destination. Each message-driven bean listens on an associated JMS destination. If the JMS destination is located on another WebLogic Server instance or a foreign JMS provider, then the JMS destination may become unreachable. In this case, the EJB container automatically attempts to reconnect to the JMS Server. Once the JMS Server is up again, the message-driven bean can again receive messages.

Example

The following entry specifies the jms polling intervals for message-driven beans:

>     <jms-polling-interval-seconds>5</jms-polling-interval seconds>

jms-client-id

Range of values: | n/a
Default value: | The default client identifier is the ejb-name for this EJB.
Requirements: | The jms-client-id is necessary for durable subscriptions to JMS topics.
Parent elements: | weblogic-enterprise-bean

Function

The jms-client-id specifies an associated id for the JMS consumers. A message-driven bean with a durable subscription needs an associated client id. If you use a separate connection factory, you can set the client id on the connection factory. In this case, the message-driven bean uses this client id.

If the associated connection factory does not have a client id or if you use the default connection factory, then the message-driven bean used the jms-client-id value as its client id.

Example

The following entry specifies an associated id for JMS consumers:

>     <jms-client-id>MyClientID</jms-client-id>

jndi-name

Range of values: | Valid JNDI name
Default value: | n/a
Requirements: | Required in resource-description and ejb-reference-description.
Parent elements: | weblogic-enterprise-bean and weblogic-enterprise-bean reference-descriptor resource-description and weblogic-enterprise-bean reference-descriptor ejb-reference-description

Function

jndi-name specifies the JNDI name of an actual EJB, resource, or reference available in WebLogic Server.

Example

See resource-description and ejb-reference-description.

local-jndi-name

Range of values: | Valid JNDI name
Default value: | n/a
Requirements: | Required if the bean has a local home.
Parent elements: | weblogic-enterprise-bean

Function

The local-jndi-name element specifies a jndi-name for a bean's local home. If a bean has both a remote and a local home, then it must have two JNDI names; one for each home.

Example

The following example shows the specifies the local-jndi-name element.

>     <local-jndi-name>weblogic.jndi.WLInitialContext
>     </local-jndi-name>

max-beans-in-cache

Range of values: | 1 to maxBeans
Default value: | 1000
Requirements: | Optional element
Parent elements: | weblogic-enterprise-bean, entity-descriptor, entity-cache and weblogic-enterprise-bean stateful-session-descriptor stateful-session-cache

Function

The max-beans-in-cache 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 recently been used by a client. max-beans-in-cache also affects when EJBs are removed from the WebLogic Server cache, as described in EJB Concurrency Strategy.

Example

The following entry enables WebLogic Server to cache a maximum of 200 instances of the AccountBean class:

>     <weblogic-enterprise-bean>

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

>     	<entity-descriptor>

>     		<entity-cache>

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

>     		</entity-cache>

>     	</entity-descriptor>

>     </weblogic-enterprise-bean>

max-beans-in-free-pool

Range of values: | 0 to maxBeans
Default value: | 1000
Requirements: | Optional element.
Parent elements: | weblogic-enterprise-bean, stateless-session-descriptor, pool weblogic-enterprise-bean, message-bean-descriptor, pool weblogic-enterprise-bean, entity-descriptor, pool

Function

WebLogic Server maintains a free pool of EJBs for every entity, stateless session, and message-driven bean class. The max-beans-in-free-pool element defines the size of this pool. See Stateless Session EJB Life Cycle and Differences Between Message-Driven Beans and Stateless Session EJBs for more information.

Example

See pool.

message-driven-descriptor

Range of values: | n/a (XML stanza)
Default value: | n/a (XML stanza)
Requirements: |
Parent elements: | weblogic-enterprise-bean

Function

The message-driven-descriptor element associates a message-driven bean with a JMS destination in WebLogic Server. This element specifies the following deployment parameters:

- pool

- destination-jndi-name

- initial-context-factory

- provider-url

- connection-factory-jndi-name

Example

The following example shows the structure of the message-driven-descriptor stanza:

>     <message-driven-descriptor>

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

>     </message-driven-descriptor>

method

Range of values: | n/a (XML stanza)
Default value: | n/a (XML stanza)
Requirements: | Optional element. You can specify more than one method stanza to configure multiple EJB methods.
Parent elements: | weblogic-ejb-jar transaction-isolation

Function

The method element defines a method or set of methods for an enterprise bean's home or remote interface.

Example

The method stanza can contain the elements shown here:

>     <method>

>     	<description>...</description>

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

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

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

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

>     </method>

method-intf

Range of values: | Home | Remote | Local | Localhome
Default value: | n/a
Requirements: | Optional element.
Parent elements: | weblogic-ejb-jar transaction-isolation method

Function

method-intf specifies the EJB interface to which WebLogic Server applies isolation level properties, if the method has the same signature in multiple interfaces.

Example

See method.

method-name

Range of values: | Name of an EJB defined in ejb-jar.xml | *
Default value: | n/a
Requirements: | Required element in method stanza.
Parent elements: | weblogic-ejb-jar transaction-isolation method

Function

method-name specifies the name of an individual EJB method to which WebLogic Server applies isolation level properties. Use the asterisk (*) to specify all methods in the EJB's home and remote interfaces.

If you specify a method-name, the method must be available in the specified ejb-name.

Example

See method.

method-param

Range of values: | Fully qualified Java type of a method parameter
Default value: | n/a
Requirements: | Required element in method-params.
Parent elements: | weblogic-ejb-jar transaction-isolation method method-params

Function

The method-param element specifies the fully qualified Java type name of a method parameter.

Example

See method-params.

method-params

Range of values: | n/a (XML stanza)
Default value: | n/a (XML stanza)
Requirements: | Optional stanza.
Parent elements: | weblogic-ejb-jar transaction-isolation method

Function

The method-params stanza contains one or more elements that define the Java type name of each of the method's parameters.

Example

The method-params stanza contains one or more method-param elements, as shown here:

>     <method-params>

>     	<method-param>java.lang.String</method-param>

>     	...

>     </method-params>

persistence

Range of values: | n/a (XML stanza)
Default value: | n/a (XML stanza)
Requirements: | Required only for entity EJBs that use container-managed persistence services.
Parent elements: | weblogic-enterprise-bean, entity-descriptor

Function

The persistence element defines the following options that determine the persistence type, transaction commit behavior, and ejbLoad() and ejbStore() behavior for entity EJBs in WebLogic Server:

- is-modified-method-name

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

- finders-load-bean

- db-is-shared

- persistence-use

Example

The following example specifies the persistence element.

>     <entity-descriptor>
>     	<persistence>
>     		<is-modified-method-name>...</is-modified-
>     		method-name>
>     		<delay-updates-until-end-of-tx>
>     		</delay-updates-until-end-of-tx>
>     		<finders-load-beand>...</finders-load-bean>
>     		<db-is-shared>false</db-is-shared>
>     		<persistence-use>...</persistence-use>

>     	</persistence>
>     </entity-descriptor>

persistence-use

Range of values: | n/a (XML stanza)
Default value: | n/a (XML stanza)
Requirements: | Required only for entity EJBs that use container-managed persistence services.
Parent elements: | weblogic-enterprise-bean, entity-descriptor, persistence

Function

The persistence-use element stores an identifier of the persistence type to be used for this particular bean.

Example

>     The following excerpt shows a sample persistence-use stanza:

>     <persistence-use>
>     	<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-use>

persistent-store-dir

Default value: | pstore
Requirements: | Optional element.
Parent elements: | weblogic-enterprise-bean stateful-session-descriptor

Function

Specifies a file system directory where WebLogic Server stores the state of passivated stateful session bean instances. For more information, see Specifying the Persistent Store Directory for Passivated Beans.

Example

<stateful-session-descriptor>
<stateful-session-cache>...</stateful-session-cache>
<allow-concurrent-calls>...</allow-concurrent-calls>
<persistent-store-dir>MyPersistenceDirr</persistent-store-dir>
<stateful-session-clustering>...</stateful-session-clustering>
<allow-remove-during-transaction>
</stateful-session-descriptor>

pool

Range of values: | n/a (XML stanza)
Default value: | n/a (XML stanza)
Requirements: | Optional element.
Parent elements: | weblogic-enterprise-bean stateless-session-descriptor, message-bean-descriptor, entity-descriptor

Function

The pool element configures the behavior of the WebLogic Server free pool for EJBs.

Example

The pool stanza can contain the elements shown here:

>     <stateless-session-descriptor>
>        <pool>
>          <max-beans-in-free-pool>500</max-beans-in-free-pool>
>          <initial-beans-in-free-pool>250</initial-beans-in-free-pool>
>        </pool>
>     </stateless-session-descriptor>

principal-name

Range of values: | valid WebLogic Server principal name
Default value: | n/a
Requirements: | At least one principal-name is required in the security-role-assignment stanza. You may define more than one principal-name for each role-name.
Parent elements: | weblogic-enterprise-bean security-role-assignment

Function

principal-name specifies the name of an actual WebLogic Server principal to apply to the specified role-name.

Example

See security-role-assignment.

provider-url

Range of values: | valid name
Default value: | n/a
Requirements: | Used in conjunction with initial-context-factory and connection-factory-jndi-name.
Parent elements: | weblogic-enterprise-bean message-driven-descriptor

Function

The provider-url element specifies the URL provider to be used by the InitialContext. Typically, this is the host:port and used in conjunction with initial-context-factory and connection-factory-jndi-name.

Example

The following example specifies the provider-url element.

>     <message-driven-descriptor>

>     <provider-url>WeblogicURL:Port</provider-url>

>     </message-driven-descriptor>

read-timeout-seconds

Range of values: | 0 to maxSeconds, where maxSeconds is the maximum value of an int.
Default value: | 600
Requirements: | Optional element. Valid only for entity EJBs.
Parent elements: | weblogic-enterprise-bean, entity-descriptor, entity-cache

Function

The read-timeout-seconds element specifies the number of seconds between ejbLoad() calls on a Read-Only entity bean. A setting of 0 causes WebLogic Server to calls ejbLoad() only when the bean is brought into the cache.

Example

The following entry causes WebLogic Server to call ejbLoad() for instances of the AccountBean class only when the instance is first brought into the cache:

>     <weblogic-enterprise-bean>
>         <ejb-name>AccountBean</ejb-name>
>             <entity-descriptor>
>                 <entity-cache>
>                     <read-timeout-seconds>0</read-timeout-seconds>
>                 </entity-cache>
>             </entity-descriptor>
>     </weblogic-enterprise-bean>

reference-descriptor

Range of values: | n/a (XML stanza)
Default value: | n/a (XML stanza)
Requirements: | Optional element.
Parent elements: | weblogic-enterprise-bean

Function

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

Example

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>

>     		...

>     	</resource-description>

>     	<ejb-reference-description>

>     		...

>     	</ejb-reference-description>

>     </reference-descriptor>

relationship-description

This element is no longer supported in WebLogic Server.

replication-type

Range of values: | InMemory | None
Default value: | None
Requirements: | Optional element. Valid only for stateful session EJBs in a cluster.
Parent elements: | weblogic-enterprise-bean stateful-session-descriptor stateful-session-clustering

Function

The replication-type element determines whether WebLogic Server replicates the state of stateful session EJBs across WebLogic Server instances in a cluster. If you select InMemory, the state of the EJB is replicated. If you select None, the state is not replicated.

See In-Memory Replication for Stateful Session EJBs for more information.

Example

See stateful-session-clustering.

res-env-ref-name

Range of values: | A valid resource environment reference name from the ejb-jar.xml file
Default value: | n/a
Requirements: | n/a
Parent elements: | weblogic-enterprise-bean reference-descriptor resource-env-description

Function

The res-env-ref-name element specifies the name of a resource environment reference.

Example

See resource-description.

res-ref-name

Range of values: | A valid resource reference name from the ejb-jar.xml file
Default value: | n/a
Requirements: | Required element if the EJB specifies resource references in ejb-jar.xml
Parent elements: | weblogic-enterprise-bean reference-descriptor resource-description

Function

The res-ref-name element specifies the name of a resourcefactory reference. This is the reference that the EJB provider places within the ejb-jar.xml deployment file.

Example

See resource-description.

resource-description

Range of values: | n/a (XML stanza)
Default value: | n/a (XML stanza)
Requirements: | Optional element.
Parent elements: | weblogic-enterprise-bean reference-descriptor

Function

The resource-description element maps a resource reference defined in ejb-jar.xml to the JNDI name of an actual resource available in WebLogic Server.

Example

The resource-description stanza can contain additional elements as shown here:

>     <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-env-description

Range of values: | n/a (XML stanza)
Default value: | n/a (XML stanza)
Requirements: | Optional element.
Parent elements: | weblogic-enterprise-bean reference-descriptor

Function

The resource-env-description element maps a resource environment reference defined in ejb-jar.xml to the JNDI name of an actual resource available in WebLogic Server.

Example

The resource-env-description stanza can contain additional elements as shown here:

>     <reference-descriptor>
>     	<resource-env-description>
>     		<res-env-ref-name>. . .</res-env-ref-name>
>     		<jndi-name>...</jndi-name>
>     	<reference-env-description>
>     </reference-descriptor>

role-name

Range of values: | An EJB role name defined in ejb-jar.xml
Default value: | n/a
Requirements: | Required element in security-role-assignment.
Parent elements: | weblogic-enterprise-bean security-role-assignment

Function

The role-name element identifies an application role name that the EJB provider placed in the ejb-jar.xml deployment file. Subsequent principal-name elements in the stanza map WebLogic Server principals to the specified role-name.

Example

See security-role-assignment.

security-permission

Range of values: | n/a (XML stanza)
Default value: | n/a (XML stanza)
Requirements: | .
Parent elements: | n/a

Function

The security-permission element specifies a security permission that is associated with a J2EE Sandbox.

For more information, see Sun's implementation of the security permission specification:

http://java.sun.com/j2se/1.3/docs/guide/security/PolicyFiles.html#FileSyntax

Example

The security-permission stanza can contain one or more of the following elements:

>     <security-permission> </security-permission>

security-permission-spec

Range of values: | n/a (XML stanza)
Default value: | n/a (XML stanza)
Requirements: | n/a
Parent elements: | security-permission

Function

The security-permission-spec element specifies a security permission associated with a J2EE sandbox.

For more information, see Sun's implementation of the security permission specification:

http://java.sun.com/j2se/1.3/docs/guide/security/PolicyFiles.html#FileSyntax

Example

To grant the "read" permission to "java.vm.version" and prevent it from being overwritten:

1. Set the security-permission-spec as shown below:

   <security-permission>
   <description>Optional explanation goes here</description>
   <security-permission-spec> grant { permission java.util.PropertyPermission "java.vm.version", "read"; }; </security-permission-spec>
   </security-permission>

2. Modify the startWeblogic script to start the server using this option:

   JAVA_OPTIONS=-Djava.security.manager

3. Create a directory named lib in your domain directory.

4. Add this line to the %WL_HOME%\server\lib\weblogic.policy file:

   add grant codeBase "file:/<Your user_projects dir>/YourDomain/lib/-" { permission java.security.AllPermission; };

   This is necessary because the EJB stub's classpath is lib.

security-role-assignment

Range of values: | n/a (XML stanza)
Default value: | n/a (XML stanza)
Requirements: | Required element if ejb-jar.xml defines application roles.
Parent elements: | n/a

Function

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

Example

The security-role-assignment stanza can contain one or more of the following elements:

>     <security-role-assignment>
>     	<role-name>PayrollAdmin</role-name>
>     	<principal-name>Tanya</principal-name>
>     	<principal-name>system</principal-name>
>     	...
>     </security-role-assignment>

session-timeout-seconds

Range of values: | n/a (XML stanza)
Default value: | n/a (XML stanza)
Requirements: | The session-timeout-seconds stanza is valid only for stateful session EJBs.
Parent elements: | weblogic-enterprise-bean, stateful-session-descriptor stateful-session-cache

Function

The session-timeout-seconds element specifies how long the EJB container waits before removing a passivated stateful session EJB from disk.

The idle-timeout-seconds element determines how long the EJB container waits before passivating stateful session beans, that is, removing them from cache and writing them to disk.

In past releases, the EJB container also used idle-timeout-seconds to determine how long to wait before removing passivated EJBs from the disk. With the addition of session-timeout-seconds, you can specify how long stateful session beans stay idle in the cache and how long they stay idle on disk using two different elements.

Example

The following example shows how to specify the session-timeout-seconds element

>     <session-timeout-seconds>3600</session-timeout-seconds>

stateful-session-cache

Range of values: | n/a (XML stanza)
Default value: | n/a (XML stanza)
Requirements: | The stateful-session-cache stanza is optional, and is valid only for stateful session EJBs.
Parent elements: | weblogic-enterprise-bean, stateful-session-descriptor

Function

The stateful-session-cache element defines the following options used to cache stateful session EJB instances within WebLogic Server.

- max-beans-in-cache

- idle-timeout-seconds

- cache-type

See EJB Life Cycle for a general discussion of the caching services available in WebLogic Server.

Example

The following example shows how to specify the stateful-session-cache element

>     <stateful-session-cache>

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

>     	<idle-timeout-seconds>...</idle-timeout-seconds>

>     	<cache-type>...</cache-type>

>     </stateful-session-cache>

stateful-session-clustering

Range of values: | n/a (XML stanza)
Default value: | n/a (XML stanza)
Requirements: | Optional element. Valid only for stateful session EJBs in a cluster.
Parent elements: | weblogic-enterprise-bean, stateful-session-descriptor

Function

The stateful-session-clustering stanza element specifies clustering behaviors for a stateful session EJB instances in a cluster:

Example

The following excerpt shows the structure of a entity-clustering stanza:

>     <stateful-session-clustering>

>     	<home-is-clusterable>true</home-is-clusterable>

>     	<home-load-algorithm>random</home-load-algorithm>

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

>     	<replication-type>InMemory</replication-type>

>     </stateful-session-clustering>

stateful-session-descriptor

Range of values: | n/a (XML stanza)
Default value: | n/a (XML stanza)
Requirements: | One stateful-session-descriptor stanza is required for each stateful session EJB in the .jar.
Parent elements: | weblogic-enterprise-bean

Function

The stateful-session-descriptor element specifies deployment behavior for a stateful session EJB:

Example

The following example shows the structure of the stateful-session-descriptor stanza:

>     <stateful-session-descriptor>
>        <stateful-session-cache>...</stateful-session-cache>
>        <allow-concurrent-calls>...</allow-concurrent-calls>
>        <persistent-store-dir>...</persistent-store-dir>
>        <stateful-session-clustering>...</stateful-session-clustering>
>        <allow-remove-during-transaction>...
>        </allow-remove-during-transaction>
>     </stateful-session-descriptor>

stateless-bean-call-router-class-name

Range of values: | Valid router class name
Default value: | n/a
Requirements: | Optional element. Valid only for stateless session EJBs in a cluster.
Parent elements: | weblogic-enterprise-bean, stateless-session-descriptor stateless-clustering

Function

The stateless-bean-call-router-class-name element specifies the name of a custom class to use for routing bean method calls. This class must implement weblogic.rmi.cluster.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.

Example

See stateless-clustering.

stateless-bean-is-clusterable

Range of values: | true | false
Default value: | true
Requirements: | Optional element. Valid only for stateless session EJBs in a cluster.
Parent elements: | weblogic-enterprise-bean, stateless-session-descriptor stateless-clustering

Function

Use stateless-bean-is-clusterable to specify whether a stateless session bean's EJBObject interface is clustered. Clustered EJBObjects support load balancing and failover.

If stateless-bean-is-clusterable is true, when a home interface of a clustered stateless session bean creates a bean instance, it returns a EJBObject stub to the client that lists all of the servers in the cluster. Given the stateless nature of the bean, any instance can service any client request.

Example

See stateless-clustering.

stateless-bean-load-algorithm

Range of values: | round-robin | random | weight-based
Default value: | Value of weblogic.cluster.defaultLoadAlgorithm
Requirements: | Optional element. Valid only for stateless session EJBs in a cluster.
Parent elements: | weblogic-enterprise-bean, stateless-session-descriptor stateless-clustering

Function

stateless-bean-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 stateless-bean-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.

Example

See stateless-clustering.

stateless-bean-methods-are-idempotent

Range of values: | true | false
Default value: | false
Requirements: | Optional element. Valid only for stateless session EJBs in a cluster.
Parent elements: | weblogic-enterprise-bean, stateless-session-descriptor stateless-clustering

Function

DEPRECATED: The stateless-bean-methods-are-idempotent element is now deprecated and will be removed in a future version of WebLogic.

Please use the idempotent-methods element instead.

Example

See stateless-clustering.

stateless-clustering

Range of values: | n/a (XML stanza)
Default value: | n/a (XML stanza)
Requirements: | Optional element. Valid only for stateless session EJBs in a cluster.
Parent elements: | weblogic-enterprise-bean, stateless-session-descriptor

Function

The stateless-clustering element specifies the options that determine how WebLogic Server replicates stateless session EJB instances in a cluster:

Example

The following excerpt shows the structure of a stateless-clustering stanza:

>     <stateless-clustering>
>        <home-is-clusterable>.../home-is-clusterable>
>        <home-load-algorithm>...</home-load-algorithm>
>        <home-call-router-class-name>...</home-call-router-class-name>
>        <use-serverside-stubs>...</use-serverside-stubs>
>        <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>
>     </stateless-clustering>

stateless-session-descriptor

Requirements: | One stateless-session-descriptor element is required for each stateless session EJB in the JAR file.
Parent elements: | weblogic-enterprise-bean

Function

The stateless-session-descriptor element defines deployment behaviors, such as caching, clustering, and persistence, for stateless session EJBs in WebLogic Server.

Example

The following example shows the structure of the stateless-session-descriptor stanza:

>     <stateless-session-descriptor>
>     	<pool>...</pool>
>     	<stateless-clustering>...</stateless-clustering>
>     </stateless-session-descriptor>

transaction-descriptor

Range of values: | n/a (XML stanza)
Default value: | n/a (XML stanza)
Requirements: | Optional element.
Parent elements: | weblogic-enterprise-bean

Function

The transaction-descriptor element specifies options that define transaction behavior in WebLogic Server. Currently, this stanza includes only one element: trans-timeout-seconds.

Example

The following example shows the structure of the transaction-descriptor stanza:

>     <transaction-descriptor>

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

>     </transaction-descriptor>

transaction-isolation

Range of values: | n/a (XML stanza)
Default value: | n/a
Requirements: | Optional element.
Parent elements: | weblogic-ejb-jar

Function

The transaction-isolation element specifies method-level transaction isolation settings for an EJB. Example

The transaction-isolation stanza can contain the elements shown here:

>     <transaction-isolation>
>     	<isolation-level>...</isolation-level>
>     	<method>
>     		<description>...</description>
>     		<ejb-name>...</ejb-name>
>     		<method-intf>...</method-intf>
>     		<method-name>...</method-name>
>     		<method-params>...</method-params>
>     	</method>
>     </transaction-isolation>

>     For more information see isolation-level.

transport-requirements

Range of values: | n/a
Default value: | n/a
Requirements: | n/a
Parent elements: | weblogic-enterprise-bean, iiop-security-descriptor

Function

The transport-requirements element provides the transport requirements for the EJB.

Example

The transport-requirements stanza can contain the elements shown here

>     <iiop-security-descriptor>
>     	<transport-requirements>
>     		<confidentiality>supported</confidentiality>
>     		<integrity>supported</integrity>
>     		<client-cert-authorization>suppoted
>     			</client-cert-authentication>
>     	</transport-requirements>
>     </iiop-security-descriptor>

trans-timeout-seconds

Range of values: | 0 to max
Default value: | 30
Requirements: | Optional element. Valid for any type of EJB.
Parent elements: | weblogic-enterprise-bean, transaction-descriptor

Function

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

Example

See transaction-descriptor.

type-identifier

Range of values: | Valid string. WebLogic_CMP_RDBMS specifies WebLogic Server RDBMS-based persistence.
Default value: | n/a
Requirements: | Required only for entity EJBs that use container-managed persistence services.
Parent elements: | weblogic-enterprise-bean, entity-descriptor, persistence persistence-use

Function

The type-identifier element contains text that identifies an entity EJB persistence type. WebLogic Server RDBMS-based persistence uses the identifier, WebLogic_CMP_RDBMS. If you use a different persistence vendor, consult the vendor's documentation for information on the correct type-identifier.

Example

See persistence-use for an example that shows the complete persistence-use definition for WebLogic Server RDBMS-based persistence.

type-storage

Range of values: | 5.1.0 for WebLogic persistence, EJB 1.1 6.0 for WebLogic persistence, EJB 2.0.
Default value: | n/a
Requirements: | Required only for entity EJBs that use container-managed persistence services.
Parent elements: | weblogic-enterprise-bean, entity-descriptor, persistence persistence-use

Function

The type-storage element 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-rdbms-jar.xml to store persistence data for a bean. This file is stored in the META-INF subdirectory of the JAR file.

Example

See persistence-use for an example that shows the complete persistence-use definition for WebLogic Server RDBMS-based persistence.

type-version

Range of values: | Valid string
Default value: | n/a
Requirements: | Required only for entity EJBs that use container-managed persistence services.
Parent elements: | weblogic-enterprise-bean, entity-descriptor, persistence persistence-use

Function

For example, for WebLogic 2.0 CMP persistence, use the value:

6.0

For WebLogic 1.1 CMP persistence, use the value:

5.1.0

This element is necessary if multiple versions of the same persistence type are installed.

Note: If you use WebLogic Server RDBMS-based persistence, 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').

Example

See persistence-use for an example that shows the complete persistence-use definition for WebLogic Server RDBMS-based persistence.

weblogic-ejb-jar

Range of values: | N/A
Default value: | N/A
Requirements: | N/A
Parent elements: | N/A

Function

weblogic-ejb-jar is the root element of the weblogic component of the EJB deployment descriptor.

weblogic-enterprise-bean

Range of values: |
Default value: |
Requirements: |
Parent elements: | weblogic-ejb-jar

Function

The weblogic-enterprise-bean element contains the deployment information for a bean that is available in WebLogic Server.

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. See EJB Life Cycle.

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, as described in EJB Life Cycle.

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. See EJB Life Cycle for more information.

idle-timeout-seconds defaults to 600.

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-use>
>           <type-identifier>...</type-identifier>
>           <type-version>...</type-version>
>           <type-storage>...</type-storage>
>        </persistence-use>
>        <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. See Using is-modified-method-name to Limit Calls to ejbStore() (EJB 1.1 Only) for more information.

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 TRANSACTION_READ_UNCOMMITTED, 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. See ejbLoad() and ejbStore() Behavior for Entity EJBs for more information.

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-use

A persistence-use defines a persistence service that can be used by an EJB. You can define multiple persistence-use entries in weblogic-ejb-jar.xml for testing with multiple persistence services.

persistence-use 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-rdbms-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-use stanza with values appropriate for WebLogic Server RDBMS persistence:

>     <persistence-use>

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

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

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

>     </persistence-use>

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. See Using cache-between-transactions to Limit Calls to ejbLoad() for more information.

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.

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.cluster.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

Use stateless-bean-is-clusterable to specify whether a stateless session bean's EJBObject interface is clustered. Clustered EJBObjects support load balancing and failover.

If stateless-bean-is-clusterable is true, when a home interface of a clustered stateless session bean creates a bean instance, it returns a EJBObject stub to the client that lists all of the servers in the cluster. Given the stateless nature of the bean, any instance can service any client request

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>TransactionSerializable</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

Range of values: | TransactionSerializable | TransactionReadCommitted | TransactionReadUncommitted | TransactionRepeatableRead | TransactionReadCommittedForUpdate | TransactionReadCommittedForUpdateNoWait
Default value: | default setting of the underlying database
Requirements: | Optional element.
Parent elements: | weblogic-ejb-jar transaction-isolation

Function

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 addition 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, for container-managed persistence (CMP) beans only. 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 secluded 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, for container-managed persistence (CMP) beans only.

  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.

  See Setting Container-Managed Transaction Isolation Levels for background information on the Oracle-specific isolation-level values.

Refer to your database documentation for more information on the implications and support for different isolation levels.

Example

See transaction-isolation.

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.