B weblogic-ejb-jar.xml Deployment Descriptor Reference

The EJB 2.1 elements in the weblogic-ejb-jar.xml file, the WebLogic-specific XML Schema-based (XSD) deployment descriptor file. Use these definitions to create the WebLogic-specific weblogic-ejb-jar.xml file that is part of your EJB deployment.

In pre-9.0 releases of WebLogic Server, weblogic-ejb-jar.xml was Document Type Definition-based (DTD). For backward compatibility, WebLogic Server still supports XSD-based or DTD-based EJB descriptors; you can deploy applications that use DTD-based descriptors in WebLogic Server without modifying the descriptors.

Note:

If you are using metadata annotations in your EJB 3.x implementation, refer to EJB Metadata Annotations Reference in Developing Enterprise JavaBeans for Oracle WebLogic Server.

For information on:

• XML Schema Definitions and the namespace declaration required in weblogic-ejb-jar.xml, as well as Document Type Definitions and DOCTYPE headers, see Deployment Descriptor Schema and Document Type Definitions Reference.

• the weblogic-cmp-jar.xml file, see weblogic-cmp-jar.xml Deployment Descriptor Reference.

• EJB 1.1 deployment descriptor elements, see Important Information for EJB 1.1 Users.

See the complete weblogic-ejb-jar.xsd schema at http://www.oracle.com/webfolder/technetwork/weblogic/weblogic-ejb-jar/index.html.

This appendix includes the following topics:

• 2.1 weblogic-ejb-jar.xml File Structure
  
• 2.1 weblogic-ejb-jar.xml Elements
  
• allow-concurrent-calls
  
• allow-remove-during-transaction
  
• cache-between-transactions
  
• cache-type
  
• client-authentication
  
• client-cert-authentication
  
• clients-on-same-server
  
• component-factory-class-name
  
• concurrency-strategy
  
• confidentiality
  
• connection-factory-jndi-name
  
• connection-factory-resource-link
  
• create-as-principal-name
  
• delay-updates-until-end-of-tx
  
• description
  
• destination-jndi-name
  
• destination-resource-link
  
• disable-warning
  
• dispatch-policy
  
• distributed-destination-connection
  
• durable-subscription-deletion
  
• ejb-name
  
• ejb-reference-description
  
• ejb-ref-name
  
• enable-bean-class-redeploy
  
• enable-call-by-reference
  
• enable-dynamic-queries
  
• entity-always-uses-transaction
  
• entity-cache
  
• entity-cache-name
  
• entity-cache-ref
  
• entity-clustering
  
• entity-descriptor
  
• estimated-bean-size
  
• externally-defined
  
• finders-load-bean
  
• generate-unique-jms-client-id
  
• global-role
  
• home-call-router-class-name
  
• home-is-clusterable
  
• home-load-algorithm
  
• idempotent-methods
  
• identity-assertion
  
• idle-timeout-seconds
  
• iiop-security-descriptor
  
• init-suspend-seconds
  
• initial-beans-in-free-pool
  
• initial-context-factory
  
• integrity
  
• invalidation-target
  
• is-modified-method-name
  
• isolation-level
  
• jms-client-id
  
• jms-polling-interval-seconds
  
• jndi-binding
  
• jndi-name
  
• local-jndi-name
  
• max-beans-in-cache
  
• max-beans-in-free-pool
  
• max-messages-in-transaction
  
• max-queries-in-cache
  
• max-suspend-seconds
  
• message-destination-descriptor
  
• message-destination-name
  
• message-driven-descriptor
  
• method
  
• method-intf
  
• method-name
  
• method-param
  
• method-params
  
• network-access-point
  
• passivate-as-principal-name
  
• persistence
  
• persistence-use
  
• persistent-store-dir
  
• persistent-store-logical-name
  
• pool
  
• principal-name
  
• provider-url
  
• read-timeout-seconds
  
• remote-client-timeout
  
• remove-as-principal-name
  
• replication-type
  
• resource-env-ref-name
  
• res-ref-name
  
• resource-adapter-jndi-name
  
• resource-description
  
• resource-env-description
  
• resource-link
  
• retry-count
  
• retry-methods-on-rollback
  
• role-name
  
• run-as-identity-principal
  
• run-as-principal-name
  
• run-as-role-assignment
  
• security-permission
  
• security-permission-spec
  
• security-role-assignment
  
• service-reference-description
  
• session-timeout-seconds
  
• singleton-bean-call-router-class-name
  
• singleton-bean-is-clusterable
  
• singleton-bean-load-algorithm
  
• singleton-clustering
  
• singleton-session-descriptor
  
• stateful-session-cache
  
• stateful-session-clustering
  
• stateful-session-descriptor
  
• stateless-bean-call-router-class-name
  
• stateless-bean-is-clusterable
  
• stateless-bean-load-algorithm
  
• stateless-clustering
  
• stateless-session-descriptor
  
• stick-to-first-server
  
• timer-descriptor
  
• timer-implementation
  
• transaction-descriptor
  
• transaction-isolation
  
• transport-requirements
  
• trans-timeout-seconds
  
• type-identifier
  
• type-storage
  
• type-version
  
• use-serverside-stubs
  
• use81-style-polling
  
• weblogic-compatibility
  
• weblogic-ejb-jar
  
• weblogic-enterprise-bean
  
• work-manager
  

2.1 weblogic-ejb-jar.xml File Structure

The WebLogic Server weblogic-ejb-jar.xml deployment descriptor file describes the elements that are unique to WebLogic Server.

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

• description

• weblogic-enterprise-bean

  • ejb-name

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

  • transaction-descriptor

  • iiop-security-descriptor

  • enable-call-by-reference

  • network-access-point

  • clients-on-same-server

  • run-as-principal-name

  • create-as-principal-name

  • remove-as-principal-name

  • passivate-as-principal-name

  • jndi-name

  • local-jndi-name

  • dispatch-policy

  • remote-client-timeout

  • stick-to-first-server

• security-role-assignment

• run-as-role-assignment

• security-permission

• transaction-isolation

• message-destination-descriptor

• idempotent-methods

• retry-methods-on-rollback

• enable-bean-class-redeploy

• timer-implementation

• disable-warning

• work-manager

• component-factory-class-name

• weblogic-compatibility

2.1 weblogic-ejb-jar.xml Elements

Examine the elements in weblogic-ejb-jar.xml that are supported in this release of WebLogic Server.

The following list of the elements in weblogic-ejb-jar.xml :

• allow-concurrent-calls

• allow-remove-during-transaction

• cache-between-transactions

• cache-type

• client-authentication

• client-cert-authentication

• clients-on-same-server

• component-factory-class-name

• concurrency-strategy

• confidentiality

• connection-factory-jndi-name

• connection-factory-resource-link

• create-as-principal-name

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

• description

• destination-jndi-name

• destination-resource-link

• disable-warning

• dispatch-policy

• distributed-destination-connection

• durable-subscription-deletion

• ejb-name

• ejb-reference-description

• ejb-ref-name

• enable-bean-class-redeploy

• enable-call-by-reference

• enable-dynamic-queries

• entity-always-uses-transaction

• entity-cache

• entity-cache-name

• entity-cache-ref

• entity-clustering

• entity-descriptor

• estimated-bean-size

• externally-defined

• finders-load-bean

• generate-unique-jms-client-id

• global-role

• home-call-router-class-name

• home-is-clusterable

• home-load-algorithm

• idempotent-methods

• identity-assertion

• idle-timeout-seconds

• iiop-security-descriptor

• init-suspend-seconds

• initial-beans-in-free-pool

• initial-context-factory

• integrity

• invalidation-target

• is-modified-method-name

• isolation-level

• jms-client-id

• jms-polling-interval-seconds

• jndi-binding

• jndi-name

• local-jndi-name

• max-beans-in-cache

• max-beans-in-free-pool

• max-messages-in-transaction

• max-queries-in-cache

• max-suspend-seconds

• message-destination-descriptor

• message-destination-name

• message-driven-descriptor

• method

• method-intf

• method-name

• method-param

• method-params

• network-access-point

• passivate-as-principal-name

• persistence

• persistence-use

• persistent-store-dir

• persistent-store-logical-name

• pool

• principal-name

• provider-url

• read-timeout-seconds

• remote-client-timeout

• remove-as-principal-name

• replication-type

• resource-env-ref-name

• res-ref-name

• resource-adapter-jndi-name

• resource-description

• resource-env-description

• resource-link

• retry-count

• retry-methods-on-rollback

• role-name

• run-as-identity-principal

• run-as-principal-name

• run-as-role-assignment

• security-permission

• security-permission-spec

• security-role-assignment

• service-reference-description

• session-timeout-seconds

• singleton-bean-call-router-class-name

• singleton-bean-is-clusterable

• singleton-bean-load-algorithm

• singleton-clustering

• singleton-session-descriptor

• stateful-session-cache

• stateful-session-clustering

• stateful-session-descriptor

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

• stateless-bean-is-clusterable

• stateless-bean-load-algorithm

• stateless-clustering

• stateless-session-descriptor

• stick-to-first-server

• timer-descriptor

• timer-implementation

• transaction-descriptor

• transaction-isolation

• transport-requirements

• trans-timeout-seconds

• type-identifier

• type-storage

• type-version

• use-serverside-stubs

