EJB Deployment Descriptors


	BEA Home \| Events \| Solutions \| Partners \| Products \| Services \| Download \| Developer Center \| WebSUPPORT
	http://www.oracle.com/technology/documentation/index.html \| Site Map \| Search \| Download Documentation \| Contact \| Glossary

\| WebLogic Server Doc Home \| Console Online Help \| Previous Topic \| Next Topic \| Contents \| Index \| View as PDF

weblogic-ejb-jar.xml deployment descriptors

This section describes the 6.1 WebLogic Server-specific XML elements found in weblogic600-ejb-jar.xml that are used to define the deployment descriptors in the WebLogic Server EJB container. These elements map to fields, of approximately the same name, in the WebLogic Server Administration Console Use these deployment descriptors for 2.0 EJBs.

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
Deployment file:	weblogic-ejb-jar.xml

Function

The allow-concurrent-calls element specifies whether a stateful session bean instance will allow 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.

cache-type

Range of values:	NRU \| LRU
Default value:	NRU
Requirements:
Parent elements:	weblogic-enterprise-bean stateful-session-cache
Deployment file:	weblogic-ejb-jar.xml

Function

The element sets the cache type for the EJB.

connection-factory-jndi-name

Range of values:
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
Deployment file:	weblogic-ejb-jar.xml

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 will be the weblogic.jms.MessageDrivenBeanConnectionFactory in config.xml.

concurrency-strategy

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

Function

This element specifies how the container should manage concurrent access to an entity bean. You can set this element to one of three possible values:

Exclusive is the default locking behavior for WebLogic Server versions 3.1 through 5.1. WebLogic Server places an exclusive lock on cached entity EJB instances when the bean is associated with a transaction. Other requests for the EJB instance block until the transaction completes.
Database causes WebLogic Server to defer locking requests for an entity EJB to the underlying datastore. With the Database concurrency strategy, WebLogic Server does not cache the intermediate results of entity EJBs involved in a transaction.
ReadOnly designates an entity EJB that is never modified. WebLogic Server calls ejbLoad() for ReadOnly beans based on the read-timeout-seconds parameter.

db-is-shared

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

Function

The db-is-shared element applies only to entity beans. When set to true WebLogic Server assumes that EJB data could be modified between transactions and reloads the 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.

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
Deployment file:	weblogic-ejb-jar.xml

Function

Set this element 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.

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.

description

Range of values:	n/a
Default value:	n/a
Requirements:	n/a
Parent elements:	weblogic-enterprise-bean, transaction-isolation method
Deployment file:	weblogic-ejb-jar.xml

Function

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

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
Deployment file:	weblogic-ejb-jar.xml

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 in WebLogic Server JNDI tree.

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 transaction-isolation method
Deployment file:	weblogic-ejb-jar.xml

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 architected relationship between the ejb-name in the deployment descriptor and the JNDI name that the deployer will assign to the enterprise bean's home.

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-description
Deployment file:	weblogic-ejb-jar.xml

Function

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

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.

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
Deployment file:	weblogic-ejb-jar.xml

Function

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

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
Deployment file:	weblogic-ejb-jar.xml

Function

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

enable-call-by-reference

Range of values:	true \| false
Default value:	true
Requirements:	Optional element.
Parent elements:	weblogic-enterprise-bean reference-description ejb-reference-description
Deployment file:	weblogic-ejb-jar.xml

Function

By default, EJB methods called from within the same server 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 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 server).

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
Deployment file:	weblogic-ejb-jar.xml

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

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
Deployment file:	weblogic-ejb-jar.xml

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

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
Deployment file:	weblogic-ejb-jar.xml

Function

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

pool
entity-cache
lifecycle
persistence
entity-clustsering

finders-load

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
Deployment file:	weblogic-ejb-jar.xml

-bean

Function

finders-load-bean 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 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.

home-call-router-class-name

Range of values:	Valid router class name
Default value:	null
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
Deployment file:	weblogic-ejb-jar.xml

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.extensions.CallRouter(). If specified, an instance of this class is called before each method call. The router class has the opportunity to choose a server to route to based on the method parameters. The class returns either a server name or null, which indicates that the current load algorithm should select the server.

home-is-clusterable

