weblogic-ejb-jar.xml
Deployment Descriptor Reference
The following sections describe the EJB 2.0 deployment descriptor elements found in the weblogic-ejb-jar.xml file, the WebLogic-specific XML document type definitions (DTD) file. Use these definitions to create the WebLogic-specific weblogic-ejb-jar.xml file that is part of your EJB deployment.
For information on the EJB 1.1 deployment descriptor elements Important Information for EJB 1.1 Users.
- Document Type Definitions and DOCTYPE Header Information
- 2.0 weblogic-ejb-jar.xml File Structure
- 2.0 weblogic-ejb-jar.xml Elements
Document Type Definitions and DOCTYPE Header Information
The contents and arrangement of elements in your XML files must conform to the Document Type Definition (DTD) for each file you use. WebLogic Server ignores the DTDs embedded within the DOCTYPE header of XML deployment files, and instead uses the DTD locations that were installed along with the server. However, the DOCTYPE header information must include a valid URL syntax in order to avoid parser errors.
When editing or creating XML deployment files, it is critical to include the correct DOCTYPE header for each deployment file. In particular, using an incorrect PUBLIC element within the DOCTYPE header can result in parser errors that may be difficult to diagnose.
The header refers to the location and version of the Document Type Definition (DTD) file for the deployment descriptor. Although this header references an external URL at java.sun.com, WebLogic Server contains its own copy of the DTD file, so your host server need not have access to the Internet. However, still include this <!DOCTYPE...> element in your weblogic-ejb-jar.xml and weblogic-cmp-jar.xml files, and have them reference the external URL because the version of the DTD contained in this element is used to identify the version of this deployment descriptor.
XML files with incorrect header information may yield error messages similar to the following, when used with a tool that parses the XML (such as appc):
SAXException: This document may not have the identifier \Qidentifier_name'
where identifier_name generally includes the invalid text from the PUBLIC element.
The correct text for the PUBLIC elements for the WebLogic-Server-specific weblogic-ejb-jar.xml file is listed, by WebLogic Server version, in Table 9-1.
The correct text for the PUBLIC elements for the WebLogic-Server-specific weblogic-cmp-jar.xml file is listed, by WebLogic Server version, in Table 9-2.
See weblogic-cmp-jar.xml Deployment Descriptor Reference, for more information on the weblogic-cmp-jar.xml file.
The correct text for the PUBLIC elements for the Sun-Microsystems-specific ejb-jar.xml file is listed, by Enterprise JavaBeans version, in Table 9-3.
EJB Version
XML File
PUBLIC Element String
2.0 ejb-jar.xml '-//Sun Microsystems, Inc.//DTD Enterprise JavaBeans 2.0//EN''http://java.sun.com/dtd/ejb-jar_2_0.dtd' 1.1 ejb-jar.xml '-//Sun Microsystems, Inc.//DTD Enterprise JavaBeans 1.1//EN''http://www.java.sun.com/j2ee/dtds/ejb-jar_1_1.dtd'
2.0 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 8.1 weblogic-ejb-jar.xml are as follows:
- description
- weblogic-version
- weblogic-enterprise-bean
- ejb-name
- entity-descriptor | stateless-session-descriptor | stateful-session-descriptor | message-driven-descriptor
- transaction-descriptor
- reference-descriptor
- enable-call-by-reference
- clients-on-same-server
- jndi-name
- security-role-assignment
- transaction-isolation
2.0 weblogic-ejb-jar.xml Elements
- allow-concurrent-calls
- allow-remove-during-transaction
- cache-between-transactions
- cache-type
- client-authentication
- client-cert-authentication
- clients-on-same-server
- concurrency-strategy
- confidentiality
- connection-factory-jndi-name
- create-as-principal-name
- delay-updates-until-end-of-tx
- description
- destination-jndi-name
- disable-warning
- dispatch-policy
- ejb-local-reference-description
- ejb-name
- ejb-reference-description
- ejb-ref-name
- enable-bean-class-redeploy
- enable-call-by-reference
- enable-dynamic-queries
- entity-cache
- entity-cache-name
- entity-cache-ref
- entity-clustering
- entity-descriptor
- estimated-bean-size
- externally-defined
- finders-load-bean
- global-role
- home-call-router-class-name
- home-is-clusterable
- home-load-algorithm
- idempotent-methods
- identity-assertion
- idle-timeout-seconds
- iiop-security-descriptor
- 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-name
- local-jndi-name
- max-beans-in-cache
- max-beans-in-free-pool
- message-driven-descriptor
- method
- method-intf
- method-name
- method-param
- method-params
- passivate-as-principal-name
- persistence
- persistence-use
- persistent-store-dir
- pool
- principal-name
- provider-url
- read-timeout-seconds
- reference-descriptor
- remove-as-principal-name
- replication-type
- res-env-ref-name
- res-ref-name
- resource-description
- resource-env-description
- role-name
- run-as-identity-principal
- run-as-principal-name
- run-as-role-assignment
- security-permission
- security-permission-spec
- security-role-assignment
- session-timeout-seconds
- stateful-session-cache
- stateful-session-clustering
- stateful-session-descriptor
- stateless-bean-call-router-class-name
- stateless-bean-is-clusterable
- stateless-bean-load-algorithm
- stateless-bean-methods-are-idempotent
- stateless-clustering
- stateless-session-descriptor
- transaction-descriptor
- transaction-isolation
- transport-requirements
- trans-timeout-seconds
- type-identifier
- type-storage
- type-version
- .weblogic-ejb-jar
- weblogic-enterprise-bean
allow-concurrent-calls
Range of values: True | False Default value: False Requirements: Requires the server to throw a RemoteException when a stateful session bean instance is currently handling a method call and another (concurrent) method call arrives on the server. Parent elements: weblogic-enterprise-bean
stateful-session-descriptor
Function
The allow-concurrent-calls element specifies whether a stateful session bean instance allows concurrent method calls. By default, allows-concurrent-calls is False. However, when this value is set to True, the EJB container blocks the concurrent method call and allows it to proceed when the previous call has completed.
Example
See stateful-session-descriptor
allow-remove-during-transaction
Range of values: True | False Default value: False Requirements:
Parent elements: weblogic-enterprise-bean
stateful-session-descriptor
Function
The allow-remove-during-transaction element specifies that the remove method on a stateful session bean can be invoked within a transaction context.
Stateful session beans implementing the Synchronization interface should not use this tag and then call remove before the transaction ends. If this is done the EJB container will not invoke the synchronization callbacks.
Example
See stateful-session-descriptor
cache-between-transactions
Range of values: True | False Default value: False Requirements: Optional element. Valid only for entity EJBs. Parent elements: weblogic-enterprise-bean,
entity-descriptor,
entity-cache or entity cache-ref
Function
The cache-between-transactions element, formerly the db-is-shared element, specifies whether the EJB container will cache the persistent data of an entity bean across (between) transactions.
The cache-between-transactions element applies only to entity beans. Specify True to enable the EJB container performs long term caching of the data. Specify False to enable the EJB container to perform short term caching of the data. This is the default setting.
A Read-Only bean ignores the value of the cache-between-transactions element because WebLogic Server always performs long term caching of Read-Only data.
See Controlling Entity Caching for more information.
Example
See persistence.
cache-type
Range of values: NRU | LRU Default value: NRU Requirements:
Parent elements: weblogic-enterprise-bean
stateful-session-cache
Function
The cache-type element specifies the order in which EJBs are removed from the cache. The values are:
- Least recently used (LRU)
- Not recently used (NRU)
The minimum cache size for NRU is 8. If max-beans-in-cache is less than 3, WebLogic Server uses a value of 8 for 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:
Requirements: n/a Parent elements: weblogic-enterprise-bean
iiop-security-descriptor
Function
The client-authentication element specifies whether the EJB supports or requires client authentication.
Example
client-cert-authentication
Range of values: none | supported | required Default value:
Requirements: n/a Parent elements: weblogic-enterprise-bean
iiop-security-descriptor
transport-requirements
Function
The client-cert-authentication element specifies whether the EJB supports or requires client certificate authentication at the transport level.
Example
clients-on-same-server
Range of values: True | False Default value: False Parent elements: weblogic-enterprise-bean
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 Using WebLogic Server Clusters 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>
concurrency-strategy
Range of values: Exclusive | Database | ReadOnly | Optimistic Default value: Database Requirements: Optional element. Valid only for entity EJBs. Parent elements: weblogic-enterprise-bean,
entity-descriptor,
entity-cache or entity-cache-ref
Function
The concurrency-strategy element specifies how the container should manage concurrent access to an entity bean. Set this element to one of four values:
- Exclusive causes WebLogic Server to place an exclusive lock on cached entity EJB instances when the bean is associated with a transaction. Other requests for the EJB instance are block until the transaction completes. This option was the default locking behavior for WebLogic Server versions 3.1 through 5.1.
- Database causes WebLogic Server to defer locking requests for an entity EJB to the underlying datastore. With the Database concurrency strategy, WebLogic Server allocates a separate entity bean instance and allows locking and caching to be handled by the database. This is the default option.
- ReadOnly used for read-only entity beans. Activates a new instance for each transaction so that requests proceed in parallel. WebLogic Server calls ejbLoad() for ReadOnly beans are based on the read-timeout-seconds parameter.
- Optimistic holds no locks in the EJB container or database during a transaction. The EJB container verifies that none of the data updated by a transaction has changed before committing the transaction. If any updated data changed, the EJB container rolls back the transaction.
See 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 Requirements: n/a Parent elements: weblogic-enterprise-bean
iiop-security-descriptor
transport-requirements
Function
The confidentiality element specifies the transport confidentiality requirements for the EJB. Using the confidentiality element ensures that the data is sent between the client and server in such a way as to prevent other entities from observing the contents.
Example
connection-factory-jndi-name
Default value: If this element is not specified, the default is weblogic.jms.MessageDrivenBeanConnectionFactory,which must have been declared in the JMSConnectionFactory stanza in config.xml Requirements:
Parent elements: weblogic-enterprise-bean
message-driven-descriptor
Function
Specifies the JNDI name of the JMS Connection Factory that an MDB looks up to create its queues and topics.
Example
<message-driven-descriptor>
<connection-factory-jndi-name>
weblogic.jms.MessageDrivenBeanConnectionFactory
</connection-factory-jndi-name>
</message-driven-descriptor>
create-as-principal-name
Requirements: Optional Parent elements: weblogic-enterprise-bean
Function
The create-as-principal-name element, 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
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 TransactionReadCommittedUncommitted, 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
Function
The description element is used to provide text that describes the parent element.
Example
<dscription>Contains a description of parent element</description>
destination-jndi-name
Range of values: Valid JNDI name Default value: n/a Requirements: Required. Parent elements: weblogic-enterprise-bean
message-driven-descriptor
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-driven-descriptor.
disable-warning
Range of values: BEA-010001 | BEA-010054 | BEA-010200 | BEA-010202 Default value: n/a Requirements: n/a Parent elements: weblogic-ejb-jar Deployment file: weblogic-ejb-jar.xml
Function
The disable-warning element tells WebLogic Server to 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 Parent elements: weblogic-enterprise-bean
Function
The dispatch-policy element specifies a dispatch policy queue for an EJB; it 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 has not configured 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. For the default thread pool the algorithm is: maxConcurrentMDBs = Min(max-beans-free-pool, default-thread-pool-size/2+1). For all other thread pools, the algorithm is maxConcurrentMDBs = Min(max-beans-free-pool, thread-pool-size). MDBs that run in the default thread pool limit their concurrency to half the thread pool size plus one to prevent dead-locks with other services and applications that share the default thread pool.
Example
<dispatch-policy>queue_name</dispatch-policy>
ejb-local-reference-description
Requirements: Optional element. Parent elements: weblogic-enterprise-bean
reference-descriptor
Function
The ejb-local-reference-description element maps the JNDI name of an EJB in the WebLogic Server instance that is referenced by the bean in the ejb-local-ref element.
Example
<ejb-local-reference-description>
<ejb-ref-name>AdminBean</ejb-ref-name>
<jndi-name>payroll.AdminBean</jndi-name>
</ejb-local-reference-description>
ejb-name
Range of values: Name of an EJB defined in ejb-jar.xml Default value: n/a Requirements: Required element in method stanza. The name must conform to the lexical rules for an NMTOKEN.Not recommend in weblogic-enterprise-bean.For more information, see Using EJB Links. Parent elements: weblogic-enterprise-beanandweblogic-enterprise-bean
method
Function
ejb-name specifies an enterprise bean's name. It contains the value of the bean name assigned 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.
The name must conform to the lexical rules for an NMTOKEN.
Example
See method.
ejb-reference-description
Requirements: Optional element. Parent elements: weblogic-enterprise-bean
reference-descriptor
Function
The ejb-reference-description element maps the JNDI name in the WebLogic Server instance of an EJB that is referenced by the bean in the ejb-reference element.
- ejb-ref-name specifies a resource reference name. This is the reference that the EJB provider places within the ejb-jar.xml deployment file.
- jndi-name specifies the JNDI name of an actual resource factory available in WebLogic Server.
Example
<ejb-reference-description>
<ejb-ref-name>AdminBean</ejb-ref-name>
<jndi-name>payroll.AdminBean</jndi-name>
</ejb-reference-description>
ejb-ref-name
Range of values: n/a Default value: n/a Requirements: Optional element. Parent elements: weblogic-enterprise-bean
reference-description
ejb-reference-description
Function
The ejb-ref-name element specifies a resource reference name. This element is the reference that the EJB provider places within the ejb-jar.xml deployment file.
Example
<reference-descriptor>
<ejb-reference-description>
<ejb-ref-name>AdminBean</ejb-ref-name>
<jndi-name>payroll.AdminBean</jndi-name>
</ejb-reference-description>
</reference-descriptor>
enable-bean-class-redeploy
Default value: False Requirements: Optional element. Parent elements: weblogic-enterprise-jar
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: Two-phase deployment must be used for this feature to be enabled. WebLogic Server ignores the enable-bean-class-redeploy setting will be ignored if two-phase deployment is not used. For information on two-phase deployment, see Two-Phase Deployment Protocol" in Deploying WebLogic Server Applications.
Example
The following XML stanza 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 elements: weblogic-enterprise-bean Deployment file: weblogic-ejb-jar.xml
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 with 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: Method parameters are always passed by value when an EJB is called remotely.
Example
<weblogic-enterprise-bean>
<entity-descriptor>
<ejb-name>AccountBean</ejb-name>
...
<enable-call-by-reference>False</enable-call-by-reference>
</entity-descriptor>
</weblogic-enterprise-bean>
enable-dynamic-queries
Range of values: True | False Default value: True Requirements: Optional element. Parent elements: weblogic-enterprise-bean
entity-descriptor
Function
The optional enable-dynamic-queries element must be set to True to enable dynamic queries. Dynamic queries are only available for use with EJB 2.0 CMP beans.
Example
<enable-dynamic-queries>True</enable-dynamic-queries>
entity-cache
Range of values: n/a (XML stanza) Default value: n/a (XML stanza) Requirements: The entity-cache stanza is optional, and is valid only for entity EJBs. Parent elements: weblogic-enterprise-bean
entity-descriptor
Function
The entity-cache element defines the following options used to cache entity EJB instances within WebLogic Server:
- max-beans-in-cache
- idle-timeout-seconds
- read-timeout-seconds
- concurrency-strategy
See Controlling Entity Caching for more information.
Example
The entity-cache stanza is shown here:
<entity-descriptor>
<entity-cache>
<max-beans-in-cache>...</max-beans-in-cache>
<idle-timeout-seconds>...</idle-timeout-seconds>
<read-timeout-seconds>...<read-timeout-seconds>
<concurrency-strategy>...</concurrency-strategy>
</entity-cache>
<persistence>...</persistence>
<entity-clustering>...</entity-clustering>
</entity-descriptor>
entity-cache-name
Requirements: The value you specify for entity-cache-name must match the name assigned to an application level entity cache in the weblogic-application.xml file. Parent elements: weblogic-enterprise-bean
entity-descriptor
entity-cache-ref
Function
The entity-cache-name element refers to an application level entity cache that the entity bean uses. An application level cache is a cache that may be shared by multiple entity beans in the same application.
For more information about the weblogic-application.xml file, see Enterprise Application Deployment Descriptor Elements" in Developing WebLogic Server Applications.
Example
See entity-cache-ref.
entity-cache-ref
Requirements: The entity-cache-name element in the entity-cache-ref stanza must contain the name of the application level cache. Parent elements: weblogic-enterprise-bean,
entity-descriptor
Function
The entity-cache-ref element refers to an application level entity cache which can cache instances of multiple entity beans that are part of the same application. Application level entity caches are declared in the weblogic-application.xml file.
Use the concurrency-strategyto define the type of concurrency you want the bean to use. The concurrency-strategy must be compatible with the application level cache's caching strategy. For example, an Exclusive cache only supports 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 (XML stanza) Default value: n/a (XML stanza) Requirements: Optional element. Valid only for entity EJBs in a cluster. Parent elements: weblogic-enterprise-bean
entity-descriptor
Function
The entity-clustering element uses the following options to specify how an entity bean will be replicated in a WebLogic cluster:
- home-is-clusterable
- home-load-algorithm
- home call-router-class-name
- use-serverside-stubs
Example
The following excerpt shows the structure of a entity-clustering stanza:
<entity-clustering>
<home-is-clusterable>True</home-is-clusterable>
<home-load-algorithm>random</home-load-algorithm>
<home-call-router-class-name>beanRouter</home-call-router-
class-name>
<use-servside-stubs>True</use-servside-stubs>
</entity-clustering>
entity-descriptor
Requirements: One entity-descriptor stanza is required for each entity EJB in the .jar. Parent elements: weblogic-enterprise-bean
Function
The entity-descriptor element specifies the following deployment parameters that are applicable to an entity bean:
- pool
- entity-cache or entity-cache-ref)
- persistence
- entity-clustering
- invalidation-target
- enable-dynamic-queries
Example
<entity-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 (XML stanza) Default value: n/a (XML stanza) Requirements: n/a Parent elements: weblogic-enterprise-bean
entity-descriptor
Function
The estimated-bean-size- element specifies the estimated average size of the instances of an entity bean in bytes. This is the average number of byte of memory that is consumed by each instance.
Use the estimated-bean-size element when the application level cache you use to cache beans is also specified in terms of bytes and megabytes.
Although you may not know the exact number of bytes consumed by the entity bean instances, specifying a size allows you to give some relative weight to the beans that share a cache at one time.
For example, suppose bean A ad bean B share a cache, called AB-cache, that has a size of 1000 bytes and the size of A is 10 bytes and the size of B is 20 bytes, then the cache can hold at most 100 instances of A and 50 instances of B. If 100 instance s of A are cached, this implies that 0 instances of B are cached.
Example
See entity-cache-ref.
externally-defined
Range of values: True | False Default value:
Requirements: n/a Parent elements: weblogic-ejb-jar
security-role-assignment
Function
The externally-defined element indicates that a particular security role is defined externally in a security realm, outside of the deployment descriptor. Because the security role and 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.
finders-load-bean
Range of values: True | False Default value: True Requirements: Optional element. Valid only for CMP entity EJBs. Parent elements: weblogic-enterprise-bean
entity-descriptor
persistence
Function
The finders-load-bean element determines whether WebLogic Server loads the EJB into the cache after a call to a finder method returns a reference to the bean. If you set this element to True, WebLogic Server immediately loads the bean into the cache if a reference to a bean is returned by the finder. If you set this element to False, WebLogic Server does not automatically load the bean into the cache until the first method invocation; this behavior is consistent with the EJB 1.1 specification.
Example
<entity-descriptor>
<persistence>
<finders-load-bean>True</finders-load-bean>
</persistence>
</entity-descriptor>
global-role
Range of values: True | False Default value: True Parent elements: weblogic-ejb-jar security-role-assignment
Function
The global-role element is deprecated and will be removed in a future version of WebLogic. Use the externally-defined element instead.
The global-role element indicates that a particular security role is defined "globally" in a security realm. Because the security role and its principal-name mapping is defined elsewhere, principal-names are not to be specified in the deployment descriptor. This tag is used as an indicative placeholder instead of a set of principal-name elements.
home-call-router-class-name
Default value: null Requirements: Optional element. Valid only for entity EJBs, stateful session EJBs, and stateless session EJBs in a cluster. Parent elements: weblogic-enterprise-bean,
entity-descriptor,
entity-clusteringandweblogic-enterprise-bean
stateful-session-descriptor
stateful-session-clusteringandweblogic-enterprise-bean
stateless-session-descriptor
stateless-session-clustering
Function
home-call-router-class-name specifies the name of a custom class to use for routing bean method calls. This class must implement weblogic.rmi.cluster.CallRouter(). If specified, an instance of this class is called before each method call. The router class has the opportunity to choose a server to route to based on the method parameters. The class returns either a server name or null, which indicates that the current load algorithm should select the server.
Example
See entity-clustering and stateful-session-clustering.
home-is-clusterable
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
Function
Specifies the algorithm to use for load balancing between replicas of the EJB home. If this element is not defined, WebLogic Server uses the algorithm specified by the server element, weblogic.cluster.defaultLoadAlgorithm.
You can define home-load-algorithm as one of the following values:
- round-robin: Load balancing is performed in a sequential fashion among the servers hosting the bean.
- random: Replicas of the EJB home are deployed randomly among the servers hosting the bean.
- weight-based: Replicas of the EJB home are deployed on host servers according to the servers' current workload.
- 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.
For more information, see Load Balancing for EJBs and RMI Objects" in Using WebLogic Server Clusters.
Example
See entity-clustering and stateful-session-clustering.
idempotent-methods
Requirements: Clustering must be enabled for the EJB. Parent elements: weblogic-ejb-jar
Function
The idempotent-methods element defines list of methods which are written in such a way that repeated calls to the same method with the same arguments has exactly the same effect as a single call. This allows the failover handler to retry a failed call without knowing whether the call actually compiled on the failed server. When you enable idempotent-methods for a method, the EJB stub can automatically recover from any failure as long as it can reach another server hosting the EJB.
To enable clustering, see entity-clustering, stateful-session-clustering, and stateless-clustering.
The methods on stateless session bean homes and read-only entity beans are automatically set to be idempotent. It is not necessary to explicitly specify them as idempotent.
Example
<idempotent-method>
<method>
<description>...</description>
<ejb-name>...</ejb-name>
<method-intf>...</method-intf>
<method-name>...</method-name>
<method-params>...</method-params>
</method>
</idempotent-method>
identity-assertion
Range of values: none | supported | required Default value:
Requirements: n/a Parent elements: weblogic-enterprise-bean
iiop-security-descriptor
Function
The identity-assertion element specifies whether the EJB supports or requires identity assertion.
Example
idle-timeout-seconds
Function
idle-timeout-seconds defines the maximum length of time a stateful EJB should remain in the cache. After this time has elapsed, WebLogic Server removes the bean instance if the number of beans in cache approaches the limit of max-beans-in-cache. The removed bean instances are passivated. See Caching for Stateful Session EJBs for more information.
Example
The following entry indicates that the stateful session EJB, AccountBean, should become eligible for removal if max-beans-in-cache is reached and the bean has been in cache for 20 minutes:
<weblogic-enterprise-bean>
<ejb-name>AccountBean</ejb-name>
<stateful-session-descriptor>
<stateful-session-cache>
<max-beans-in-cache>200</max-beans-in-cache>
<idle-timeout-seconds>1200</idle-timeout-seconds>
</stateful-session-cache>
</stateful-session-descriptor>
</weblogic-enterprise-bean>
iiop-security-descriptor
Range of values: n/a Default value: n/a Requirements: n/a Parent elements: weblogic-enterprise-bean
Function
The iiop-security-descriptor element specifies security configuration parameters at the bean-level. These parameters determine the IIOP security information contained in the IOR.
Example
<iiop-security-descriptor>
<transport-requirements>...</transport-requirements>
<client-authentication>supported<client-authentication><identity-assertion>supported</identity-assertion></iiop-security-descriptor>
initial-beans-in-free-pool
Range of values: 0 to maxBeans Default value: 0 Requirements: Optional element. Valid for stateless session, entity, and message-driven EJBs. Parent elements: weblogic-enterprise-bean,
stateless-session-descriptor or message-bean-descriptor
or entity-descriptor
pool
Function
If you specify a value for initial-beans-in-free-pool, you set the initial size of the pool. WebLogic Server populates the free pool with the specified number of bean instances for every bean class at startup. Populating the free pool in this way improves initial response time for the EJB, because initial requests for the bean can be satisfied without generating a new instance.
Example
See pool.
initial-context-factory
Range of values: True | False Default value: weblogic.jndi.WLInitialContextFactory Requirements:
Parent elements: weblogic-enterprise-bean message-driven-descriptor
Function
Specifies the initial contextFactory that the container will use to create its connection factories.
Example
<message-driven-descriptor>
<initial-context-factory>weblogic.jndi.WLInitialContextFactory
</initial-context-factory>
</message-driven-descriptor>
integrity
Range of values: none | supported | required Default value:
Requirements: n/a. Parent elements: weblogic-enterprise-bean
iiop-security-descriptor
transport-requirements
Function
The integrity element specifies the transport integrity requirements for he EJB. Using the integrity element ensures that the data is sent between the client and server in such a way that it cannot be changed in transit.
Example
invalidation-target
Range of values:
Default value:
Requirements: The target ejb-name must be a Read-Only entity EJB and this element can only be specified for an EJB 2.0 container-managed persistence entity EJB. Parent elements: weblogic-enterprise-bean
entity-descriptor
Function
The invalidation-target element specifies a Read-Only entity EJB that should be invalidated when this container-managed persistence entity EJB has been modified.
Example
<invalidation-target>
<ejb-name>StockReaderEJB</ejb-name>
</invalidation-target>
is-modified-method-name
Range of values: Valid entity EJB method name Default value: None Requirements: Optional element. Valid only for EJB 1.1 entity EJBs. Parent elements: weblogic-enterprise-bean,
entity-descriptor,
persistence
Function
is-modified-method-name specifies a method that WebLogic Server calls when the EJB is stored. The specified method must return a boolean value. If no method is specified, WebLogic Server always assumes that the EJB has been modified and always saves it.
Providing a method and setting it as appropriate can improve performance for EJB 1.1-compliant beans, and for beans that use bean-managed persistence. However, any errors in the method's return value can cause data inconsistency problems.
Note: isModified() is no longer required for 2.0 CMP entity EJBs based on the EJB 2.0 specification However, it still applies to BMP and 1.1 CMP EJBs. When you deploy EJB 2.0 entity beans with container-managed persistence, WebLogic Server automatically detects which EJB fields have been modified, and writes only those fields to the underlying datastore.
Example
<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: n/a Requirements: Optional element. Parent elements: weblogic-ejb-jar
transaction-isolation
Function
isolation-level specifies the isolation level for all of the EJB's database operations. The following are possible values for isolation-level:
- TransactionReadCommittedUncommitted: The transaction can view uncommitted updates from other transactions.
- TransactionReadCommitted: The transaction can view only committed 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.
- TransactionSerializable: Simultaneously executing this transaction multiple times has the same effect as executing the transaction multiple times in a serial fashion.
For Oracle databases only:
- TransactionReadCommittedForUpdate
- TransactionReadCommittedForUpdateNoWait
See Specifying Automatic Key Generation for Oracle for background information on the Oracle-specific isolation-level values.
Refer to your database documentation for more information on the implications and support for different isolation levels.
Example
jms-client-id
Range of values: n/a Default value: ejb-name for the EJB Requirements: Required for durable subscriptions to JMS topics. Parent elements: message-driven-descriptor
Function
Specifies a client ID for the MDB when it connects to a JMS destination.
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 stanza 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 used 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 Requirements: n/a Parent elements: message-driven-descriptor
Function
The jms-polling-interval-seconds specifies the number of seconds between each attempt to reconnect to the JMS destination. Each message-driven bean listens on an associated JMS destination. If the JMS destination is located on another WebLogic Server instance or a foreign JMS provider, then the JMS destination may become unreachable. In this case, the EJB container automatically attempts to reconnect to the JMS Server. Once the JMS Server is up again, the message-driven bean can again receive messages.
Example
<jms-polling-interval-seconds>5</jms-polling-interval-seconds>
jndi-name
Range of values: Valid JNDI name Default value: n/a Requirements: Required in resource-description and ejb-reference-description. Parent elements: weblogic-enterprise-beanandweblogic-enterprise-bean
reference-descriptor
resource-descriptionandweblogic-enterprise-bean
reference-descriptor
ejb-reference-descriptionandweblogic-enterprise-bean
reference-descriptor
ejb-local-reference-description
Function
jndi-name specifies the JNDI name of an actual EJB, resource, or reference available in WebLogic Server.
Assigning a JNDI name to an bean is not recommended.Global JNDI names generate heavy multicast traffic during clustered server startup. See Using EJB Links for the better practice.
Example
See resource-description and ejb-reference-description.
local-jndi-name
Range of values: Valid JNDI name Default value: n/a Requirements: Required if the bean has a local home. Parent elements: weblogic-enterprise-bean
Function
JNDI name for a bean's local home. If a bean has both a remote and a local home, then it must have two JNDI names; one for each home.
Example
<local-jndi-name>weblogic.jndi.WLInitialContext
</local-jndi-name>
max-beans-in-cache
Function
The max-beans-in-cache element specifies the maximum number of objects of this class that are allowed in memory. When max-bean-in-cache is reached, WebLogic Server passivates some EJBs that have not recently been used by a client. max-beans-in-cache also affects when EJBs are removed from the WebLogic Server cache, as described in Caching for 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
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. By default, max-beans-in-free-pool is 1000.
Example
See pool.
message-driven-descriptor
Parent elements: weblogic-enterprise-bean Deployment file: weblogic-ejb-jar.xml
Function
The message-driven-descriptor element associates a message-driven bean with a JMS destination in WebLogic Server. This element specifies the following deployment parameters:
- pool
- destination-jndi-name
- initial-context-factory
- provider-url
- connection-factory-jndi-name
Example
The following example shows the structure of the message-driven-descriptor stanza:
<message-driven-descriptor>
<destination-jndi-name>...</destination-jndi-name>
</message-driven-descriptor>
method
Function
The method element 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
Function
method-intf specifies the EJB interface to which WebLogic Server applies isolation level properties, if the method has the same signature in multiple interfaces.
Example
See method.
method-name
Range of values: Name of an EJB defined in ejb-jar.xml | * Default value: n/a Requirements: Required element in method stanza. Parent elements: weblogic-ejb-jar
transaction-isolation
methodand weblogic-ejb-jar
idempotent-methods
method
Function
method-name specifies the name of an individual EJB method to which WebLogic Server applies isolation level properties. Use the asterisk (*) to specify all methods in the EJB's home and remote interfaces.
If you specify a method-name, the method must be available in the specified ejb-name.
Example
See method.
method-param
Range of values: Fully qualified Java type of a method parameter Default value: n/a Requirements: Required element in method-params. Parent elements: weblogic-ejb-jar
transaction-isolation
method
method-paramsand weblogic-ejb-jar
idempotent-methods
method
method-params
Function
The method-param element specifies the fully qualified Java type name of a method parameter.
Example
See method-params.
method-params
Requirements: Optional stanza. Parent elements: weblogic-ejb-jar
transaction-isolation
methodand weblogic-ejb-jar
idempotent-methods
method
Function
The method-params stanza contains one or more elements that define the Java type name of each of the method's parameters.
Example
The method-params stanza contains one or more method-param elements, as shown here:
<method-params>
<method-param>java.lang.String</method-param>
...
</method-params>
passivate-as-principal-name
Requirements: Optional Parent elements: weblogic-enterprise-bean
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 effects 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
Requirements: Required only for entity EJBs that use container-managed persistence services. Parent elements: weblogic-enterprise-bean,
entity-descriptor
Function
The persistence element defines the following options that determine the persistence type, transaction commit behavior, and ejbLoad() and ejbStore() behavior for entity EJBs in WebLogic Server:
- is-modified-method-name
- delay-updates-until-end-of-tx
- finders-load-bean
- 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>
<db-is-shared>False</db-is-shared>
<persistence-use>...</persistence-use>
</persistence>
</entity-descriptor>
persistence-use
Requirements: Required only for entity EJBs that use container-managed persistence services. Parent elements: weblogic-enterprise-bean,
entity-descriptor,
persistence
Function
The persistence-use element stores an identifier of the persistence type to be used for this particular bean.
Example
<persistence-use>
<type-identifier>WebLogic_CMP_RDBMS</type-identifier>
<type-version>5.1.0</type-version>
<type-storage>META-INF/weblogic-cmp-jar.xml</type-storage>
</persistence-use>
persistent-store-dir
Default value: pstore Requirements: Optional element. Parent elements: weblogic-enterprise-bean
stateful-session-descriptor
Function
Specifies a file system directory where ProductName stores the state of passivated stateful session bean instances. For more information, see Specifying the Persistent Store Directory for Passivated Beans.
Example
<stateful-session-descriptor>
<stateful-session-cache>...</stateful-session-cache>
<allow-concurrent-calls>...</allow-concurrent-calls>
<persistent-store-dir>MyPersistenceDirr</persistent-store-dir>
<stateful-session-clustering>...</stateful-session-clustering>
<allow-remove-during-transaction>
</stateful-session-descriptor>
pool
Range of values: n/a (XML stanza) Default value: n/a (XML stanza) Requirements: Optional element. Parent elements: weblogic-enterprise-bean
stateless-session-descriptor or message-bean-descriptor
or entity-descriptor
Function
The pool element configures the behavior of the WebLogic Server free pool for stateless session and message-driven EJBs. The options are:
- max-beans-in-free-pool
- initial-beans-in-free-pool
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 Requirements: At least one principal-name is required in the security-role-assignment stanza. You may define more than one principal-name for each role-name. Parent elements: weblogic-ejb-jar
security-role-assignment
Function
principal-name specifies the name of an actual WebLogic Server principal to apply to the specified role-name.
Example
provider-url
Range of values: valid name Default value: t3://localhost:7001 Requirements: Used in conjunction with initial-context-factory and connection-factory-jndi-name. Parent elements: weblogic-enterprise-bean
message-driven-descriptor
Function
Specifies the URL provider to be used by the InitialContext. Typically, this is the host port and is used in conjunction with initial-context-factory and connection-factory-jndi-name.
Example
<message-driven-descriptor>
<provider-url>WeblogicURL:Port</provider-url>
</message-driven-descriptor>
read-timeout-seconds
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>
reference-descriptor
Requirements: Optional element. Parent elements: weblogic-enterprise-bean
Function
The reference-descriptor element maps references in the ejb-jar.xml file to the JNDI names of actual resource factories and EJBs available in WebLogic Server.
Example
The reference-descriptor stanza contains one or more additional stanzas to define resource factory references and EJB references. The following shows the organization of these elements:
<reference-descriptor>
<resource-description>
...
</resource-description>
<resource-env-description>
...
</resource-env-description>
<ejb-reference-description>
...
</ejb-reference-description>
<ejb-local-reference-description>
...
</ejb-local-reference-description>
</reference-descriptor>
remove-as-principal-name
Range of values: n/a Default value: n/a Requirements: This parameter only needs to be specified if operations within ejbRemove need more permissions than the anonymous principal would have.
Parent elements: weblogic-enterprise-bean
Function
The remove-as-principal-name element, introduced in WebLogic Server 8.1 SP01, 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 Requirements: Optional element. Parent elements: weblogic-enterprise-bean
stateful-session-descriptor
stateful-session-clustering
Function
The replication-type element determines whether WebLogic Server replicates the state of stateful session EJBs across WebLogic Server instances in a cluster. If you select InMemory, the state of the EJB is replicated. If you select None, the state is not replicated.
Example
See stateful-session-clustering.
res-env-ref-name
Range of values: A valid resource environment reference name from the ejb-jar.xml file Default value: n/a Requirements: n/a Parent elements: weblogic-enterprise-bean
reference-descriptor
resource-env-description
Function
The res-env-ref-name element specifies the name of a resource environment reference.
Example
See resource-description.
res-ref-name
Range of values: A valid resource reference name from the ejb-jar.xml file Default value: n/a Requirements: Required element if the EJB specifies resource references in ejb-jar.xml Parent elements: weblogic-enterprise-bean
reference-descriptor
resource-description
Function
The res-ref-name element specifies the name of a resourcefactory reference. This is the reference that the EJB provider places within the ejb-jar.xml deployment file.
Example
See resource-description.
resource-description
Range of values: n/a (XML stanza) Default value: n/a (XML stanza) Requirements: Optional element. Parent elements: weblogic-enterprise-bean
reference-descriptor
Function
The resource-description element maps a resource reference defined in ejb-jar.xml to the JNDI name of an actual resource available in WebLogic Server.
Example
<reference-descriptor>
<resource-description>
<res-ref-name>. . .</res-ref-name>
<jndi-name>...</jndi-name>
</resource-description>
<ejb-reference-description>
<ejb-ref-name>. . .</ejb-ref-name>
<jndi-name>. . .</jndi-name>
</ejb-reference-description>
</reference-descriptor>
resource-env-description
Requirements: Optional. Parent elements: weblogic-enterprise-bean
reference-descriptor
Function
The resource-env-description element maps a resource environment reference defined in ejb-jar.xml to the JNDI name of an actual resource available in WebLogic Server.
Example
<reference-descriptor>
<resource-env-description>
<res-env-ref-name>. . .</res-env-ref-name>
<jndi-name>...</jndi-name>
<reference-env-description>
</reference-descriptor>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.
role-name
Default value: n/a Requirements: Required element in security-role-assignment. Parent elements: weblogic-enterprise-bean
security-role-assignment
Function
The role-name element identifies an application role name that the EJB provider placed in the ejb-jar.xml deployment file. Subsequent principal-name elements in the stanza map WebLogic Server principals to the specified role-name.
Example
run-as-identity-principal
Default value: n/a Requirements:
Parent elements: weblogic-enterprise-bean
Function
Note that 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
Default value: n/a Requirements:
Parent elements: weblogic-enterprise-bean
Function
The run-as-principal-name 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 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
Default value: n/a Requirements: Required element in security-role-assignment. Corresponds to an EJB role name defined in ejb-jar.xml Parent elements: weblogic-enterprise-bean
security-role-assignment
Function
The run-as-role-assignment element is used to map 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 in 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, i.e. 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
Requirements:
Parent elements: weblogic-ejb-jar
Function
The security-permission element specifies a security permission that is associated with a J2EE Sandbox.
For more information, see Sun's implementation of the security permission specification:
http://java.sun.com/j2se/1.3/docs/guide/security/PolicyFiles.html#FileSyntax
Example
<security-permission>
<description>Optional explanation goes here</description>
<security-permission-spec>
...
</security-permission-spec>
</security-permission>
security-permission-spec
Range of values: n/a (XML stanza) Default value: n/a (XML stanza) Requirements: n/a Parent elements: security-permission
Function
The security-permission-spec element specifies a single security permission based on the Security policy file syntax.
For more information, see Sun's implementation of the security permission specification:
http://java.sun.com/j2se/1.3/docs/guide/security/PolicyFiles.html#FileSyntax
Example
To grant the "read" permission to "java.vm.version", and prevent it from being overwritten:
- 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>- Modify the startWeblogic script to start the server using this option:
JAVA_OPTIONS=-Djava.security.manager
- Create a directory named lib in your domain directory.
- 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
Requirements: Required element if ejb-jar.xml defines application roles. Parent elements: weblogic-ejb-jar
Function
The security-role-assignment element maps application roles in the ejb-jar.xml file to the names of security principals available in WebLogic Server.
Example
<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>
session-timeout-seconds
Default: idle-timeout-sections Parent elements: weblogic-enterprise-bean
stateful-session-descriptor
stateful-session-cache
Function
This element 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>
stateful-session-cache
Requirements: The stateful-session-cache stanza is optional, and is valid only for stateful session EJBs. Parent elements: weblogic-enterprise-bean,
stateful-session-descriptor
Function
The stateful-session-cache element defines the following options used to cache stateful session EJB instances within WebLogic Server.
- max-beans-in-cache
- idle-timeout-seconds
- session-timeout-sections
- cache-type
See Caching for 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
Requirements: Optional element. Valid only for stateful session EJBs in a cluster. Parent elements: weblogic-enterprise-bean,
stateful-session-descriptor
Function
The stateful-session-clustering stanza element specifies 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
Requirements: One stateful-session-descriptor stanza is required for each stateful session EJB in the .jar. Parent elements: weblogic-enterprise-bean
Function
The stateless-session-descriptor element defines deployment behaviors, such as caching, clustering, and persistence, for stateless session EJBs in WebLogic Server.
:Example
<stateful-session-descriptor>
<stateful-session-cache>...</stateful-session-cache>
<allow-concurrent-calls>...</allow-concurrent-calls>
<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
Default value: n/a Requirements: Optional element. Valid only for stateless session EJBs in a cluster. Parent elements: weblogic-enterprise-bean,
stateless-session-descriptor
stateless-clustering
Function
Specifies the name of a custom class to use for routing bean method calls. This class must implement weblogic.rmi.cluster.CallRouter(). If specified, an instance of this class is called before each method call. The router class has the opportunity to choose a server to route to based on the method parameters. The class returns either a server name or null, which indicates that the current load algorithm should select the server.
Example
See stateless-clustering.
stateless-bean-is-clusterable
Range of values: True | False Default value: True Requirements: Optional element. Parent elements: weblogic-enterprise-bean,
stateless-session-descriptor
stateless-clustering
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 Requirements: Optional element. Valid only for stateless session EJBs in a cluster. Parent elements: weblogic-enterprise-bean,
stateless-session-descriptor
stateless-clustering
Function
stateless-bean-load-algorithm specifies the algorithm to use for load balancing between replicas of the EJB home.
You can define stateless-bean-load-algorithm as one of the following values:
- round-robin: Load balancing is performed in a sequential fashion among the servers hosting the bean.
- random: Replicas of the EJB home are deployed randomly among the servers hosting the bean.
- weight-based: Replicas of the EJB home are deployed on host servers according to the servers' current workload.
- 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.
For more information, see Load Balancing for EJBs and RMI Objects" in Using WebLogic Server Clusters.
Example
See stateless-clustering.
stateless-bean-methods-are-idempotent
Note: This element is deprecated in this release.
Range of values: True | False Default value: False Requirements: Optional element. Valid only for stateless session EJBs in a cluster. Parent elements: weblogic-enterprise-bean,
stateless-session-descriptor
stateless-clustering
Function
Set stateless-bean-methods-are-idempotent to True only if the bean is written such that repeated calls to the same method with the same arguments has exactly the same effect as a single call. This allows the failover handler to retry a failed call without knowing whether the call actually completed on the failed server. Setting this property to True makes it possible for the bean stub to recover automatically from any failure as long as another server hosting the bean can be reached.
Example
See stateless-clustering.
stateless-clustering
Requirements: Optional element. Valid only for stateless session EJBs in a cluster. Parent elements: weblogic-enterprise-bean,
stateless-session-descriptor
Function
The stateless-clustering element specifies options that determine how WebLogic Server replicates stateless session EJB instances in a cluster.
Example
The following excerpt shows the structure of a stateless-clustering stanza:
<stateless-clustering>
<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
Requirements: One stateless-session-descriptor element is required for each stateless session EJB in the JAR file. Parent elements: weblogic-enterprise-bean
Function
The stateless-session-descriptor element defines deployment 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>
transaction-descriptor
Requirements: Optional element. Parent elements: weblogic-enterprise-bean
Function
The transaction-descriptor element specifies options that define transaction behavior in WebLogic Server. Currently, this stanza includes only one element: trans-timeout-seconds.
Example
<transaction-descriptor>
<trans-timeout-seconds>20</trans-timeout-seconds>
</transaction-descriptor>
transaction-isolation
Requirements: Optional element. Parent elements: weblogic-ejb-jar
Function
Defines method-level transaction isolation settings for an EJB.
Supported Values for Non-Oracle Databases
- TransactionSerializable
Note: Many datastores provide limited support for detecting serialization problems, even for a single user connection. In such cases, even with an transaction-isolation of TransactionSerializable, you may receive exceptions or rollbacks in the EJB client if contention occurs between clients for the same rows. To avoid such exceptions, include code in your client application to catch SQL exceptions, and resolve them appropriately, for instance by restarting the transaction. For Oracle databases, this problem is addressed with Oracle-only settings, as described in
- TransactionReadCommitted
- TransactionReadUncommitted
- TransactionRepeatableRead
Transaction Isolation Settings for Oracle Databases
WebLogic Server provides transaction-isolation settings to avoid serialization problems with Oracle databases. When you use these settings, WebLogic Server uses exclusive database locks in conjunction with Oracle's READ COMMITTED isolation level to provide serializable isolation:
- TransactionReadCommittedForUpdate - This value causes the isolation level to be set to TransactionReadCommitted, and for the duration of the transaction, all SQL SELECT statements executed in any method are executed with FOR UPDATE appended to the statement. This causes the SELECTed rows to be locked for update. This setting prevents the error:
java.sql.SQLException: ORA-08177: can't serialize access for this transaction
which can happen when using the TransactionSerializable isolation with Oracle databases.
- TransactionReadCommittedForUpdateNoWait - This value, introduced in WebLogic Server 7.0, causes the isolation level to be set to TransactionReadCommitted, and for the duration of the transaction, all SQL SELECT statements executed in any method are executed FOR UPDATE NO WAIT appended to them. the statement. This causes the SELECTed rows to be locked for update.
In contrast to the TransactionReadCommittedForUpdate setting TransactionReadCommittedForUpdateNoWait causes Oracle to not wait if the required locks cannot be acquired immediately. If the Oracle DBMS cannot immediately acquire the locks, the SELECT will fail and an exception will be thrown by the Container.
For non-Oracle databases, the value of this element must be one of the following:
For non-Oracle databases, refer to the vendor's documentation for more details about isolation level support.
Example
<transaction-isolation>
<isolation-level>TransactionSerializable</isolation-level>
<method>
<description>...</description>
<ejb-name>...</ejb-name>
<method-intf>...</method-intf>
<method-name>...</method-name>
<method-params>...</method-params>
</method>
</transaction-isolation>
transport-requirements
Requirements: n/a Parent elements: weblogic-enterprise-bean,
iiop-security-descriptor
Function
The transport-requirements element provides the transport requirements for the EJB.
Example
<iiop-security-descriptor>
<transport-requirements>
<confidentiality>supported</confidentiality>
<integrity>supported</integrity>
<client-cert-authorization>suppoted
</client-cert-authentication>
</transport-requirements>
</iiop-security-descriptor>
trans-timeout-seconds
Range of values: 0 to max Default value: 30 Requirements: Optional element. Valid for any type of EJB. Parent elements: weblogic-enterprise-bean,
transaction-descriptor
Function
The trans-timeout-seconds element specifies the maximum duration for an EJB's container-initiated transactions. If a transaction lasts longer than trans-timeout-seconds, WebLogic Server rolls back the transaction.
Example
type-identifier
Function
Specifies identifies an entity EJB persistence type. WebLogic Server RDBMS-based persistence uses the identifier, WebLogic_CMP_RDBMS. If you use a different persistence vendor, consult the vendor's documentation for information on the correct type-identifier.
Example
See persistence-use for an example that shows the complete persistence type definition for WebLogic Server RDBMS-based persistence.
type-storage
Range of values: Valid string Default value: n/a Requirements: Required only for entity EJBs that use container-managed persistence services. Parent elements: weblogic-enterprise-bean,
entity-descriptor,
persistence
persistence-use
Function
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 Requirements: Required for entity EJBs that use container-managed persistence service, if multiple versions of the same persistence type are installed. Parent elements: weblogic-enterprise-bean,
entity-descriptor,
persistence
persistence-use
Function
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.0This element is necessary if multiple versions of the same persistence type are installed.Note: If you use WebLogic Server RDBMS-based persistence, the specified version must exactly match the RDBMS persistence version for the WebLogic Server release. Specifying an incorrect version results in the error:
weblogic.ejb.persistence.PersistenceSetupException: Error initializing the CMP Persistence Type for your bean: No installed Persistence Type matches the signature of (identifier `Weblogic_CMP_RDBMS', version `version_number').
Example
See persistence-use for an example that shows the complete persistence type definition for WebLogic Server RDBMS-based persistence.
use-serverside-stubs
Function
Causes the bean home to use server-side stubs in the context of server.
Example
See the example for entity-clustering.
.weblogic-ejb-jar
Requirements: N/A Parent elements: N/A
Function
weblogic-ejb-jar is the root element of the weblogic component of the EJB deployment descriptor.
weblogic-enterprise-bean
Range of values:
Default value:
Requirements:
Parent elements: weblogic-ejb-jar
Function
The weblogic-enterprise-bean element contains the deployment information for a bean that is available in WebLogic Server.