• use81-style-polling

• weblogic-compatibility

• weblogic-ejb-jar

• weblogic-enterprise-bean

• work-manager

allow-concurrent-calls

Note:

The allows-concurrent-calls element is deprecated in the WebLogic Server EJB 3.1 container. Oracle recommends using the javax.ejb.AccessTimeout metadata annotation instead, which enables you to specify the amount of time that a concurrent access attempt should block before timing out. See EJB Metadata Annotations Reference in Developing Enterprise JavaBeans for Oracle WebLogic Server.

Range of values: True | False

Default value: False

Parent elements:

• weblogic-enterprise-bean

• stateful-session-descriptor

• Function
  
• Example
  

Function

Specifies whether a stateful session bean instance allows concurrent method calls. By default, allows-concurrent-calls is False, in accordance with the EJB specification, and WebLogic Server will throw a RemoteException when a stateful session bean instance is currently handling a method call and another (concurrent) method call arrives on the server.

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

Parent elements:

weblogic-enterprise-bean
  stateful-session-descriptor

• Function
  
• Example
  

Function

Specifies that the remove method on a stateful session bean can be invoked within a transaction context.

Note:

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

Parent elements:

weblogic-enterprise-bean
  entity-descriptor
    entity-cache or entity cache-ref

• Function
  
• Example
  

Function

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

Specify True to enable the EJB container to perform long term caching of the data. Specify False to enable the EJB container to perform short term caching of the data.

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 Limiting Database Reads with cache-between-transactions for more information.

Example

See persistence.

cache-type

Range of values: NRU | LRU

Default value: NRU

Parent elements:

weblogic-enterprise-bean
  stateful-session-cache

• Function
  
• Example
  

Function

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 8, WebLogic Server uses a value of 8 for max-beans-in-cache.

Example

<stateful-session-cache>
    <cache-type>NRU</cache-type>
</stateful-session-cache>

client-authentication

Range of values: none | supported | required

Default value: n/a

Parent elements:

weblogic-enterprise-bean
  iiop-security-descriptor

• Function
  
• Example
  

Function

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: n/a

Parent elements:

weblogic-enterprise-bean
  iiop-security-descriptor
    transport-requirements

• Function
  
• Example
  

Function

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

Parent element:

weblogic-enterprise-bean

• Function
  
• Example
  

Function

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 Administering Clusters for Oracle WebLogic Server for more information on collocated EJBs.

Example

<weblogic-enterprise-bean>
    <ejb-name>AccountBean</ejb-name>
    ...
    <clients-on-same-server>True</clients-on-same-server>
</weblogic-enterprise-bean>

component-factory-class-name

Range of values: N/A

Default value: null

Parent element:

weblogic-ejb-jar

• Function
  

Function

Enable the Spring extension by setting this element to org.springframework.jee.interfaces.SpringComponentFactory. This element exists in EJB, Web, and application descriptors. A module-level descriptor overwrites an application-level descriptor. If the tag is set to null (default), the Spring extension is disabled.

concurrency-strategy

Range of values: Exclusive | Database | ReadOnly | Optimistic

Default value: Database

Parent elements:

weblogic-enterprise-bean
  entity-descriptor
    entity-cache

Or

weblogic-enterprise-bean
  entity-descriptor
    entity-cache-ref

• Function
  
• Example
  

Function

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 blocked until the transaction completes. This option was the default locking behavior for WebLogic Server 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 is 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.

  Note:

  When a cluster member updates a bean with a concurrency-strategy of Optimistic that is deployed to a cluster, the EJB container attempts to invalidate all copies of the bean in all servers in the cluster. You can disable this behavior by setting cluster-invalidation-disabled in weblogic-cmp-jar.xml to True. For more information, see Invalidation Options for Optimistic Concurrency in Clusters.

See Choosing a Concurrency Strategy for more information on the Exclusive and Database locking behaviors. See Read-Write versus Read-Only Entity Beans for more information about read-only entity EJBs.

Example

<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

Parent elements:

weblogic-enterprise-bean
  iiop-security-descriptor
    transport-requirements

• Function
  
• Example
  

Function

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 JNDI name

Default value: If not specified, the default is weblogic.jms.MessageDrivenBeanConnectionFactory, which must have been declared in the JMSConnectionFactory element in config.xml.

Parent elements:

weblogic-enterprise-bean
  message-driven-descriptor

• Function
  
• Example
  

Function

Specifies the JNDI name of the JMS Connection Factory that a message-driven EJB looks up to create its queues and topics. See "Configuring MDBs for Destinations" and "How to Set connection-factory-jndi-name" in

Example

<message-driven-descriptor>
    <connection-factory-jndi-name>
    java:comp/env/jms/MyConnectionFactory
    </connection-factory-jndi-name>
</message-driven-descriptor>

connection-factory-resource-link

Range of values: Valid resource within a JMS module

Default value: n/a.

Parent elements:

weblogic-enterprise-bean
  message-destination-descriptor

• Function
  

Function

Maps to a resource within a JMS module defined in ejb-jar.xml to an actual JMS Module Reference in WebLogic Server.

create-as-principal-name

Range of values: Valid principal name

Default value: n/a

Parent element:

weblogic-enterprise-bean

• Function
  

Function

Introduced in WebLogic Server 8.1 SP01, specifies the principal to be used in situations where ejbCreate would otherwise run with an anonymous principal. Under such conditions, the choice of which principal to run as is governed by the following rule:

if create-as-principal-name is set

then use that principal

else

If a run-as role has been specified for the bean in ejb-jar.xml

then use a principal according to the rules for setting the run-as-role-assignment

else

run ejbCreate as an anonymous principal.

The create-as-principal-name element only needs to be specified if operations within ejbCreate require more permissions than the anonymous principal would have.

This element effects the ejbCreate methods of stateless session beans and message-driven beans.

See also remove-as-principal-name, passivate-as-principal-name, and principal-name.

delay-updates-until-end-of-tx

Range of values: True | False

Default value: True

Parent elements:

weblogic-enterprise-bean
  entity-descriptor
    persistence

• Function
  
• Example
  

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 TransactionReadUncommitted, you may want to allow other database users to view the intermediate results of in-progress transactions. In this case, set delay-updates-to-end-of-tx to False to update the bean's persistent store at the conclusion of each method invoke. See Understanding ejbLoad() and ejbStore() Behavior 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

<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

Parent elements:

weblogic-ejb-jar

and

weblogic-ejb-jar
  transaction-isolation
    method

and

weblogic-ejb-jar
  idempotent-methods
    method

and

weblogic-ejb-jar
  retry-methods-on-rollback

• Function
  
• Example
  

Function

Describes the parent element.

Example

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

destination-jndi-name

Range of values: Valid JNDI name

Default value: n/a

Parent elements:

weblogic-enterprise-bean
  message-destination-descriptor

and

weblogic-enterprise-bean
  message-driven-descriptor

• Function
  
• Example
  

Function

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-destination-descriptor and message-driven-descriptor.

destination-resource-link

Range of values: Valid resource within a JMS module

Default value: n/a

Parent elements:

weblogic-enterprise-bean
  message-destination-descriptor

• Function
  

Function

Maps to a resource within a JMS module defined in ejb-jar.xml to an actual JMS Module Reference in WebLogic Server.

disable-warning

Range of values: BEA-010001 | BEA-010054 | BEA-010200 | BEA-010202

Default value: n/a

Parent element:

weblogic-ejb-jar

• Function
  
• Example
  

Function

Specifies that WebLogic Server should disable the warning message whose ID is specified. Set this element to one of four values:

• BEA-010001—Disables this warning message: "EJB class loaded from system classpath during deployment."

• BEA-010054—Disables this warning message: "EJB class loaded from system classpath during compilation."

• BEA-010200—Disables this warning message: "EJB impl class contains a public static field, method or class."

• BEA-010202—Disables this warning message: "Call-by-reference not enabled."

Example

To disable the warning message: "Call-by-reference not enabled", set <disable-warning>, as shown below.

<disable-warning>BEA-010202</disable-warning>

dispatch-policy

Range of values: Valid execute queue name

Default value: n/a

Parent element:

weblogic-enterprise-bean

• Function
  
• Example
  

Function

Designates which server execute thread pool the EJB should run in. Dispatch polices are supported for all types of beans, including entity, session, and message-driven.

If no dispatch-policy is specified, or the specified dispatch-policy refers to a nonexistent server execute thread pool, then the server's default execute thread pool is used instead.

WebLogic Server ignores dispatch-policy if the host server instance does not have an execute thread queue bearing a corresponding name.

If a message-driven bean (MDB) is driven by a foreign (non-WebLogic) destination source, WebLogic Server might ignore dispatch-policy, as the MDB may instead run in the foreign provider's threading mechanism. For example, for the IBM WebSphere MQSeries messaging software, dispatch-policy is not honored for non-transactional queues; instead the application code runs in an MQSeries thread. For MQSeries transactional queues, and both non-transactional and transactional topics, dispatch-policy is honored.

The maximum number of concurrently running MDB instances is designated by a combination of max-beans-in-free-pool and dispatch-policy values. See MDB Thread Management in Tuning Performance of Oracle WebLogic Server.

Example

<dispatch-policy>queue_name</dispatch-policy>

distributed-destination-connection

Range of values: LocalOnly | EveryMember