Range of values:	true \| false
Default value:	true
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
Deployment file:	weblogic-ejb-jar.xml

Function

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

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
Deployment file:	weblogic-ejb-jar.xml

Function

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.

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
Deployment file:	weblogic-ejb-jar.xml

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.

initial-beans-in-free-pool

Range of values:	0 to maxBeans
Default value:	0
Requirements:	Optional element. Valid only for stateless session EJBs.
Parent elements:	weblogic-enterprise-bean, pool
Deployment file:	weblogic-ejb-jar.xml

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.

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
Deployment file:	weblogic-ejb-jar.xml

Function

The initial-context-factory element specifies the 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.

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
Deployment file:	weblogic-ejb-jar.xml

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.

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.

isolation-level

Range of values:	Serializable \| ReadCommitted \| ReadUncommitted \| RepeatableRead
Default value:	n/a
Requirements:	Optional element.
Parent elements:	weblogic-enterprise-bean, transaction-isolation
Deployment file:	weblogic-ejb-jar.xml

Function

isolation-level specifies the isolation level for all of the EJB's database operations. The following are possible values for isolation-level:

TRANSACTION_READ_UNCOMMITTED: The transaction can view uncommitted updates from other transactions.
TRANSACTION_READ_COMMITTED: The transaction can view only committed 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.
TRANSACTION_SERIALIZABLE: Simultaneously executing this transaction multiple times has the same effect as executing the transaction multiple times in a serial fashion.

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

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-description resource-description and weblogic-enterprise-bean reference-description ejb-reference-description
Deployment file:	weblogic-ejb-jar.xml

Function

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

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
Deployment file:	weblogic-ejb-jar.xml

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.

lifecycle

Range of values:	n/a (XML stanza)
Default value:	n/a (XML stanza)
Requirements:	The lifecycle stanza is optional.
Parent elements:	weblogic-enterprise-bean, entity-descriptor and weblogic-enterprise-bean stateful-session-descriptor
Deployment file:	weblogic-ejb-jar.xml

Function

The lifecycle element defines options that affect the lifecycle of stateful and entity EJB instances within WebLogic Server. Currently, the lifecycle element includes only one element: passivation-strategy.

max-beans-in-cache

Range of values:	1 to maxBeans
Default value:	100
Requirements:	Optional element
Parent elements:	weblogic-enterprise-bean, entity-descriptor, entity-cache and weblogic-enterprise-bean stateful-session-descriptor stateful-session-cache
Deployment file:	weblogic-ejb-jar.xml

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

max-beans-in-free-pool

Range of values:	0 to maxBeans
Default value:	1000
Requirements:	Optional element. V
Parent elements:	weblogic-enterprise-bean, stateless-session-descriptor, pool weblogic-enterprise-bean, message-driven-descriptor, pool weblogic-enterprise-bean, entity-descriptor, pool
Deployment file:	weblogic-ejb-jar.xml

Function

WebLogic Server maintains a free pool of EJBs for every stateless session bean, message-driven, and entity bean class. The max-beans-in-free-pool element defines the size of this pool. For more information, see "EJB Lifecycle" in Programming WebLogic Server EJBs

message-driven-descriptor

Range of values:	n/a (XML stanza)
Default value:	n/a (XML stanza)
Requirements:
Parent elements:	weblogic-enterprise-bean
Deployment file:	weblogic-ejb-jar.xml

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

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-enterprise-bean transaction-isolation
Deployment file:	weblogic-ejb-jar.xml

Function

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

method-intf

Range of values:	Home \| Remote
Default value:	n/a
Requirements:	Optional element.
Parent elements:	weblogic-enterprise-bean transaction-isolation method
Deployment file:	weblogic-ejb-jar.xml

Function

method-intf specifies the EJB interface to which WebLogic Server applies isolation level properties. Use this element only if you need to differentiate between methods having the same signature in the EJB's home and remote interface.

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-enterprise-bean transaction-isolation method
Deployment file:	weblogic-ejb-jar.xml

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.

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-enterprise-bean transaction-isolation method method-params
Deployment file:	weblogic-ejb-jar.xml

Function

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

method-params

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

Function

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

passivation-strategy