Default value: LocalOnly

Parent elements:

weblogic-ejb-jar
  weblogic-enterprise-bean
    message-driven-descriptor

• Function
  
• Example
  

Function

Note:

This element is valid for WebLogic JMS 9.0 or later.

Specifies whether an MDB that accesses a WebLogic JMS distributed queue in the same cluster consumes from all distributed destination members or only those members local to the current Weblogic Server.

Valid values include:

• LocalOnly—Deployment descriptor and message-driven bean are in the same cluster.

• EveryMember—Deployment descriptor is on a remote server.

If set to EveryMember, the total number of connections will be equal to: (the number of servers where message-driven bean is deployed) x (the number of destinations). For larger deployments, the number of connections may consume a considerable amount of resources.

The EveryMember setting incurs additional network and CPU overhead transferring messages from remote servers to the local MDB; it is normally only recommended for limited use cases (such as MDBs with JMS selector filters that are unique to the current server).

Example

<distributed-destination-connection>EveryMember</distributed-destination-connection>

durable-subscription-deletion

Range of values: True | False

Default value: False

Parent elements:

weblogic-ejb-jar
  weblogic-enterprise-bean
    message-driven-descriptor

• Function
  
• Example
  

Function

Indicates whether you want durable topic subscriptions to be automatically deleted when an MDB is undeployed or removed.

Example

<durable-subscription-deletion>True</durable-subscription-deletion>

ejb-name

Range of values: Name, which conforms to the lexical rules for an NMTOKEN, of an EJB that is defined in ejb-jar.xml

Default value: n/a

Parent elements:

weblogic-enterprise-bean

and

weblogic-enterprise-bean
  method

• Function
  
• Example
  

Function

Specifies an enterprise bean's name, using the same name for the bean that is specified in ejb-jar.xml. 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.

Note:

Not recommended in weblogic-enterprise-bean. For more information, see Using EJB Links.

Example

See method.

ejb-reference-description

Range of values: n/a

Default value: n/a

Parent element:

weblogic-enterprise-bean

• Function
  
• Example
  

Function

Maps the JNDI name of an EJB in WebLogic Server to the name by which it is specified in the ejb-ref-name element in ejb-jar.xml.

Example

<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: Valid ejb-ref-name specified in the associated ejb-jar.xml file

Default value: n/a

Parent elements:

weblogic-enterprise-bean
  ejb-reference-description

• Function
  
• Example
  

Function

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

Example

<ejb-reference-description>
    <ejb-ref-name>AdminBean</ejb-ref-name>
    <jndi-name>payroll.AdminBean</jndi-name>
</ejb-reference-description>

enable-bean-class-redeploy

Range of values: True | False

Default value: False

Parent element:

weblogic-enterprise-jar

• Function
  
• Example
  

Function

By default, the EJB implementation class is loaded in the same classloader as the rest of the EJB classes. When the enable-bean-class-redeploy element is enabled, the implementation class, along with its super classes, gets loaded in a child classloader of the EJB module classloader. This allows the EJB implementation class to be redeployed without redeploying the entire EJB module.

There are some potential problems with loading the bean class in a child classloader. First, the bean class will no longer be visible to any classes loaded in the parent classloader, so those classes cannot refer to the bean class or errors will occur. Also, the bean class will not be able to invoke any package protected methods on any classes loaded in a different classloader. So, if your bean class invokes a helper class in the same package, the helper class methods must be declared public or IllegalAccessErrors will result.

Note:

This element is deprecated for EJB 3.0. Starting with WebLogic Server 10.3.0, you can replace this feature with FastSwap. See Using FastSwap Deployment to Minimize Redeployment in Deploying Applications to Oracle WebLogic Server.

Example

The following XML element enables redeployment of an individual bean class:

<enable-bean-class-redeploy>True</enable-bean-class-redeploy>

enable-call-by-reference

Range of values: True | False

Default value: False

Parent element:

weblogic-enterprise-bean

• Function
  
• Example
  

Function

When enable-call-by-reference is False, parameters to the EJB methods are copied—or passed by value—regardless of whether the EJB is called remotely or from within the same EAR.

When enable-call-by-reference is True, EJB methods called from within the same EAR file or standalone JAR file will pass arguments by reference. This improves the performance of method invocation since parameters are not copied.

Note:

When an EJB is called remotely, method parameters are always passed by value. Remote calls may be between applications on different JVMs or between applications on the same JVM.

For example, suppose two applications named EJBApp1.ear, and EJBApp2.ear are deployed on the same server. EJBApp1.ear includes EJB1, and EJBApp2.ear includes EJB2. In this situation, the calls between EJB1 and EJB2 are considered remote calls even though they are on the same JVM.

Example

<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

Parent elements:

weblogic-enterprise-bean
  entity-descriptor

• Function
  
• Example
  

Function

Set to True to enable dynamic queries. Dynamic queries are only available for use with EJB 2.x CMP beans.

Example

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

entity-always-uses-transaction

Range of values: True | False

Default value: False

Parent elements:

weblogic-ejb-jar
  weblogic-compatibility

• Function
  

Function

This element, introduced in WebLogic Server 9.0, allows you to specify whether an entity bean must always use a transaction. Before WebLogic Server 9.0, when an entity bean ran in an unspecified transaction, the EJB container would create a transaction for the entity bean. Now, the EJB container no longer creates a transaction when an entity bean runs in an unspecified transaction. To disable this behavior and cause the EJB container to create a transaction for entity beans that run in unspecified transaction, set the value of this element to True.

entity-cache

Range of values: n/a

Default value: n/a

Parent elements:

weblogic-enterprise-bean
  entity-descriptor

• Function
  
• Example
  

Function

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 Understanding Entity Caching for more information.

Example

<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: Name assigned to an application level entity cache in the weblogic-application.xml file

Default value: n/a

Parent elements:

weblogic-enterprise-bean
  entity-descriptor
    entity-cache-ref

• Function
  
• Example
  

Function

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

For more information about the weblogic-application.xml file, see Enterprise Application Deployment Descriptor Elements in Developing Applications for Oracle WebLogic Server.

Example

See entity-cache-ref.

entity-cache-ref

Range of values: n/a

Default value: n/a

Parent elements:

weblogic-enterprise-bean
  entity-descriptor

• Function
  
• Example
  

Function

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 concurrency-strategy to 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 beans with a concurrency-strategy of Exclusive. A MultiVersion cache supports the Database, ReadOnly, and Optimistic concurrency strategies.

Example

<entity-cache-ref>
    <entity-cache-name>AllEntityCache</entity-cache-name>
    <read-timeout-seconds>600</read-timeout-seconds>
    <cache-between-transactions>true</cache-between-transactions>
    <concurrency-strategy>ReadOnly</concurrency-strategy>
    <estimated-bean-size>20</estimated-bean-size>
</entity-cache-ref>

entity-clustering

Range of values: n/a

Default value: n/a

Parent elements:

weblogic-enterprise-bean
  entity-descriptor

• Function
  
• Example
  

Function

Specifies how an entity bean will be replicated in a WebLogic cluster:

• home-is-clusterable

• home-load-algorithm

• home-call-router-class-name

• use-serverside-stubs

Example

<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>
    <use-serverside-stubs>True</use-serverside-stubs>
</entity-clustering>

entity-descriptor

Range of values: n/a

Default value: n/a

Parent element:

weblogic-enterprise-bean

• Function
  
• Example
  

Function

Specifies the following deployment parameters that are applicable to an entity bean:

• pool

• timer-descriptor

• entity-cache or entity-cache-ref

• persistence

• entity-clustering

• invalidation-target

• enable-dynamic-queries

Example

<entity-descriptor>
    <pool>...</pool>
    <timer-descriptor>...</timer-descriptor>
    <entity-cache>...</entity-cache>
    <persistence>...</persistence>
    <entity-clustering>...</entity-clustering>
    <invalidation-target>...</invalidation-target>
    <enable-dynamic-queries>...</enable-dynamic-queries>
</entity-descriptor>

estimated-bean-size

Range of values: n/a

Default value: n/a

Parent elements:

weblogic-enterprise-bean
  entity-descriptor

• Function
  
• Example
  

Function

Specifies the estimated average size of the instances of an entity bean in bytes. This is the average number of bytes 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 and 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 instances 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: none

Parent elements:

weblogic-ejb-jar
  security-role-assignment

• Function
  

Function

Indicates that a particular security role is defined externally in a security realm, outside of the deployment descriptor. 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. Use this element instead of global-role, which has been deprecated and was removed from WebLogic Server in release 9.0.

finders-load-bean

Range of values: True | False

Default value: True

Parent elements:

weblogic-enterprise-bean
  entity-descriptor
    persistence

• Function
  
• Example
  

Function

Valid only for CMP entity EJBs. 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

<entity-descriptor>
    <persistence>
        <finders-load-bean>True</finders-load-bean>
    </persistence>
</entity-descriptor>

generate-unique-jms-client-id

Range of values: True | False

Default value: False

Parent elements:

weblogic-ejb-jar
  weblogic-enterprise-bean
    message-driven-descriptor

• Function
  

Function

Indicates whether or not you want the EJB container to generate a unique client-id for every instance of an MDB. Enabling this flag makes it easier to deploy durable MDBs to multiple server instances in a WebLogic Server cluster.

global-role