Range of values:	default \| transaction
Default value:	default
Requirements:	Optional element. Valid only for entity EJBs.
Parent elements:	weblogic-enterprise-bean, entity-descriptor, lifecycle
Deployment file:	weblogic-ejb-jar.xml

Function

The passivation-strategy element determines whether or not WebLogic Server maintains the intermediate state of entity EJBs in its cache.

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
Deployment file:	weblogic-ejb-jar.xml

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
persistence-type
db-is-shared
persistence-use

persistence-type

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
Deployment file:	weblogic-ejb-jar.xml

Function

The persistence-type element defines a persistence service that the entity EJB can use. You can define multiple persistence-type stanzas in weblogic-ejb-jar.xml for testing your EJB with multiple persistence services. Only the persistence type defined in persistence-use is actually used during deployment.

persistence-type includes several elements that identify the persistence types:

type-identifier
type-version
type-storage

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
Deployment file:	weblogic-ejb-jar.xml

Function

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

persistent-store-dir

Range of values:	Fully qualified filesystem path
Default value:	n/a
Requirements:	Optional element.
Parent elements:	weblogic-enterprise-bean stateful-session-descriptor
Deployment file:	weblogic-ejb-jar.xml

Function

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

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
Deployment file:	weblogic-ejb-jar.xml

Function

The pool element configures the behavior of the WebLogic Server free pool for a stateless session and message driven EJBs. The options are:

max-beans-in-free-pool
initial-beans-in-free-pool

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
Deployment file:	weblogic-ejb-jar.xml

Function

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

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
Deployment file:	weblogic-ejb-jar.xml

Function

The provider-url element specifies the URL provider to be used by the InitialContext. Typically, this is the host : port.

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
Deployment file:	weblogic-ejb-jar.xml

Function

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 0, and WebLogic Server calls ejbLoad() only when the bean is brought into the cache.

reference-descriptor

Range of values:	n/a (XML stanza)
Default value:	n/a (XML stanza)
Requirements:	Optional element.
Parent elements:	weblogic-enterprise-bean
Deployment file:	weblogic-ejb-jar.xml

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.

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
Deployment file:	weblogic-ejb-jar.xml

Function

The replication-type element determines whether or not 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.

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
Deployment file:	weblogic-ejb-jar.xml

Function

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

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-description resource-description
Deployment file:	weblogic-ejb-jar.xml

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.

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
Deployment file:	weblogic-ejb-jar.xml

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.

resource-description

Range of values:	n/a (XML stanza)
Default value:	n/a (XML stanza)
Requirements:	Optional element.
Parent elements:	weblogic-enterprise-bean reference-description
Deployment file:	weblogic-ejb-jar.xml

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.

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
Deployment file:	weblogic-ejb-jar.xml

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.

run-as-identity-principal

Range of values:	Principal that will be used as the identity as defined in ejb-jar.xml
Default value:	n/a
Requirements:	Required element in security-role-assignment.
Parent elements:	weblogic-enterprise-bean
Deployment file:	weblogic-ejb-jar.xml

Function

The run-as-identity-principal element specifies the principal to be used as the identity for beans that have a security-identity.run-as-specified-identity set in the ejb-jar.xml.

The principal named in this element must be one of the principals mapped to the run-as-specified--identity role.

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:	weblogic-ejb-jar
Deployment file:	weblogic-ejb-jar.xml

Function

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

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
Deployment file:	weblogic-ejb-jar.xml

Function

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

home-is-clusterable
home-load-algorithm
home-call-router-class-name
replication-type

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
Deployment file:	weblogic-ejb-jar.xml

Function

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

max-beans-in-cache
idle-timeout-seconds
cache-type

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
Deployment file:	weblogic-ejb-jar.xml

Function

The stateful-session-descriptor element specifies the following deployment parameters that are applicable for stateful session EJBs in WebLogic Server:

stateful-session-cache
lifecycle
persistent-store-dir
stateful-session-clustering
allow-concurrent-calls

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
Deployment file:	weblogic-ejb-jar.xml

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.extensions.CallRouter(). If specified, an instance of this class is called before each method call. The router class has the opportunity to choose a server to route to based on the method parameters. The class returns either a server name or null, which indicates that the current load algorithm should select the server.