The global-role element is deprecated and was removed from WebLogic Server in release 9.0. Use the externally-defined element instead.

home-call-router-class-name

Range of values: Valid name of a custom class

Default value: n/a

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-session-clustering

• Function
  
• Example
  

Function

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

Parent elements:

weblogic-enterprise-bean
  entity-descriptor
    entity-clustering

and

weblogic-enterprise-bean
  stateful-session-descriptor
    stateful-session-clustering

and

weblogic-enterprise-bean
  stateful-session-descriptor
    stateless-clustering

• Function
  
• Example
  

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.

Example

See entity-clustering.

home-load-algorithm

Range of values: round-robin | random | weight-based | RoundRobinAffinity | RandomAffinity | WeightBasedAffinity

Default value: Value of weblogic.cluster.defaultLoadAlgorithm

Parent elements:

weblogic-enterprise-bean
  entity-descriptor
    entity-clustering

and

weblogic-enterprise-bean
  stateful-session-descriptor
    stateful-session-clustering

and

weblogic-enterprise-bean
  entity-descriptor
    entity-clustering

• Function
  
• Example
  

Function

Specifies the algorithm to use for load balancing between replicas of the EJB home in a cluster. 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.

• round-robin-affinity—server affinity governs connections between external Java clients and server instances; round robin load balancing is used for connections between server instances.

• weight-based-affinity—server affinity governs connections between external Java clients and server instances; weight-based load balancing is used for connections between server instances.

• random-affinity—server affinity governs connections between external Java clients and server instances; random load balancing is used for connections between server instances.

See Load Balancing for EJBs and RMI Objects in Administering Clusters for Oracle WebLogic Server.

Example

See entity-clustering and stateful-session-clustering.

idempotent-methods

Range of values: n/a

Default value: n/a

Parent element:

weblogic-ejb-jar

• Function
  
• Example
  

Function

Defines list of methods of a clustered EJB 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.

Clustering must be enabled for 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

<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: none

Parent elements:

weblogic-enterprise-bean
  iiop-security-descriptor

• Function
  
• Example
  

Function

Specifies whether the EJB supports or requires identity assertion.

Example

See iiop-security-descriptor.

idle-timeout-seconds

Range of values: 0 to maxSeconds, where 0 denotes unlimited and maxSeconds is the maximum value of an int

Default value: 600

Parent elements:

weblogic-enterprise-bean
  entity-descriptor
    entity-cache

and

weblogic-enterprise-bean
  entity-descriptor
    entity-cache-ref

and

weblogic-enterprise-bean
  stateful-session-descriptor
    stateful-session-cache

and

weblogic-enterprise-bean
  stateless-session-descriptor or message-driven-descriptor or entity-descriptor
    pool

• Function
  
• Example
  

Function

Defines the maximum length of time an 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 Caching and Passivating Stateful Session EJBs and Managing Entity Bean Pooling and Caching for more information.

Also defines the maximum length of time an EJB should remain idle in the free pool before it is removed. After this time has elapsed, WebLogic Server removes the bean instance from the free pool so long as doing so will not cause the number of beans in the pool to fall below the number specified in initial-beans-in-free-pool.

Note:

Although idle-timeout-seconds appears in the entity-cache element, WebLogic Server 8.1 SP1 and SP2 do not use its value in managing the life cycle of entity EJBs—in those service packs, 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

Parent element:

weblogic-enterprise-bean

• Function
  
• Example
  

Function

Specifies security configuration parameters at the bean level. These parameters determine the IIOP security information contained in the IOR.

Example

<iiop-security-descriptor>
    <transport-requirements>...</transport-requirements>
    <client-authentication>supported<client-authentication>
    <identity-assertion>supported</identity-assertion>
</iiop-security-descriptor>

init-suspend-seconds

Range of values: any integer

Default value: 5

Parent elements:

weblogic-enterprise-bean
  message-driven-descriptor

• Function
  

Function

Specifies the initial number of seconds to suspend an MDB's JMS connection when the EJB container detects a JMS resource outage. See Configuring Suspension of Message Delivery During JMS Resource Outages in Developing Message-Driven Beans for Oracle WebLogic Server.

initial-beans-in-free-pool

Range of values: 0 to maxBeans

Default value: 0

Parent elements:

weblogic-enterprise-bean
  stateless-session-descriptor or message-driven-descriptor or entity-descriptor
    pool

• Function
  
• Example
  

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.

Note:

Based on the Enterprise JavaBean specification, the javax.ejb.ActivationConfigProperty annotation is used for MDBs only. This annotation is not used for session or entity beans.

Example

See pool.

initial-context-factory

Range of values: Valid name of an initial context factory

Default value: weblogic.jndi.WLInitialContextFactory

Parent elements:

weblogic-enterprise-bean
  message-destination-descriptor

and

weblogic-enterprise-bean
  message-driven-descriptor

• Function
  
• Example
  

Function

Specifies the initial context factory used by the JMS provider to create initial context. See Configuring MDBs for Destinations and How to Set initial-context-factory in Developing Message-Driven Beans for Oracle WebLogic Server.

Example

<message-driven-descriptor>
    <initial-context-factory>fiorano.jms.rtl.FioranoInitialContextFactory
    </initial-context-factory>
</message-driven-descriptor>

See also message-destination-descriptor.

integrity

Range of values: none | supported | required

Default value: n/a

Parent elements:

weblogic-enterprise-bean
  iiop-security-descriptor
    transport-requirements

• Function
  
• Example
  

Function

Specifies the transport integrity requirements for the 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: n/a

Default value: n/a

Parent elements:

weblogic-enterprise-bean
  entity-descriptor

• Function
  
• Example
  

Function

Specifies a Read-Only entity EJB that should be invalidated when this container-managed persistence entity EJB has been modified.

The target ejb-name must be a Read-Only entity EJB and this element can only be specified for an EJB 2.x container-managed persistence entity EJB.

Example

<invalidation-target>
    <ejb-name>StockReaderEJB</ejb-name>
</invalidation-target>

is-modified-method-name

Range of values: Valid entity EJB method name

Default value: n/a

Parent elements:

weblogic-enterprise-bean
  entity-descriptor
    persistence

• Function
  
• Example
  

Function

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.x CMP entity EJBs based on the EJB 2.x specification. However, it still applies to BMP and 1.1 CMP EJBs. When you deploy EJB 2.x 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

<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 value of the underlying database

Parent elements:

weblogic-ejb-jar
  transaction-isolation

• Function
  
• Oracle Database-Only Isolation Levels
  
• Example
  

Function

Defines method-level transaction isolation settings for an EJB. Allowable values include:

• TransactionSerializable—Simultaneously executing this transaction multiple times has the same effect as executing the transaction multiple times in a serial fashion.

  Note:

  For Oracle databases, Oracle recommends that you use the TransactionReadCommittedForUpdate isolation level instead of the TransactionSerializable isolation level. This is because Oracle databases do not lock read data at the TransactionSerializable isolation level. Additionally, at the TransactionSerializable isolation level, it is possible for concurrent transactions on Oracle databases to proceed without throwing the Oracle exception ORA-08177 "can't serialize access for this transaction"). For more information on the TransactionReadCommittedForUpdate isolation level, see Oracle Database-Only Isolation Levels.

• TransactionReadCommitted—The transaction can view only committed updates from other transactions.

• TransactionReadUncommitted—The transaction can view uncommitted updates from other transactions.

• TransactionRepeatableRead—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.

Oracle Database-Only Isolation Levels

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

• TransactionReadCommittedForUpdate— Supported only for Oracle databases, for container-managed persistence (CMP) EJBs only. This value sets the isolation level to TransactionReadCommitted, 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 the Oracle database 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 (but does not always) occur when using the TransactionSerializable isolation level with Oracle databases.

  Note:

  For Oracle databases, Oracle recommends that you use this isolation level (TransactionReadCommittedForUpdate) instead of the TransactionSerializable isolation level. This is because Oracle databases do not lock read data at the TransactionSerializable isolation level.

• TransactionReadCommittedForUpdateNoWait—Supported only for Oracle databases, for container-managed persistence (CMP) EJBs only.

  This value sets the isolation level to TransactionReadCommitted, 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 TransactionReadCommittedForUpdate setting, TransactionReadCommittedForUpdateNoWait causes the Oracle DBMS to NOT WAIT if the required locks cannot be acquired immediately—the affected SELECT query will fail and an exception will be thrown by the container.

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

Example

See transaction-isolation.

jms-client-id

Range of values: n/a

Default value: ejb-name for the EJB

Parent element:

message-driven-descriptor

• Function
  
• Example
  

Function

Specifies a client ID for the MDB when it connects to a JMS destination. Required for durable subscriptions to JMS topics.

If you specify the connection factory that the MDB uses in connection-factory-jndi-name, the client ID can be defined in the ClientID element of the associated JMSConnectionFactory element in config.xml.

If JMSConnectionFactory in config.xml does not specify a ClientID, or if you use the default connection factory, (you do not specify connection-factory-jndi-name) the message-driven bean uses the jms-client-id value as its client id.

Example

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

jms-polling-interval-seconds

Range of values: n/a

Default value: 10 seconds

Parent element:

message-driven-descriptor

• Function
  
• Example
  

Function

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

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

jndi-binding

Range of values: Custom JNDI name

Default value: n/a

Parent elements:

weblogic-enterprise-bean

and

weblogic-enterprise-bean
  resource-description

and

weblogic-enterprise-bean
  ejb-reference-description

• Function
  
• Example
  

Function

Specifies the custom JNDI name that can be applied to a bean class or business interface to indicate a JNDI name for a certain client view. When applied to a bean class to indicate the JNDI name of a no-interface view, the className is optional.

Example

See resource-description and ejb-reference-description.

jndi-name

Note:

The jndi-name element is deprecated in this release of WebLogic Server. Use jndi-binding instead.

Range of values: Valid JNDI name

Default value: n/a

Parent elements:

weblogic-enterprise-bean

and

weblogic-enterprise-bean
  resource-description

and

weblogic-enterprise-bean
  ejb-reference-description

• Function
  
• Example
  

Function

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

Note:

Assigning a JNDI name to a bean is not recommended. Global JNDI names generate heavy multicast traffic during clustered server startup. See Using EJB Links for the better practice. If you have an EAR library that contains EJBs, you cannot deploy multiple applications that reference the library because attempting to do so will result in a JNDI name conflict. This is because global JNDI name cannot be set for individual EJBs in EAR libraries; it can only be set for an entire library.

Example

See resource-description and ejb-reference-description.

local-jndi-name

Note:

The local-jndi-name element is deprecated in this release of WebLogic Server. Use jndi-binding instead.

Range of values: Valid JNDI name

Default value: n/a

Parent elements:

weblogic-enterprise-bean

• Function
  
• Example
  

Function

JNDI name for a bean's local home. If a bean has both a remote and a local home, then it can be assigned two JNDI names; one for each home.

Note:

Assigning a JNDI name to a bean is not recommended. See Using EJB Links for the better practice.

Example

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

max-beans-in-cache

Range of values: 1 to maxBeans

Default value: 1000

Parent elements:

weblogic-enterprise-bean
  entity-descriptor
    entity-cache

and

weblogic-enterprise-bean
  stateful-session-descriptor
    stateful-session-cache

• Function
  
• Example
  

Function

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 Caching and Passivating Stateful Session EJBs.

Example

<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

Parent elements:

weblogic-enterprise-bean
  stateless-session-descriptor
    pool

and

weblogic-enterprise-bean
  message-driven-descriptor
    pool

and

weblogic-enterprise-bean
  entity-descriptor
    pool

• Function
  
• Example
  

Function

WebLogic Server maintains a free pool of EJBs for every entity bean, stateless session bean, and message-driven bean class. The max-beans-in-free-pool element defines the size of this pool.

Note:

Based on the Enterprise JavaBean specification, the javax.ejb.ActivationConfigProperty annotation is used for MDBs only. This annotation is not used for session or entity beans.

Example

See pool.

max-messages-in-transaction

Range of values: All positive integers

Default value: n/a

Parent elements:

weblogic-enterprise-bean
  message-driven-descriptor

• Function
  

Function

Specifies the maximum number of messages that can be in a transaction for this MDB.

max-queries-in-cache

Range of values: All positive integers

Default value: n/a

Parent elements:

weblogic-enterprise-bean
  entity-descriptor

• Function
  

Function

This element, introduced in WebLogic Server 9.0, specifies the maximum number of read-only entity queries to cache at the bean level. For information on caching read-only entity queries at the application level, see Using Query Caching (Read-Only Entity Beans).

max-suspend-seconds

Range of values: Any integer

Default value: 60

Parent elements:

weblogic-enterprise-bean
  message-driven-descriptor

• Function
  

Function

Specifies the maximum number of seconds to suspend an MDB's JMS connection when the EJB container detects a JMS resource outage. To disable JMS connection suspension when the EJB container detects a JMS resource outage, set the value of this element to 0. See Configuring Suspension of Message Delivery During JMS Resource Outages in Developing Message-Driven Beans for Oracle WebLogic Server.

message-destination-descriptor

Range of values: n/a

Default value: n/a

Parent elements:

weblogic-enterprise-bean

• Function
  
• Example
  

Function

Maps a message destination reference in the ejb-jar.xml file to an actual message destination, such as a JMS Queue or Topic, in WebLogic Server.

Example

<message-destination-descriptor>
    <message-destination-name>...</message-destination-name>
    <destination-jndi-name>...</destination-jndi-name>
    <resource-link>...</resource-link>
    <initial-context-factory>...</initial-context-factory>
    <provider-url>...</provider-url>
</message-destination-descriptor>

message-destination-name

Range of values: A valid message destination reference name from the ejb-jar.xml file

Default value: n/a

Requirements: This element is required if the EJB specifies messages destination references in ejb-jar.xml.

Parent elements:

weblogic-enterprise-bean
  message-destination-descriptor

• Function
  
• Example
  

Function

Specifies the name of a message destination reference. This is the reference that the EJB provider places within the ejb-jar.xml deployment file.

Example

See message-destination-descriptor.

message-driven-descriptor

Range of values: n/a

Default value: n/a

Parent element:

weblogic-enterprise-bean

• Function
  
• Example
  

Function

Associates a message-driven bean with a JMS destination in WebLogic Server.

Example

<message-driven-descriptor>
    <pool>...</pool>
    <timer-descriptor>...</timer-descriptor>
    <destination-jndi-name>...</destination-jndi-name>
    <initial-context-factory>...</initial-context-factory>
    <provider-url>...</provider-url>
    <connection-factory-jndi-name>...</connection-factory-jndi-name>
    <jms-polling-interval-seconds>...</jms-polling-interval-seconds>
    <jms-client-id>...</jms-client-id>
    <generate-unique-jms-client-id>...</generate-unique-jms-client-id>
    <durable-subscription-deletion>...</durable-subscription-deletion>
    <max-messages-in-transaction>...</max-messages-in-transaction>
    <distributed-destination-connection>...</distributed-destination-connection>
    <use81-style-polling>...</use81-style-polling>
    <init-suspend-seconds>...</init-suspend-seconds>
    <max-suspend-seconds>...</max-suspend-seconds>
</message-driven-descriptor>

method

Range of values: n/a

Default value: n/a

Parent elements:

weblogic-ejb-jar
  transaction-isolation

and

weblogic-ejb-jar
  idempotent-methods

and

weblogic-ejb-jar
  retry-methods-on-rollback

• Function
  
• Example
  

Function

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

Example

<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

Parent elements:

weblogic-ejb-jar
  transaction-isolation
    method

and

weblogic-ejb-jar
  idempotent-methods
    method

• Function
  
• Example
  

Function

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

Parent elements:

weblogic-ejb-jar
  transaction-isolation
    method

and

weblogic-ejb-jar
  idempotent-methods
    method

• Function
  
• Example
  

Function

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 name of a method parameter

Default value: n/a

Parent elements:

weblogic-ejb-jar
  transaction-isolation
    method
      method-params

and

weblogic-ejb-jar
  idempotent-methods
    method
      method-params

• Function
  
• Example
  

Function

Specifies the fully-qualified Java type name of a method parameter.

Example

See method-params.

method-params

Range of values: n/a

Default value: n/a

Parent elements:

weblogic-ejb-jar
  transaction-isolation
    method

and

weblogic-ejb-jar
  idempotent-methods
    method

• Function
  
• Example
  

Function

Contains one or more elements that define the Java type name of each of the method's parameters.

Example

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

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

network-access-point

Range of values: Name of a custom network access point

Default value: n/a

Parent elements:

weblogic-enterprise-bean

• Function
  
• Example
  

Function

Assigns a custom network channel that the EJB will use for network communications. A network channel defines a set of connection attributes. See Configuring Network Resources in Administering Server Environments for Oracle WebLogic Server.

Example

<weblogic-enterprise-bean>
    <network-access-point>SSLChannel</network-access-point>
</weblogic-enterprise-bean>

passivate-as-principal-name

Range of values: Valid WebLogic Server principal

Default value: n/a

Parent elements:

weblogic-enterprise-bean

• Function
  

Function

The passivate-as-principal-name element, introduced in WebLogic Server 8.1 SP01, specifies the principal to be used in situations where ejbPassivate would otherwise run with an anonymous principal. Under such conditions, the choice of which principal to run as is governed by the following rule:

If passivate-as-principal-name is set

then use that principal

else

if a run-as role has been specified for the bean in ejb-jar.xml

then use a principal according to the rules for setting the run-as-role-assignment

else

run ejbPassivate as an anonymous principal.

The passivate-as-principal-name element only needs to be specified if operations within ejbPassivate require more permissions than the anonymous principal would have.

This element affects the ejbPassivate methods of stateless session beans when passivation occurs due to a cache timeout.

See also remove-as-principal-name, create-as-principal-name, and principal-name.

persistence

Range of values: n/a

Default value: n/a

Parent elements:

weblogic-enterprise-bean
  entity-descriptor

• Function
  
• Example
  

Function

Required only for entity EJBs that use container-managed persistence services. 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-use

Example

<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>
        <persistence-use>...</persistence-use>
    </persistence>
</entity-descriptor>

persistence-use

Range of values: n/a

Default value: n/a

Parent elements:

weblogic-enterprise-bean
  entity-descriptor
    persistence

• Function
  
• Example
  

Function

Required only for entity EJBs that use container-managed persistence services. The persistence-use element stores an identifier of the persistence type to be used for this particular bean.