stateless-bean-is-clusterable

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
Deployment file:	weblogic-ejb-jar.xml

Function

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

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
Deployment file:	weblogic-ejb-jar.xml

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.

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
Deployment file:	weblogic-ejb-jar.xml

Function

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 recover automatically from any failure as long as another server hosting the bean can be reached.

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
Deployment file:	weblogic-ejb-jar.xml

Function

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

stateless-bean-is-clusterable
stateless-bean-load-algorithm
stateless-bean-call-router-class-name
stateless-bean-methods-are-idempotent

stateless-session-descriptor

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

Function

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

transaction-descriptor

Range of values:	n/a (XML stanza)
Default value:	n/a (XML stanza)
Requirements:	Optional element.
Parent elements:	weblogic-enterprise-bean
Deployment file:	weblogic-ejb-jar.xml

Function

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

transaction-isolation

Range of values:	n/a (XML stanza)
Default value:	n/a (XML stanza)
Requirements:	Optional element.
Parent elements:	transaction-description
Deployment file:	weblogic-ejb-jar.xml

Function

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

trans-timeout-seconds

Range of values:	0 to maxSeconds
Default value:	30
Requirements:	Optional element. Valid only for all EJBs.
Parent elements:	weblogic-enterprise-bean, transaction-descriptor
Deployment file:	weblogic-ejb-jar.xml

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.

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

type-identifier

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-type and weblogic-enterprise-bean, entity-descriptor, persistence persistence-use
Deployment file:	weblogic-ejb-jar.xml

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.

type-storage

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-type
Deployment file:	weblogic-ejb-jar.xml

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.

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-type and weblogic-enterprise-bean, entity-descriptor, persistence persistence-use
Deployment file:	weblogic-ejb-jar.xml

Function

The type-version element identifies the version of the specified persistence type.

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 following 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').

weblogic-ejb-jar

Range of values:
Default value:
Requirements:
Parent elements:	weblogic-enterprise-bean,
Deployment file:	weblogic-ejb-jar.xml

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-enterprise-bean,
Deployment file:	weblogic-ejb-jar.xml

Function

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

This section describes the 6.1 WebLogic Server-specific XML elements found in weblogic510-ejb-jar.xml that are used to define the deployment descriptors in the WebLogic Server EJB container. These elements map to fields, of approximately the same name, in the WebLogic Server Administration Console. Use these deployment descriptors for 1.1 EJBs.

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.

max-beans-in-free-pool

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

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

initial-beans-in-free-pool

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

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

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

max-beans-in-cache

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

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

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

idle-timeout-seconds

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

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

cache-strategy

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

Read-Write
Read-Only

The default value is Read-Write.

read-timeout-seconds

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

persistence-descriptor

The persistence-descriptor stanza specifies persistence options for entity EJBs.

is-modified-method-name

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

delay-updates-until-end-of-tx

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

persistence-type

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

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

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

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

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

type-storage defines the full path of the file that stores data for this persistence type. The path must specify the file's location relative to the top level of the EJB's .jar deployment file or deployment directory.
WebLogic Server RDBMS-based persistence generally uses an XML file named weblogic-cmp-rdbms-jar.xml to store persistence data for a bean. This file is stored in the META-INF subdirectory of the .jar file.

db-is-shared

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

stateful-session-persistent-store-dir

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

persistence-use

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

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.

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

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

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

home-call-router-class-name

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

stateless-bean-is-clusterable

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

stateless-bean-load-algorithm

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

stateless-bean-call-router-class-name

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

stateless-bean-methods-are-idempotent

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

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

transaction-descriptor

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

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.

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:

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

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.

isolation-level

isolation-level defines a valid transaction isolation level to apply to specific EJB methods. The following are possible values for isolation-level:

TRANSACTION_READ_UNCOMMITTED: The transaction can view uncommitted updates from other transactions.
TRANSACTION_READ_COMMITTED: The transaction can view only committed 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.
TRANSACTION_SERIALIZABLE: Simultaneously executing this transaction multiple times has the same effect as executing the transaction multiple times in a serial fashion.

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

method

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

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

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.

enable-call-by-reference

By default, EJB methods called from within the same server 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 server).