Example

<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

Range of values: Valid file system directory

Default value: pstore

Parent elements:

weblogic-enterprise-bean
  stateful-session-descriptor

• Function
  
• Example
  

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>MyPersistenceDir</persistent-store-dir>
    <stateful-session-clustering>...</stateful-session-clustering>
    <allow-remove-during-transaction>
</stateful-session-descriptor>

persistent-store-logical-name

Range of values: Valid name of a persistent store on the file system

Default value: n/a

Parent elements:

weblogic-enterprise-bean
  entity-descriptor
    timer-descriptor

and

weblogic-enterprise-bean
  message-driven-descriptor
    timer-descriptor

• Function
  

Function

Specifies the name of a persistent store on the server's file system where WebLogic Server stores timer objects. If you do not specify a persistent store name in this element, WebLogic Server stores timer objects in the default store.

pool

Range of values: n/a

Default value: n/a

Parent elements:

weblogic-enterprise-bean
  stateless-session-descriptor or message-driven-descriptor

and

  entity-descriptor

• Function
  
• Example
  

Function

Configures the behavior of the WebLogic Server free pool for entity EJBs, stateless session EJBs, and message-driven EJBs. The options are:

• max-beans-in-free-pool

• initial-beans-in-free-pool

• idle-timeout-seconds

Example

<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

Parent elements:

weblogic-ejb-jar
  security-role-assignment

• Function
  
• Example
  

Function

Specifies the name of an actual WebLogic Server principal to apply to the specified role-name. At least one principal-name is required in the security-role-assignment element. You may define more than one principal-name for each role-name.

Example

See security-role-assignment.

provider-url

Range of values: Valid URL

Default value: t3://localhost:7001

Parent elements:

weblogic-enterprise-bean
  message-destination-descriptor

and

weblogic-enterprise-bean
  message-driven-descriptor

• Function
  
• Example
  

Function

Specifies the URL to be used by the InitialContext. See Configuring MDBs for Destinations and How to Set provider-urlin Developing Message-Driven Beans for Oracle WebLogic Server.

Example

<message-driven-descriptor>
    <provider-url>WeblogicURL:Port</provider-url>
</message-driven-descriptor>

See also message-destination-descriptor.

read-timeout-seconds

Range of values: 0 to maxSeconds, where maxSeconds is the maximum value of an int

Default value: 600

Parent elements:

weblogic-enterprise-bean
  entity-descriptor
    entity-cache

or

weblogic-enterprise-bean
  entity-descriptor
    entity-cache-ref

• Function
  
• Example
  

Function

Specifies the number of seconds between ejbLoad() calls on a Read-Only entity bean. A value of 0 causes WebLogic Server to call 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>

remote-client-timeout

Range of values: 0 to maxSeconds, where maxSeconds is the maximum value of an int

Default value: 0

Parent elements:

weblogic-enterprise-bean

• Function
  
• Example
  

Function

Specifies the length of time that a remote RMI client will wait before it will time out. See Using a Read Timeout in Developing RMI Applications for Oracle WebLogic Server.

Example

The following entry causes a remote RMI client to timeout after waiting 5 seconds.

<weblogic-enterprise-bean>
    <ejb-name>AccountBean</ejb-name>
    ...
    <remote-client-timeout>5</remote-client-timeout>
</weblogic-enterprise-bean>

remove-as-principal-name

Range of values: n/a

Default value: n/a

Parent element:

weblogic-enterprise-bean

• Function
  

Function

This parameter only needs to be specified if operations within ejbRemove need more permissions than the anonymous principal would have.

The remove-as-principal-name element, introduced in WebLogic Server 8.1 SP1, specifies the principal to be used in situations where ejbRemove would otherwise run with an anonymous principal. Under such conditions, the choice of which principal to run as is governed by the following rule:

If remove-as-principal-name is set

then use that principal

else

if a run-as role has been specified for the bean in ejb-jar.xml

then use a principal according to the rules for setting the run-as-role-assignment

else

run ejbRemove as an anonymous principal

The remove-as-principal-name element only needs to be specified if operations within ejbRemove require more permissions than the anonymous principal would have.

This element effects the ejbRemove methods of stateless session beans and message-drive beans.

See also passivate-as-principal-name, create-as-principal-name, and principal-name.

replication-type

Range of values: InMemory | None

Default value: None

Parent elements:

weblogic-enterprise-bean
  stateful-session-descriptor
    stateful-session-clustering

• Function
  
• Example
  

Function

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.

Example

See stateful-session-clustering.

resource-env-ref-name

Range of values: A valid resource environment reference name from the ejb-jar.xml file

Default value: n/a

Parent elements:

weblogic-enterprise-bean
  resource-env-description

• Function
  
• Example
  

Function

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

Parent elements:

weblogic-enterprise-bean
  resource-description

• Function
  
• Example
  

Function

Specifies the name of a resourcefactory reference. This is the reference that the EJB provider places within the ejb-jar.xml deployment file. Required element if the EJB specifies resource references in ejb-jar.xml

Example

See resource-description.

resource-adapter-jndi-name

Range of values: n/a

Default value: n/a

Parent elements:

weblogic-ejb-jar
  weblogic-enterprise-bean
    message-driven-descriptor

• Function
  

Function

Identifies the resource adapter that this MDB receives messages from.

resource-description

Range of values: n/a

Default value: n/a

Parent element:

weblogic-enterprise-bean

• Function
  
• Example
  

Function

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

Example

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

resource-env-description

Range of values: n/a

Default value: n/a

Parent element:

weblogic-enterprise-bean

• Function
  
• Example
  

Function

Maps a resource environment reference defined in ejb-jar.xml to the JNDI name of an actual resource available in WebLogic Server.

Example

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

When jndi-name is not a valid URL, WebLogic Server treats it as a object that maps to a URL and is already bound in the JNDI tree, and binds a LinkRef with that jndi-name.

resource-link

Range of values: Valid resource within a JMS module

Default value: n/a

Parent elements:

weblogic-enterprise-bean
  message-destination-descriptor

• Function
  
• Example
  

Function

Maps to a resource within a JMS module defined in ejb-jar.xml to an actual JMS Module Reference in WebLogic Server.

Example

See message-destination-descriptor.

retry-count

Range of values: Any positive integer

Note:

While it is possible to set this value to less than or equal to 0, Oracle recommends that you do not do so because the EJB container will not retry transactions when this value is not greater than or equal to 1.

Default value: n/a

Parent elements:

weblogic-ejb-jar
  retry-methods-on-rollback

• Function
  

Function

Specifies the number of times you want the EJB container to automatically retry a container-managed transaction method that has rolled back.

retry-methods-on-rollback

Range of values: n/a

Default value: n/a

Parent element:

weblogic-ejb-jar

• Function
  

Function

Specifies the methods for which you want the EJB container to automatically retry container-managed transactions that have rolled back. Automatic transaction retry is supported for session and entity beans that use container-managed transaction demarcation. Additionally, regardless of the methods specified in this element, the EJB container does not retry transactions that fail because of system exception-based errors.

role-name

Range of values: Valid application role name

Default value: n/a

Parent elements:

weblogic-enterprise-bean
  security-role-assignment

• Function
  
• Example
  

Function

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

Example

See security-role-assignment.

run-as-identity-principal

Range of values: Valid security principal name

Default value: n/a

Parent elements:

weblogic-enterprise-bean

• Function
  
• Example
  

Function

Note:

The run-as-identity-principal element is deprecated in this release of WebLogic Server. Use run-as-principal-name instead.

The run-as-identity-principal element specifies which security principal name is to be used as the run-as principal for a bean that has specified a security identity run-as-role-name its ejb-jar.xml deployment descriptor.

For an explanation of how the mapping of run-as role-names to run-as-identity-principals or run-as-principal-names occurs, see the comments for the run-as-role-assignment element.

Example

<run-as-identity-principal>
    Fred
</run-as-identity-principal>

run-as-principal-name

Range of values: Valid principal

Default value: n/a

Parent elements:

weblogic-enterprise-bean

• Function
  
• Example
  

Function

Specifies which security principal name is to be used as the run-as principal for a bean that has specified a security-identity run-as role-name in its ejb-jar.xml deployment descriptor.

For an explanation of how the mapping of run-as role-names to run-as-principal-names occurs, see the comments for the run-as-role-assignment element.

Example

<run-as-principal-name>
    Fred
</run-as-principal-name>

run-as-role-assignment

Range of values: n/a

Default value: n/a

Parent elements:

weblogic-enterprise-bean

• Function
  
• Example
  
• A_EJB_with_runAs_role_X
  
• B_EJB_with_runAs_role_X
  
• C_EJB_with_runAs_role_Y
  

Function

Maps a given security-identity run-as role-name specified in the ejb-jar.xml deployment descriptor file to a run-as-principal-name.

The value of the run-as-principal-name for a given role-name that is specified here is scoped to all beans in the ejb-jar.xml deployment descriptor; it applies to all beans that specify that role-name as their security-identity run-as-role-name.

The run-as-principal-name value specified here can be overridden at the individual bean level by specifying a run-as-principal-name under that bean's weblogic-enterprise-bean element.

Note:

For a given bean, if there is no run-as-principal-name specified in either a run-as-role-assignment or in a bean specific run-as-principal-name tag, then the EJB container chooses the first principal-name of a security user in the weblogic-enterprise-bean security-role-assignment for the role-name and uses that principal-name as the run-as-principal-name.

Example

Suppose that in the ejb-jar.xml deployment descriptor file:

• Beans 'A_EJB_with_runAs_role_X' and 'B_EJB_with_runAs_role_X'

  specify a security-identity run-as role-name 'runAs_role_X'.

• Bean 'C_EJB_with_runAs_role_Y'

  specifies a security-identity run-as role-name 'runAs_role_Y'.

Consider the following excerpts from the corresponding weblogic-ejb-jar.xml deployment descriptor file:

<weblogic-ejb-jar>
    <weblogic-enterprise-bean>
        <ejb-name>
            A_EJB_with_runAs_role_x
        </ejb-name>
    </weblogic-enterprise-bean>
    <weblogic-enterprise-bean>
        <ejb-name>
            B_EJB_with_runAs_role_X
        </ejb-name>
        <run-as-principal-name>
            Joe 
        </run-as-principal-name>
    </weblogic-enterprise-bean>
    <weblogic-enterprise-bean>
        <ejb-name>
            C_EJB_with_runAs_role_Y
        </ejb-name>
    </weblogic-enterprise-bean>
    <security-role-assignment>
        <role-name>
            runAs_role_Y
        </role-name>
        <principal-name>
            first_principal_of_role_Y
        </principal-name>
        <principal-name>
            second_principal_of_role_Y
        </principal-name>
    </security-role-assignment>
    <run-as-role-assignment>
        <role-name> 
            runAs_role_X 
        </role-name>
        <run-as-principal-name>
            Fred
        </run-as-principal-name>
    </run-as-role-assignment>
</weblogic-ejb-jar>

Each of the beans chooses a different principal name to use as its run-as-principal-name.

A_EJB_with_runAs_role_X

This bean's run-as role-name is 'runAs_role_X'. The jar scoped <run-as-role-assignment> mapping will be used to look up the name of the principal to use.

The <run-as-role-assignment> mapping specifies that for <role-name> 'runAs_role_X' we are to use <run-as-principal-name> 'Fred'.

"Fred" is the principal name that will be used.

B_EJB_with_runAs_role_X

This bean's run-as role-name is also 'runAs_role_X'. This bean will not use the jar scoped <run-as-role-assignment> to look up the name of the principal to use because that value is overridden by this bean's <weblogic-enterprise-bean> <run-as-principal-name> value 'Joe'.

"Joe" is the principal name that will be used.

C_EJB_with_runAs_role_Y

This bean's run-as role-name is 'runAs_role_Y'. There is no explicit mapping of 'runAs_role_Y' to a run-as principal name; that is, there is no jar-scoped <run-as-role-assignment> for 'runAs_role_Y' nor is there a bean scoped <run-as-principal-name> specified in this bean's weblogic-enterprise-bean.

To determine the principal name to use, the <security-role-assignment> for <role-name> "runAs_role_Y" is examined. The first <principal-name> corresponding to a User (i.e. not a Group) is chosen.

"first_principal_of_role_Y" is the principal name that will be used.

security-permission

Range of values: n/a

Default value: n/a

Parent elements:

weblogic-ejb-jar

• Function
  
• Example
  

Function

Specifies a security permission that is associated with a Java EE Sandbox.

For more information, see the security permission specification:

http://docs.oracle.com/javase/8/docs/technotes/guides/security/PolicyFiles.html

Example

<security-permission>
    <description>Optional explanation goes here</description>
    <security-permission-spec>
    ...
    </security-permission-spec>
</security-permission> 

security-permission-spec

Range of values: n/a

Default value: n/a

Parent element:

security-permission

• Function
  
• Example
  

Function

Specifies a single security permission based on the Security policy file syntax.

For more information, see the security permission specification:

http://docs.oracle.com/javase/8/docs/technotes/guides/security/PolicyFiles.html

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

Default value: n/a

Parent elements:

weblogic-ejb-jar

• Function
  
• Example
  

Function

Maps application roles in the ejb-jar.xml file to the names of security principals available in WebLogic Server.

Example

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

service-reference-description

Range of values: n/a

Default value: n/a

Parent element:

weblogic-enterprise-bean

• Function
  
• Example
  

Function

Maps a Web Service destination reference in the ejb-jar.xml file to an actual Web Service in WebLogic Server.

• wsdl-url — the url of the dynamic wsdl of the referenced web service used by the client to create stub to invoke remote web service.

• port-info — defines wsdl:port information specified in wsdl.

• port-name — defines the local name of wsdl:port.

• stub-property — property to be set on the client-side stub, it has the same effect of as javax.xml.rpc.Stub._setProperty(prop_name, prop_value).

Example

<service-reference-description>
    <service-ref-name>service/WebServiceBroker</service-ref-name>
    <wsdl-url>
        http://@PROXY_SERVER@/webservice/BrokerServiceBean?wsdl
    </wsdl-url>
    <call-property>...</call-property>
    <port-info>
        <port-name>BrokerServiceIntfPort</port-name>
        <stub-property>
            <name>javax.xml.rpc.service.endpoint.address</name>
            <value>http://@PROXY_SERVER@/webservice/BrokerServiceBean<;/value>
        </stub-property>
    </port-info>
</service-reference-description>

session-timeout-seconds

Range of values: (None specified)

Default value: idle-timeout-seconds

Parent elements:

weblogic-enterprise-bean
  stateful-session-descriptor
    stateful-session-cache

• Function
  
• Example
  

Function

Determines how long the EJB container leaves a passivated stateful session bean on disk. The container removes a passivated EJB session-timeout-seconds after passivating the bean instance to disk. If session-timeout-seconds is not specified, the default is the value specified by idle-timeout-seconds.

Example

<stateful-session-descriptor>
    <stateful-session-cache> 
        <max-beans-in-cache>4</max-beans-in-cache>
        <idle-timeout-seconds>5</idle-timeout-seconds> 
        <session-timeout-seconds>120</session-timeout-seconds> 
        <cache-type>LRU</cache-type> 
    </stateful-session-cache>
</stateful-session-descriptor>

singleton-bean-call-router-class-name

Range of values: Valid custom class name

Default value: n/a

Parent elements:

weblogic-enterprise-bean
  singleton-session-descriptor
    singleton-clustering

• Function
  
• Example
  

Function

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 singleton-clustering.

singleton-bean-is-clusterable

Range of values: true | false

Default value: false

Parent elements:

weblogic-enterprise-bean
  singleton-session-descriptor

• Function
  
• Example
  

Function

Marks the remote business views of the bean as clusterable and supports load balancing and failover.

When singleton-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.

Example

See singleton-clustering.

singleton-bean-load-algorithm

Range of values: round-robin | random | weight-based | RoundRobinAffinity | RandomAffinity | WeightBasedAffinity

Default value: Value of weblogic.cluster.defaultLoadAlgorithm

Parent elements:

weblogic-enterprise-bean
  singleton-session-descriptor
    singleton-clustering

• Function
  
• Example
  

Function

Specifies the algorithm to use for load balancing between replicas of the EJB home.

You can define singleton-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—Load balancing is performed randomly among the servers hosting the bean.

• weight-based—Load balancing is performed according to the servers' current workload.

• round-robin-affinity—Server affinity governs connections between external Java clients and server instances; round robin load balancing is used for connections between server instances.

• weight-based-affinity—Server affinity governs connections between external Java clients and server instances; weight-based load balancing is used for connections between server instances.

• random-affinity—Server affinity governs connections between external Java clients and server instances; random load balancing is used for connections between server instances.

See Load Balancing for EJBs and RMI Objects in Administering Clusters for Oracle WebLogic Server.

Example

See singleton-clustering.

singleton-clustering

Range of values: n/a

Default value: n/a

Parent elements:

weblogic-enterprise-bean
  singleton-session-descriptor

• Function
  
• Example
  

Function

Specifies options that determine how WebLogic Server replicates singleton session EJB instances in a cluster.

Example

<singleton-clustering>
    <singleton-bean-is-clusterable>
        True
    </singleton-bean-is-clusterable>
    <singleton-bean-load-algorithm>
        random</singleton-bean-load-algorithm>
    <singleton-bean-call-router-class-name>
        beanRouter
    </singleton-bean-call-router-class-name>
    <singleton-bean-methods-are-idempotent>
        True
    </singleton-bean-methods-are-idempotent>
</singleton-clustering>

singleton-session-descriptor

Range of values: n/a

Default value: n/a

Parent element:

weblogic-enterprise-bean

• Function
  
• Example
  

Function

Defines deployment behaviors, such as caching, clustering, and persistence, for singleton session EJBs in WebLogic Server.

Example

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

stateful-session-cache

Range of values: n/a

Default value: n/a

Parent elements:

weblogic-enterprise-bean
  stateful-session-descriptor

• Function
  
• Example
  

Function

Defines the following options used to cache stateful session EJB instances.

• max-beans-in-cache

• idle-timeout-seconds

• session-timeout-sections

• cache-type

See Caching and Passivating Stateful Session EJBs for more information about caching of stateful session beans.

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>
    <session-timeout-seconds>...</session-timeout-seconds>
    <cache-type>...</cache-type>
</stateful-session-cache>

stateful-session-clustering

Range of values: n/a

Default value: n/a

Parent elements:

weblogic-enterprise-bean
  stateful-session-descriptor

• Function
  
• Example
  

Function

Specifies the following options that determine how WebLogic Server replicates stateful session EJB instances in a cluster:

• home-is-clusterable

• home-load-algorithm

• home-call-router-class-name

• replication-type

Example

<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

Default value: n/a

Parent element:

weblogic-enterprise-bean

• Function
  
• Example
  

Function

Defines deployment behaviors, such as caching, clustering, and persistence, for stateless session EJBs in WebLogic Server.

Example

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

stateless-bean-call-router-class-name

Range of values: Valid custom class name

Default value: n/a

Parent elements:

weblogic-enterprise-bean
  stateless-session-descriptor
    stateless-clustering

• Function
  
• Example
  

Function

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

Parent elements:

weblogic-enterprise-bean
  stateless-session-descriptor
    stateless-clustering

• Function
  
• Example
  

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.

Example

See stateless-clustering.

stateless-bean-load-algorithm

Range of values: round-robin | random | weight-based | RoundRobinAffinity | RandomAffinity | WeightBasedAffinity

Default value: Value of weblogic.cluster.defaultLoadAlgorithm

Parent elements:

weblogic-enterprise-bean
  stateless-session-descriptor
    stateless-clustering

• Function
  
• Example
  

Function

Specifies the algorithm to use for load balancing between replicas of the EJB home.

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—Load balancing is performed randomly among the servers hosting the bean.

• weight-based—Load balancing is performed according to the servers' current workload.

• round-robin-affinity—Server affinity governs connections between external Java clients and server instances; round robin load balancing is used for connections between server instances.

• weight-based-affinity—Server affinity governs connections between external Java clients and server instances; weight-based load balancing is used for connections between server instances.

• random-affinity—Server affinity governs connections between external Java clients and server instances; random load balancing is used for connections between server instances.

See Load Balancing for EJBs and RMI Objects in Administering Clusters for Oracle WebLogic Server.

Example

See stateless-clustering.

stateless-clustering

Range of values: n/a

Default value: n/a

Parent elements:

weblogic-enterprise-bean
  stateless-session-descriptor

• Function
  
• Example
  

Function

Specifies options that determine how WebLogic Server replicates stateless session EJB instances in a cluster.

Example

<stateless-clustering>
    <stateless-bean-is-clusterable>
        True
    </stateless-bean-is-clusterable>
    <stateless-bean-load-algorithm>
        random</stateless-bean-load-algorithm>
    <stateless-bean-call-router-class-name>
        beanRouter
    </stateless-bean-call-router-class-name>
    <stateless-bean-methods-are-idempotent>
        True
    </stateless-bean-methods-are-idempotent>
</stateless-clustering>

stateless-session-descriptor

Range of values: n/a

Default value: n/a

Parent elements:

weblogic-enterprise-bean

• Function
  
• Example
  

Function

Defines deployment parameters, such as caching, clustering, and persistence for stateless session EJBs in WebLogic Server.

Example

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

stick-to-first-server

Range of values: True or False

Default value: False

Parent element:

weblogic-enterprise-bean

• Function
  
• Example
  

Function

Defines "sticky" load balancing in a cluster. The server chosen for servicing the first request is used for all subsequent requests.

Example

<stick-to-first-server>
    True
</stick-to-first-server>

timer-descriptor

Range of values: n/a

Default value: n/a

Parent elements:

weblogic-enterprise-bean
  entity-descriptor

or

  message-driven-descriptor

or

  singleton-session-descriptor

or

  stateless-session-descriptor

• Function
  

Function

Specifies the persistent store that will be used to store the local timer information for the bean.

timer-implementation

Range of values:

Valid values include:

• Clustered—Specifies that timers are cluster aware. This option provides EJB timers with features such as automatic failover, load balancing, and improved accessibility within the cluster. This option is recommended for EJBs that will be deployed to a cluster of WebLogic servers.

• Local—Specifies that timers will only execute on the server on which they are created and are only visible to the beans on that server. When you set this element to Local, if you deploy an EJB to a cluster, and invoke the EJB to create a timer, that call could go to any server on the cluster. Another invocation (for instance, to cancel the timer) could also go to any server on the cluster and will not necessarily go to the same server in which the call to create the timer went. For instance, if the call to create a timer is directed to server1, and the call to cancel it is directed to server2, the EJB on server2 would not see the timer on server1 and would, therefore, fail to cancel it.

To avoid the limitation when using local timers, you can use one of the following approaches:

• Pin the EJB deployment to a single server in the cluster. This causes all calls to the EJB to go to server to which the EJB is pinned and all timers to exist on that same server. The trade-off to using this approach is that the EJB cannot take advantage of clustering benefits such as load balancing and failover.

• Ensure that calls to cancel timers go to all servers in the cluster by using a message-driven bean (MDB) that listens on a JMS topic. The message to cancel the timer can be published to the JMS topic and serviced by an MDB on each server. Then, the MDB on each server can invoke a cancelTimer method on the bean. The trade-off to using this approach is that it makes your application more complex and attempting to cancel timers on all servers is inefficient.

Default value: Local (the current file store-backed EJB timer service is used)

Parent element:

weblogic-ejb-jar

• Function
  
• Example
  

Function

Specifies whether the EJB timer service is cluster aware.

Example

<timer-implementation>
    Clustered
</timer-implementation>

transaction-descriptor

Range of values: n/a

Default value: n/a

Parent elements:

weblogic-enterprise-bean

• Function
  
• Example
  

Function

Specifies options that define transaction behavior in WebLogic Server. Currently, this element includes only one child element: trans-timeout-seconds.

Example

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

transaction-isolation

Range of values: n/a

Default value: n/a

Parent elements:

weblogic-ejb-jar

• Function
  
• Example
  

Function

Defines method-level transaction isolation settings for an EJB.

Example

<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

Parent elements:

weblogic-enterprise-bean
  iiop-security-descriptor

• Function
  
• Example
  

Function

Provides the transport requirements for the EJB.

Example

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

trans-timeout-seconds

Range of values: 0 to max

Default value: From domain-level JTA configuration.

Parent elements:

weblogic-enterprise-bean
  transaction-descriptor

• Function
  
• Example
  

Function

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

Parent elements:

weblogic-enterprise-bean
  entity-descriptor
    persistence
      persistence-use

• Function
  
• Example
  

Function

Required only for entity EJBs that use container-managed persistence services. Specifies 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 type definition for WebLogic Server RDBMS-based persistence.

type-storage

Range of values: Valid string

Default value: n/a

Parent elements:

weblogic-enterprise-bean
  entity-descriptor
    persistence
      persistence-use

• Function
  
• Example
  

Function

Required only for entity EJBs that use container-managed persistence services. Defines the full path of the file that stores data for this persistence type. The path must specify the file's location relative to the top level of the EJB's JAR deployment file or deployment directory.

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

Example

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

type-version

Range of values: Valid string

Default value: n/a

Parent elements:

weblogic-enterprise-bean
  entity-descriptor
    persistence
      persistence-use

• Function
  
• Example
  

Function

Required for entity EJBs that use container-managed persistence service, if multiple versions of the same persistence type are installed. Identifies the version of the specified persistence type. 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.

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 type definition for WebLogic Server RDBMS-based persistence.

use-serverside-stubs

Range of values: true | false

Default value: false

Parent elements:

weblogic-enterprise-bean
  entity-descriptor
    entity-clustering

and

weblogic-enterprise-bean
  stateful-session-descriptor
    stateful-session-clustering

and

weblogic-enterprise-bean
  entity-descriptor
    entity-clustering

• Function
  
• Example
  

Function

Causes the bean home to use server-side stubs in the context of server.

Example

See the example for entity-clustering.

use81-style-polling

Range of values: true | false

Default value: false

Parent elements:

weblogic-ejb-jar
  weblogic-enterprise-bean
    message-driven-descriptor

• Function
  
• Example
  

Function

Enables backwards compatibility for WLS Version 8.1-style polling.

In WLS version 8.1 and earlier, transactional MDBs with batching enabled created a dedicated polling thread for each deployed MDB. This polling thread was not allocated from the pool specified by dispatch-policy, it was an entirely new thread in addition to the all other threads running on the system. See Backwards Compatibility for WLS 10.0 and Earlier-style Polling in Tuning Performance of Oracle WebLogic Server.

Example

See the example for entity-clustering.

weblogic-compatibility

Range of values: n/a

Default value: n/a

Parent elements:

weblogic-ejb-jar

• Function
  

Function

This element, introduced in WebLogic Server 9.0 contains elements that specify compatibility flags.

weblogic-ejb-jar

Range of values: n/a

Default value: n/a

Parent elements: n/a

• Function
  

Function

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

weblogic-enterprise-bean

Range of values: n/a

Default value: n/a

Parent elements:

weblogic-ejb-jar

• Function
  

Function

Contains the deployment information for a bean that is available in WebLogic Server.

work-manager

Range of values: n/a

Default value: n/a

Parent elements:

weblogic-ejb-jar

• Function
  

Function

Specifies a work manager to manage work requests for EJBs.

For more information on work managers, see Using Work Managers to Optimize Scheduled Work in Administering Server Environments for Oracle WebLogic Server.