|
|
|
|
|
|
| | | |
weblogic-ejb-jar.xml Document Type Definitions
The following sections describe the EJB 5.1 and EJB 6.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.
Note: Use the 6.0 deployment descriptors with the 6.x version of WebLogic Server.
EJB Deployment Descriptors
The EJB deployment descriptors contain structural and application assembly information for an enterprise bean. You specify this information by specifying values for the deployment descriptors in three EJB XML DTD files. These files are:
You package these three XML files with the EJB and other classes into a deployable EJB component, usually a JAR file, called ejb.jar.
The ejb-jar.xml file is based on the deployment descriptors found in Sun Microsystems's ejb.jar.xml file. The other two XML files are weblogic-specific files that are based on the deployment descriptors found in weblogic-ejb-jar.xml and weblogic-cmp-rdbms-jar.xml.
When you edit or create XML deployment files, it is critical to include the correct DOCTYPE header for the deployment file. In particular, using an incorrect PUBLIC element within the DOCTYPE header can result in parser errors that may be difficult to diagnose.
The correct text for the PUBLIC elements for the WebLogic Server-specific weblogic-ejb-jar.xml file are as follows.
The correct text for the PUBLIC elements for the Sun Microsystem-specific ejb-jar.xml file are as follows.
For example, the entire DOCTYPE header for a weblogic-ejb-jar.xml file is as follows:
<!DOCTYPE weblogic-ejb-jar PUBLIC '-//BEA Systems, Inc.//DTD WebLogic 6.0.0 EJB//EN' 'http://www.bea.com/servers/wls600/dtd/weblogic-ejb-jar.dtd'>
XML files with incorrect header information may yield error messages similar to the following, when used with a utility that parses the XML (such as ejbc):
SAXException: This document may not have the identifier `identifier_name'
identifier_name generally includes the invalid text from the PUBLIC element.
Document Type Definitions (DTDs) for Validation
The contents and arrangement of elements in your XML files must conform to the Document Type Definition (DTD) for each file you use. WebLogic Server ignores the DTDs embedded within the DOCTYPE header of XML deployment files, and instead uses the DTD locations that were installed along with the server. However, the DOCTYPE header information must include a valid URL syntax in order to avoid parser errors.
Note: Most browsers do not display the contents of files having the .dtd extension. To view the DTD file contents in your browser, save the links as text files and view them with a text editor.
weblogic-ejb-jar.xml
The following links provide the new public DTD locations for the weblogic-ejb-jar.xml deployment files used with the WebLogic Server:
http://www.bea.com/servers/wls600/dtd/weblogic-ejb-jar.dtd contains the DTD used for creating weblogic-ejb-jar.xml, which defines EJB properties used for deployment to WebLogic Server.
weblogic-ejb-jar.dtd contains the DTD used for creating weblogic-ejb-jar.xml, which defines EJB properties used for deployment to WebLogic Server. This file is located at http://www.bea.com/servers/wls510/dtd/weblogic-ejb-jar.dtd
ejb-jar.xml
The following links provide the public DTD locations for the ejb-jar.xml deployment files used with WebLogic Server:
http://www.java.sun.com/dtd/ejb-jar_2_0.dtd contains the DTD for the standard ejb-jar.xml deployment file, required for all EJBs. This DTD is maintained as part of the JavaSoft EJB 2.0 specification; refer to the JavaSoft specification for information about the elements used in ejb-jar.dtd.
ejb-jar.dtd contains the DTD for the standard ejb-jar.xml deployment file, required for all EJBs. This DTD is maintained as part of the JavaSoft EJB 1.1 specification; refer to the JavaSoft specification for information about the elements used in ejb-jar.dtd.
Note: Refer to the appropriate JavaSoft EJB specification for a description of the ejb-jar.xml deployment descriptors.
Changed EJB Deployment Elements in WebLogic Server 6.1
These changes were made to weblogic-ejb-jar.xml in WebLogic Server 6.1:
6.0 weblogic-ejb-jar.xml Deployment Descriptor File Structure
The WebLogic Server 6.0 weblogic-ejb-jar.xml deployment descriptor file describes the elements that are unique to WebLogic Server. Although you can use both versions of the deployment descriptors in the EJB container, the WebLogic Server 6.0 version of weblogic-ejb-jar.xml is different from the version shipped with WebLogic Server Version 5.1.
The WebLogic Serve 6.0 weblogic-ejb-jar.xml includes elements for enabling stateful session EJB replication, configuring entity EJB locking behavior, and assigning JMS Queue and Topic names for message-driven beans.
The top level elements in the WebLogic Server 6.0 weblogic-ejb-jar.xml are as follows:
6.0 weblogic-ejb-jar.xml Deployment Descriptor Elements
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.
|
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:
Example
The following example shows the structure of the cache-type element.
<stateful-session-cache>
<cache-type>NRU</cache-type>
</stateful-session-cache>
Function
The connection-factory-jndi-name element specifies the JNDI name of the JMS Connection Factory that the message-driven bean should look up to create its queues and topics. If this element is not specified, the default is the weblogic.jms.MessageDrivenBeanConnectionFactory in config.xml.
Example
<message-driven-descriptor>
<connection-factory-jndi-name>weblogic.jms.MessageDrivenBean
ConnectionFactory</connection-factory-jndi-name>
</message-driven-descriptor>
concurrency-strategy
Function
The concurrency-strategy element specifies how the container should manage concurrent access to an entity bean. Set this element to one of three values:
SeeLocking Services for Entity EJBs for more information on the Exclusive and Database locking behaviors. SeeRead-Only Multicast Invalidation for more information about read-only entity EJBs.
Example
The following entry identifies the AccountBean class as a read-only entity EJB:
<weblogic-enterprise-bean>
<ejb-name>AccountBean</ejb-name>
<entity-descriptor>
<entity-cache>
<concurrency-strategy>ReadOnly</concurrency-strategy>
</entity-cache>
</entity-descriptor>
</weblogic-enterprise-bean>
db-is-shared
|
Range of values: |
true | false |
|
Default value: |
true |
|
Requirements: |
Optional element. Valid only for entity EJBs. |
|
Parent elements: |
weblogic-enterprise-bean, |
Function
The db-is-shared element applies only to entity beans. When it is set to true, WebLogic Server assumes that EJB data can be modified between transactions and reloads the data at the beginning of each transaction. When set to false, WebLogic Server assumes that it has exclusive access to the EJB data in the persistent store. See Using db-is-shared to Limit Calls to ejbLoad() for more information.
Example
See persistence.
delay-updates-until-end-of-tx
|
Range of values: |
true | false |
|
Default value: |
true |
|
Requirements: |
Optional element. Valid only for entity EJBs. |
|
Parent elements: |
weblogic-enterprise-bean, |
Function
Set the delay-updates-until-end-of-tx element to true (the default) to update the persistent store of all beans in a transaction at the completion of the transaction. This setting generally improves performance by avoiding unnecessary updates. However, it does not preserve the ordering of database updates within a database transaction.
If your datastore uses an isolation level of TRANSACTION_READ_UNCOMMITTED, you may want to allow other database users to view the intermediate results of in-progress transactions. In this case, set delay-updates-until-end-of-tx to false to update the bean's persistent store at the conclusion of each method invoke. See ejbLoad() and ejbStore() Behavior for Entity EJBs for more information.
Note: Setting delay-updates-until-end-of-tx to false does not cause database updates to be "committed" to the database after each method invoke; they are only sent to the database. Updates are committed or rolled back in the database only at the conclusion of the transaction.
Example
The following example shows a delay-updates-until-end-of-tx stanza.
<entity-descriptor>
<persistence>
<delay-updates-until-end-of-tx>false</delay-updates-until-end-of- tx>
</persistence>
</entity-descriptor>
description
|
Range of values: |
n/a |
|
Default value: |
n/a |
|
Requirements: |
n/a |
|
Parent elements: |
weblogic-ejb-jar |
Function
The description element is used to provide text that describes the parent element.
Example
The following examples specifies the description element.
destination-jndi-name
|
Range of values: |
Valid JNDI name |
|
Default value: |
n/a |
|
Requirements: |
Required in message-driven-descriptor. |
|
Parent elements: |
weblogic-enterprise-bean |
Function
The destination-jndi-name element specifies the JNDI name used to associate a message-driven bean with an actual JMS Queue or Topic deployed in the in WebLogic Server JNDI tree.
Example
See message-driven-descriptor.
ejb-name
|
Range of values: |
Name of an EJB defined in ejb-jar.xml |
|
Default value: |
n/a |
|
Requirements: |
Required element in method stanza. The name must conform to the lexical rules for an NMTOKEN. |
|
Parent elements: |
weblogic-enterprise-bean |
Function
ejb-name specifies the name of an EJB to which WebLogic Server applies isolation level properties. This name is assigned by the ejb-jar file's deployment descriptor. The name must be unique among the names of the enterprise beans in the same ejb.jar file. The enterprise bean code does not depend on the name; therefore the name can be changed during the application-assembly process without breaking the enterprise bean's function. There is no built-in relationship between the ejb-name in the deployment descriptor and the JNDI name that the deployer will assign to the enterprise bean's home.
Example
See method.
ejb-reference-description
|
Range of values: |
n/a (XML stanza) |
|
Default value: |
n/a (XML stanza) |
|
Requirements: |
Optional element. |
|
Parent elements: |
weblogic-enterprise-bean |
Function
The ejb-reference-description element maps the JNDI name in the WebLogic Server of an EJB that is referenced by the bean in the ejb-reference element.
Example
The ejb-reference-description stanza is shown here:
<ejb-reference-description>
<ejb-ref-name>AdminBean</ejb-ref-name>
<jndi-name>payroll.AdminBean</jndi-name>
</ejb-reference-description>
ejb-ref-name
|
Range of values: |
n/a |
|
Default value: |
n/a |
|
Requirements: |
Optional element. |
|
Parent elements: |
weblogic-enterprise-bean |
Function
The ejb-ref-name element specifies a resource reference name. This element is the reference that the EJB provider places within the ejb-jar.xml deployment file.
Example
The ejb-ref-name stanza is shown here:
<reference-descriptor>
<ejb-reference-description>
<ejb-ref-name>AdminBean</ejb-ref-name>
<jndi-name>payroll.AdminBean</jndi-name>
</ejb-reference-description>
</reference-descriptor>
ejb-local-reference-description
|
Range of values: |
n/a (XML stanza) |
|
Default value: |
n/a (XML stanza) |
|
Requirements: |
Optional element. |
|
Parent elements: |
weblogic-enterprise-bean |
Function
The ejb-local-reference-description element maps the JNDI name of an EJB in the WebLogic Server that is referenced by the bean in the ejb-local ref element.
Example
The following example shows the ejb-local-reference-description element.
<ejb-local-reference-description>
<ejb-ref-name>AdminBean</ejb-ref-name>
<jndi-name>payroll.AdminBean</jndi-name>
</ejb-local-reference-description>
enable-call-by-reference
|
Range of values: |
true | false |
|
Default value: |
true |
|
Requirements: |
Optional element. |
|
Parent elements: |
weblogic-enterprise-bean ejb-reference-description |
Function
By default, EJB methods called from within the same EAR pass arguments by reference. This increases the performance of method invocation because parameters are not copied.
If you set enable-call-by-reference to False, parameters to the EJB methods are copied (pass-by-value) in accordance with the EJB 1.1 specification. Pass by value is always necessary when the EJB is called remotely (not from within the same application).
Example
The following example enables pass-by-value for EJB methods:
<weblogic-enterprise-bean>
<ejb-name>AccountBean</ejb-name>
...
<enable-call-by-reference>false</enable-call-by-reference>
</weblogic-enterprise-bean>
entity-cache
Function
The entity-cache element defines the following options used to cache entity EJB instances within WebLogic Server:
See EJB Life Cycle for a general discussion of the caching services available in WebLogic Server.
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>
<lifecycle>...</lifecycle>
<persistence>...</persistence>
<entity-clustering>...</entity-clustering>
</entity-descriptor>
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, |
Function
The entity-clustering element uses the following options to specify how an entity bean will be replicated in a WebLogic cluster:
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-n ame>
</entity-clustering>
entity-descriptor
|
Range of values: |
n/a (XML stanza) |
|
Default value: |
n/a (XML stanza) |
|
Requirements: |
One entity-descriptor stanza is required for each entity EJB in the .jar. |
|
Parent elements: |
weblogic-enterprise-bean |
Function
The entity-descriptor element specifies the following deployment parameters that are applicable to an entity bean:
Example
The following example shows the structure of the entity-descriptor stanza:
<entity-descriptor>
<entity-cache>...</entity-cache>
<lifecycle>...</lifecycle>
<persistence>...</persistence>
<entity-clustering>...</entity-clustering>
</entity-descriptor>
finders-load
|
Range of values: |
true | false |
|
Default value: |
true |
|
Requirements: |
Optional element. Valid only for CMP entity EJBs. |
|
Parent elements: |
weblogic-enterprise-bean, |
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 load automatically load the bean into the cache until the first method invocation; this behavior is consistent with the EJB 1.1 specification.
Example
The following entry specifies that EJBs are loaded into the WebLogic Server cache automatically when a finder method returns a reference to the bean:
<entity-descriptor>
<persistence>
<finders-load-bean>true</finders-load-bean>
</persistence>
</entity-descriptor>
home-call-router-class-name
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
Use home-is-clusterable to specify whether the home interface of an entity, stateless session, or stateful session bean is clustered.
When home-is-clusterable is true for an EJB deployed to a cluster, each server instance binds the bean's home interface to its cluster JNDI tree under the same name. When a client requests the bean's home from the cluster, the server instance that does the look-up returns a EJBHome stub that has a reference to the home on each server.
When the client issues a create() or find() call, the stub routes selects a server from the replica list in accordance with the load balancing algorithm, and routes the call to the home interface on that server. The selected home interface receives the call, and creates a bean instance on that server instance and executes the call, creating an instance of the bean.
Example
See entity-clustering.
home-load-algorithm
Function
home-load-algorithm specifies the algorithm to use for load balancing between replicas of the EJB home. If this property is not defined, WebLogic Server uses the algorithm specified by the server property, weblogic.cluster.defaultLoadAlgorithm.
You can define home-load-algorithm as one of the following values:
Example
See entity-clustering and stateful-session-clustering.
idle-timeout-seconds
Function
idle-timeout-seconds defines the maximum length of time a stateful session EJB should remain in cache. After this time has elapsed, WebLogic Server removes the bean instance if the number of beans in cache approaches the limit of max-beans-in-cache. The removed bean instances are passivated. See EJB Life Cycle for more information.
Note: Although idle-timeout-seconds appears in the entity-cache stanza, WebLogic Server 6. 1 does not uses its value in managing the lifecycle of entity EJBs— 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>
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
Function
The initial-context-factory element specifies the initial contextFactory that the container will use to create its connection factories. If initial-context-factory is not specified, the default will be weblogic.jndi.WLInitialContextFactory.
Example
The following example specifies the initial-context-factory element.
<message-driven-descriptor>
<initial-context-factory>weblogic.jndi.WLInitialContextFactory </initial-context-factory>
</message-driven-descriptor>
invalidation-target
Function
The invalidation-target element specifies a Read-Only entity EJB that should be invalidated when this container-managed persistence entity EJB has been modified.
Example
The following entry specifies that the EJB named StockReaderEJB should be invalidated when the EJB has been modified.
<invalidation-target>
<ejb-name>StockReaderEJB</ejb-name>
</invalidation-target>
is-modified-method-name
|
Range of values: |
Valid entity EJB method name |
|
Default value: |
None |
|
Requirements: |
Optional element. Valid only for entity EJBs. |
|
Parent elements: |
weblogic-enterprise-bean, |
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. SeeUsing is-modified-method-name to Limit Calls to ejbStore() (EJB 1.1 Only) for more information.
Note: isModified() is no longer required for 2.0 CMP entity EJBs based on the EJB 2.0 specification However, it still applies to BMP and 1.1 CMP EJBs. When you deploy EJB 2.0 entity beans with container-managed persistence, WebLogic Server automatically detects which EJB fields have been modified, and writes only those fields to the underlying datastore.
Example
The following entry specifies that the EJB method named semidivine will notify WebLogic Server when the EJB has been modified:
<entity-descriptor>
<persistence>
<is-modified-method-name>semidivine</is-modified-method-name>
</persistence>
</entity-descriptor>
isolation-level
|
Range of values: |
Serializable | ReadCommitted | ReadUncommitted | RepeatableRead |
|
Default value: |
n/a |
|
Requirements: |
Optional element. |
|
Parent elements: |
weblogic-ejb-jar |
Function
isolation-level specifies the isolation level for all of the EJB's database operations. The following are possible values for isolation-level:
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: |
Necessary for durable subscriptions to JMS topics. |
|
Parent elements: |
weblogic-enterprise-bean |
Function
The jms-client-id element specifies the client ID associated with the message-driven bean. This ID is necessary for durable subscriptions to JMS topics.
The JMS specification allows JMS consumers to specify an associated ID. A message-driven bean with a durable subscription needs an associated client ID. If you use a separate connection factory, you can set the client ID on the connection factory. In this case, the message-driven bean uses this client ID.
If the associated client ID does not have a client ID or if you are using the default connection factory, the message-driven bean uses the jms-client-id value as its client ID.
Example
The following example specifies the use of the jms-client-id element.
<jms-client-id>MyClientID</jms-client-id>
jms-polling-interval-seconds
|
Range of values: |
none |
|
Default value: |
10 seconds |
|
Requirements: |
.none |
|
Parent elements: |
weblogic-enterprise-bean |
Function
The jms-polling-interval-seconds element determines the number of seconds between each attempt by WebLogic Server 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, 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 running again the message-driven bean can again receive JMS messages.
Refer to your database documentation for more information on the implications and support for different isolation levels.
Example
The following example specifies the use of the jms-polling-interval-seconds element.
<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-bean and weblogic-enterprise-bean and weblogic-enterprise-bean |
Function
jndi-name specifies the JNDI name of an actual EJB, resource, or reference available in WebLogic Server.
Example
See resource-description and ejb-reference-description.
local-jndi-name
|
Range of values: |
Valid JNDI name |
|
Default value: |
n/a |
|
Requirements: |
Required if the bean has a local home. |
|
Parent elements: |
weblogic-enterprise-bean |
Function
The local-jndi-name element specifies a jndi-name for a bean's local home. If a bean has both a remote and a local home, then it must have two JNDI names; one for each home.
Example
The following example shows the specifies the local-jndi-name element.
<local-jndi-name>weblogic.jndi.WLInitialContext </local-jndi-name>
lifecycle
Function
The lifecycle element defines options that affect the lifecycle of stateful and entity EJB instances within WebLogic Server. Currently, the lifecycle element includes only one element: passivation-strategy.
Example
The following example shows the specifies the lifecycle element.
<entity-descriptor>
<lifecycle>
<passivation-strategy>...</passivation-strategy>
</lifecycle>
</entity-descriptor>
Function
The max-beans-in-cache element specifies the maximum number of objects of this class that are allowed in memory. When max-bean-in-cache is reached, WebLogic Server passivates some EJBs that have not been recently used by a client. max-beans-in-cache also affects when EJBs are removed from the WebLogic Server cache, as described inLocking Services for Entity EJBs.
Example
The following entry enables WebLogic Server to cache a maximum of 200 instances of the AccountBean class:
<weblogic-enterprise-bean>
<ejb-name>AccountBean</ejb-name>
<entity-descriptor>
<entity-cache>
<max-beans-in-cache>200</max-beans-in-cache>
</entity-cache>
</entity-descriptor>
</weblogic-enterprise-bean>
Function
WebLogic Server maintains a free pool of EJBs for every stateless session, message-driven, and entity bean class max-beans-in-free-pool limits the size of the free pool. For more information, see EJB Life Cycle.
Example
See pool.
message-driven-descriptor
|
Range of values: |
n/a (XML stanza) |
|
Default value: |
n/a (XML stanza) |
|
Requirements: |
|
|
Parent elements: |
weblogic-enterprise-bean |
Function
The message-driven-descriptor element associates a message-driven bean with a JMS destination in WebLogic Server. This element specifies the following deployment parameters:
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
The method stanza can contain the elements shown here:
<method>
<description>...</description>
<ejb-name>...</ejb-name>
<method-intf>...</method-intf>
<method-name>...</method-name>
<method-params>...</method-params>
</method>
method-intf
|
Range of values: |
Home | Remote | Local | Localhome |
|
Default value: |
n/a |
|
Requirements: |
Optional element. |
|
Parent elements: |
weblogic-ejb-jar |
Function
method-intf specifies the EJB interface to which WebLogic Server applies isolation level properties. Use this element to differentiate between methods having the same signature in the EJB's home, remote, and local 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 |
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 |
Function
The method-param element specifies the fully qualified Java type name of a method parameter.
Example
See method-params.
method-params
|
Range of values: |
n/a (XML stanza) |
|
Default value: |
n/a (XML stanza) |
|
Requirements: |
Optional stanza. |
|
Parent elements: |
weblogic-ejb-jar |
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>
passivation-strategy
|
Range of values: |
default | transaction |
|
Default value: |
default |
|
Requirements: |
Optional element. Valid only for entity EJBs. |
|
Parent elements: |
weblogic-enterprise-bean, |
Function
The passivation-strategy element determines whether or not WebLogic Server maintains the intermediate state of entity EJBs in its cache. See Locking Services for Entity EJBs for more information.
Example
The following entry reverts to WebLogic Server locking and caching behavior:
<entity-descriptor>
<lifecycle>
<passivation-strategy>default</passivation-strategy>
</lifecycle>
</entity-descriptor>
persistence
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:
Example
The following example specifies the persistence element.
<entity-descriptor> <persistence> <is-modified-method-name>... </is-modified-method-name> <delay-updates-until-end-of-tx>... </delay-updates-until-end-of-tx> <finders-load-bean>...</finders-load-bean> <persistence-type>...</persistence-type> <db-is-shared>...</db-is-shared> <persistence-use>...</persistence-use> </persistence> </entity-descriptor>
persistence-type
Function
Defines a persistence service that the entity EJB can use. You can define multiple persistence-type stanzas in weblogic-ejb-jar.xml for testing your EJB with multiple persistence services. At deployment, the bean uses the persistence service defined in persistence-use.
persistence-type includes these elements:
Example
<persistence-type> <type-identifier>WebLogic_CMP_RDBMS </type-identifier> <type-version>5.1.0</type-version> <type-storage>META-INF\weblogic-cmp-rdbms-jar.xml </type-storage> </persistence-type>
persistence-use
Function
Defines the persistence service used for the entity bean.
Example
<persistence-use> <type-identifier>WebLogic_CMP_RDBMS</type-identifier> <type-version>5.1.0</type-version> </persistence-use>
persistent-store-dir
|
Range of values: |
Fully qualified filesystem path |
|
Default value: |
n/a |
|
Requirements: |
Optional element. |
|
Parent elements: |
weblogic-enterprise-bean |
Function
The persistent-store-dir element specifies a file system directory where WebLogic Server stores the state of passivated stateful session bean instances.
Example
See stateful-session-descriptor.
pool
Function
The pool element configures the behavior of the WebLogic Server free pool for EJBs. You can configure:
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 |
|
Requirements: |
At least one principal-name is required in the security-role-assignment stanza. You may define more than one principal-name for each role-name. |
|
Parent elements: |
weblogic-enterprise-bean |
Function
principal-name specifies the name of an actual WebLogic Server principal to apply to the specified role-name.
Example
provider-url
Function
The provider-url element specifies the URL provider to be used by the InitialContext. Typically, this is the host:port and used in conjunction with initial-context-factory and connection-factory-jndi-name.
Example
The following example specifies the provider-url element.
<message-driven-descriptor> <provider-url>WeblogicURL:Port</provider-url> </message-driven-descriptor>
read-timeout-seconds
Function
The read-timeout-seconds element specifies the number of seconds between ejbLoad() calls on a Read-Only entity bean. A setting of 0 causes WebLogic Server to 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
|
Range of values: |
n/a (XML stanza) |
|
Default value: |
n/a (XML stanza) |
|
Requirements: |
Optional element. |
|
Parent elements: |
weblogic-enterprise-bean |
Function
The reference-descriptor element maps references in the ejb-jar.xml file to the JNDI names of actual resource factories and EJBs available in WebLogic Server.
Example
The reference-descriptor stanza contains one or more additional stanzas to define resource factory references and EJB references. The following shows the organization of these elements:
<reference-descriptor>
<resource-description>
...
</resource-description>
<ejb-reference-description>
...
</ejb-reference-description>
</reference-descriptor>
relationship-description
This element is no longer supported in WebLogic Server.
replication-type
Function
The replication-type element determines whether WebLogic Server replicates the state of stateful session EJBs across WebLogic Server instances in a cluster. If you select InMemory, the state of the EJB is replicated. If you select None, the state is not replicated.
See In-Memory Replication for Stateful Session EJBs for more information.
Example
See stateful-session-clustering.
res-env-ref-name
Function
The res-env-ref-name element specifies the name of a resource environment reference.
Example
See resource-description.
res-ref-name
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 |
Function
The resource-description element maps a resource reference defined in ejb-jar.xml to the JNDI name of an actual resource available in WebLogic Server.
Example
The resource-description stanza can contain additional elements as shown here:
<reference-descriptor>
<resource-description>
<res-ref-name>. . .</res-ref-name>
<jndi-name>...</jndi-name>
</resource-description>
<ejb-reference-description>
<ejb-ref-name>. . .</ejb-ref-name>
<jndi-name>. . .</jndi-name>
</ejb-reference-description>
</reference-descriptor>
resource-env-description
|
Range of values: |
n/a (XML stanza) |
|
Default value: |
n/a (XML stanza) |
|
Requirements: |
Optional element. |
|
Parent elements: |
weblogic-enterprise-bean |
Function
The resource-env-description element maps a resource environment reference defined in ejb-jar.xml to the JNDI name of an actual resource available in WebLogic Server.
Example
The resource-env-description stanza can contain additional elements as shown here:
<reference-descriptor>
<resource-env-description>
<res-env-ref-name>. . .</res-env-ref-name>
<jndi-name>...</jndi-name>
<reference-env-description>
</reference-descriptor>
role-name
|
Range of values: |
An EJB role name defined in ejb-jar.xml |
|
Default value: |
n/a |
|
Requirements: |
Required element in security-role-assignment. |
|
Parent elements: |
weblogic-enterprise-bean |
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
Note: This element has been deprecated. It is here for backward compatibility only.
|
Range of values: |
Principal that will be used as the identity as defined in ejb-jar.xml |
|
Default value: |
n/a |
|
Requirements: |
Required element in security-role-assignment. |
|
Parent elements: |
weblogic-enterprise-bean |
Function
The run-as-identity-principal element specifies the principal to be used as the identity for beans that have a security-identity.run-as-specified-identity set in the ejb-jar.xml.
The principal named in this element must be one of the principals mapped to the run-as-specified--identity role.
Example
<weblogic-ejb-jar>
<weblogic-enterprise-bean>
<run-as-identity-principal>..</run-as-identity-principal>
</weblogic-enterprise-bean>
</weblogic-ejb-jar>
security-role-assignment
|
Range of values: |
n/a (XML stanza) |
|
Default value: |
n/a (XML stanza) |
|
Requirements: |
Required element if ejb-jar.xml defines application roles. |
|
Parent elements: |
N/A |
Function
The security-role-assignment stanza maps application roles in the ejb-jar.xml file to the names of security principals available in WebLogic Server.
Example
The security-role-assignment stanza can contain one or more of the following elements:
<security-role-assignment>
<role-name>PayrollAdmin</role-name>
<principal-name>Tanya</principal-name>
<principal-name>system</principal-name>
...
</security-role-assignment>
stateful-session-cache
Function
The stateful-session-cache element defines the following options used to cache stateful session EJB instances within WebLogic Server.
SeeEJB Life Cycle for a general discussion of the caching services available in WebLogic Server.
Example
The following example shows how to specify the stateful-session-cache element
<stateful-session-cache>
<max-beans-in-cache>...</max-beans-in-cache>
<idle-timeout-seconds>...</idle-timeout-seconds>
<cache-type>...<cache-type>
</stateful-session-cache>
stateful-session-clustering
Function
The stateful-session-clustering stanza element specifies the following options that determine how WebLogic Server replicates stateful session EJB instances in a cluster:
Example
The following excerpt shows the structure of a entity-clustering stanza:
<stateful-session-clustering>
<home-is-clusterable>true</home-is-clusterable>
<home-load-algorithm>random</home-load-algorithm>
<home-call-router-class-name>beanRouter</home-call-router-class-n ame>
<replication-type>InMemory</replication-type>
</stateful-session-clustering>
stateful-session-descriptor
Function
The stateful-session-descriptor element specifies the following deployment parameters that are applicable for stateful session EJBs in WebLogic Server:
Example
The following example shows the structure of the stateful-session-descriptor stanza:
<stateful-session-descriptor>
<stateful-session-cache>...</stateful-session-cache>
<lifecycle>...</lifecycle>
<persistence>...</persistence>
<allow-concurrent-calls>...</allow-concurrent-calls>
<persistent-store-dir>/weblogic/myserver</persistent-store-dir>
<stateful-session-clustering>...</stateful-session-clustering>
</stateful-session-descriptor>
stateless-bean-call-router-class-name
Function
The stateless-bean-call-router-class-name element specifies the name of a custom class to use for routing bean method calls. This class must implement weblogic.rmi.cluster.CallRouter(). If specified, an instance of this class is called before each method call. The router class has the opportunity to choose a server to route to based on the method parameters. The class returns either a server name or null, which indicates that the current load algorithm should select the server.
Example
See stateless-clustering.
stateless-bean-is-clusterable
Function
Use stateless-bean-is-clusterable to specify whether a stateless session bean's EJBObject interface is clustered. Clustered EJBObjects support load balancing and failover.
If stateless-bean-is-clusterable is true, when a home interface of a clustered stateless session bean creates a bean instance, it returns a EJBObject stub to the client that lists all of the servers in the cluster. Given the stateless nature of the bean, any instance can service any client request
Example
See stateless-clustering.
stateless-bean-load-algorithm
Function
stateless-bean-load-algorithm specifies the algorithm to use for load balancing between replicas of the EJB home. If this property is not defined, WebLogic Server uses the algorithm specified by the server property, weblogic.cluster.defaultLoadAlgorithm.
You can define stateless-bean-load-algorithm as one of the following values:
Example
See stateless-clustering.
stateless-bean-methods-are-idempotent
Function
You can set this element to either true or false. Set stateless-bean-methods-are-idempotent to "true" only if the bean is written such that repeated calls to the same method with the same arguments has exactly the same effect as a single call. This allows the failover handler to retry a failed call without knowing whether the call actually completed on the failed server. Setting this property to true makes it possible for the bean stub to recover automatically from any failure as long as another server hosting the bean can be reached.
Example
See stateless-clustering.
stateless-clustering
Function
The stateless-clustering element specifies the following 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-clusterabl e>
<stateless-bean-load-algorithm>random</stateless-bean-load-algori thm>
<stateless-bean-call-router-class-name>beanRouter</stateless-bean -call-router-class-name>
<stateless-bean-methods-are-idempotent>true</stateless-bean-metho ds-are-idempotent>
</stateless-clustering>
stateless-session-descriptor
Function
The stateless-session-descriptor element defines deployment parameters, such as caching, clustering, and persistence for stateless session EJBs in WebLogic Server.
Example
The following example shows the structure of the stateless-session-descriptor stanza:
<stateless-session-descriptor>
<pool>...</pool>
<stateless-clustering>...</stateless-clustering>
</stateless-session-descriptor>
transaction-descriptor
|
Range of values: |
n/a (XML stanza) |
|
Default value: |
n/a (XML stanza) |
|
Requirements: |
Optional element. |
|
Parent elements: |
weblogic-enterprise-bean |
Function
The transaction-descriptor element specifies options that define transaction behavior in WebLogic Server. Currently, this stanza includes only one element: trans-timeout-seconds.
Example
The following example shows the structure of the transaction-descriptor stanza:
<transaction-descriptor>
<trans-timeout-seconds>20</trans-timeout-seconds>
<transaction-descriptor>
transaction-isolation
|
Range of values: |
n/a (XML stanza) |
|
Default value: |
n/a (XML stanza) |
|
Requirements: |
Optional element. |
|
Parent elements: |
weblogic-ejb-jar |
Function
The transaction-isolation element defines method-level transaction isolation settings for an EJB.
Example
The transaction-isolation stanza can contain the elements shown here:
<transaction-isolation>
<isolation-level>Serializable</isolation-level>
<method>
<description>...</description>
<ejb-name>...</ejb-name>
<method-intf>...</method-intf>
<method-name>...</method-name>
<method-params>...</method-params>
</method>
</transaction-isolation>
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, |
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
The type-identifier element contains text that identifies an entity EJB persistence type. WebLogic Server RDBMS-based persistence uses the identifier, WebLogic_CMP_RDBMS. If you use a different persistence vendor, consult the vendor's documentation for information on the correct type-identifier.
Example
See persistence-type for an example that shows the complete persistence-type definition for WebLogic Server RDBMS-based persistence.
type-storage
Function
The type-storage element defines the full path of the file that stores data for this persistence type. The path must specify the file's location relative to the top level of the EJB's .jar deployment file or deployment directory.
WebLogic Server RDBMS-based persistence generally uses an XML file named weblogic-cmp-rdbms-jar.xml to store persistence data for a bean. This file is stored in the META-INF subdirectory of the .jar file.
Example
See persistence-type for an example that shows the complete persistence-type definition for WebLogic Server RDBMS-based persistence.
type-version
Function
The type-version element identifies the version of the specified persistence type.
Note: If you use WebLogic Server RDBMS-based persistence, the specified version must exactly match the RDBMS persistence version for the WebLogic Server release. Specifying an incorrect version results in the 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-type for an example that shows the complete persistence-type definition for WebLogic Server RDBMS-based persistence.
weblogic-ejb-jar
|
Range of values: |
N/A |
|
Default value: |
N/A |
|
Requirements: |
N/A |
|
Parent elements: |
N/A |
Function
weblogic-ejb-jar is the root element of the weblogic component of the EJB deployment descriptor.
weblogic-enterprise-bean
|
Range of values: |
|
|
Default value: |
|
|
Requirements: |
|
|
Parent elements: |
weblogic-ejb-jar |
Function
The weblogic-enterprise-bean element contains the deployment information for a bean that is available in WebLogic Server.
5.1 weblogic-ejb-jar.xml Deployment Descriptor File Structure
The WebLogic Server 5.1 weblogic-ejb-jar.xml file defines the EJB document type definitions (DTD)s you use with EJB 1.1 beans. These deployment descriptor elements are WebLogic-specific. The top level elements in the WebLogic Server 5.1 weblogic-ejb-jar.xml are as follows:
5.1 weblogic-ejb-jar.xml Deployment Descriptor Elements
The following sections describe WebLogic-Server 5.1 weblogic-ejb-jar.xml deployment descriptor elements.
caching-descriptor
The caching-descriptor stanza affects the number of EJBs in the WebLogic Server cache as well as the length of time before EJBs are passivated or pooled. The entire stanza, as well as each of its elements, is optional. WebLogic Server uses default values where no elements are defined.
The following is a sample caching-descriptor stanza that shows the caching elements described in this section:
<caching-descriptor>
<max-beans-in-free-pool>500</max-beans-in-free-pool>
<initial-beans-in-free-pool>50</initial-beans-in-free-pool>
<max-beans-in-cache>1000</max-beans-in-cache>
<idle-timeout-seconds>20</idle-timeout-seconds>
<cache-strategy>Read-Write</cache-strategy>
<read-timeout-seconds>0</read-timeout-seconds>
</caching-descriptor>
max-beans-in-free-pool
Note: This element is valid only for stateless session EJBs.
WebLogic Server maintains a free pool of EJBs for every bean class. This optional element defines the size of the pool. By default, max-beans-in-free-pool has no limit; the maximum number of beans in the free pool is limited only by the available memory. See Stateful Session EJB Creation in The WebLogic Server EJB Container and Supported Services for more information.
initial-beans-in-free-pool
Note: This element is valid only for stateless session EJBs.
If you specify a value for initial-bean-in-free-pool, WebLogic Server populates the free pool with the specified number of bean instances at startup. Populating the free pool in this way improves initial response time for the EJB, since initial requests for the bean can be satisfied without generating a new instance.
initial-bean-in-free-pool defaults to 0 if the element is not defined.
max-beans-in-cache
Note: This element is valid only for stateful session EJBs and entity EJBs.
This element specifies the maximum number of objects of this class that are allowed in memory. When max-bean-in-cache is reached, WebLogic Server passivates some EJBs that have not been recently used by a client. max-beans-in-cache also affects when EJBs are removed from the WebLogic Server cache, as described in Stateful Session EJB Life Cycle.
The default value of max-beans-in-cache is 100.
idle-timeout-seconds
idle-timeout-seconds defines the maximum length of time a stateful EJB should remain in the cache. After this time has elapsed, WebLogic Server may remove the bean instance if the number of beans in cache approaches the limit of max-beans-in-cache. See EJB Life Cycle for more information.
idle-timeout-seconds defaults to 600 if you do not define the element.
cache-strategy
The cache-strategy element can be one of the following:
The default value is Read-Write. See Setting Entity EJBs to Read-Only for more information.
read-timeout-seconds
The read-timeout-seconds element specifies the number of seconds between ejbLoad() calls on a Read-Only entity bean. By default, read-timeout-seconds is set to 600 seconds. If you set this value to 0, WebLogic Server calls ejbLoad only when the bean is brought into the cache.
persistence-descriptor
The persistence-descriptor stanza specifies persistence options for entity EJBs. The following shows all elements contained in the persistence-descriptor stanza:
<persistence-descriptor>
<is-modified-method-name>. . .</is-modified-method-name>
<delay-updates-until-end-of-tx>. . .</delay-updates-until-end-of-tx>
<persistence-type>
<type-identifier>. . .</type-identifier>
<type-version>. . .</type-version>
<type-storage>. . .</type-storage>
</persistence-type>
<db-is-shared>. . .</db-is-shared>
<stateful-session-persistent-store-dir>
. . .
</stateful-session-persistent-store-dir>
<persistence-use>. . .</persistence-use>
</persistence-descriptor>
is-modified-method-name
is-modified-method-name specifies a method that WebLogic Server calls when the EJB is stored. The specified method must return a boolean value. If no method is specified, WebLogic Server always assumes that the EJB has been modified and always saves it.
Providing a method and setting it as appropriate can improve performance. However, any errors in the method's return value can cause data inconsistency problems. See Using is-modified-method-name to Limit Calls to ejbStore() (EJB 1.1 Only) for more information.
delay-updates-until-end-of-tx
Set this property to true (the default), to update the persistent store of all beans in a transaction at the completion of the transaction. This generally improves performance by avoiding unnecessary updates. However, it does not preserve the ordering of database updates within a database transaction.
If your datastore uses an isolation level of TRANSACTION_READ_UNCOMMITTED, you may want to allow other database users to view the intermediate results of in-progress transactions. In this case, set delay-updates-until-end-of-tx to false to update the bean's persistent store at the conclusion of each method invoke. See ejbLoad() and ejbStore() Behavior for Entity EJBs for more information.
Note: Setting delay-updates-until-end-of-tx to false does not cause database updates to be "committed" to the database after each method invoke; they are only sent to the database. Updates are committed or rolled back in the database only at the conclusion of the transaction.
persistence-type
A persistence-type defines a persistence service that can be used by an EJB. You can define multiple persistence-type entries in weblogic-ejb-jar.xml for testing with multiple persistence services. Only the persistence type defined in persistence-use is used during deployment.
persistence-type includes several elements that define the properties of a service:
Note: The specified version must exactly match the RDBMS persistence version for the WebLogic Server release. Specifying an incorrect version results in the error:
weblogic.ejb.persistence.PersistenceSetupException: Error initializing the CMP Persistence Type for your bean: No installed Persistence Type matches the signature of (identifier `Weblogic_CMP_RDBMS', version `version_number').
WebLogic Server RDBMS-based persistence generally uses an XML file named weblogic-cmp-rdbms-jar.xml to store persistence data for a bean. This file is stored in the META-INF subdirectory of the .jar file.
The following shows an example persistence-type stanza with values appropriate for WebLogic Server RDBMS persistence:
<persistence-type>
<type-identifier>WebLogic_CMP_RDBMS</type-identifier>
<type-version>5.1.0</type-version>
<type-storage>META-INF\weblogic-cmp-rdbms-jar.xml</type-stora ge>
</persistence-type>
db-is-shared
The db-is-shared element applies only to entity beans. When set to true (the default value), WebLogic Server assumes that EJB data could be modified between transactions and reloads data at the beginning of each transaction. When set to false, WebLogic Server assumes that it has exclusive access to the EJB data in the persistent store. See Using db-is-shared to Limit Calls to ejbLoad() for more information.
stateful-session-persistent-store-dir
stateful-session-persistent-store-dir specifies the file system directory where WebLogic Server stores the state of passivated stateful session bean instances.
persistence-use
The persistence-use property is similar to persistence-type, but it defines the persistence service actually used during deployment. persistence-use uses the type-identifier and type-version elements defined in a persistence-type to identify the service.
For example, to actually deploy an EJB using the WebLogic Server RDBMS-based persistence service defined in persistence-type, the persistence-use stanza would resemble:
<persistence-use>
<type-identifier>WebLogic_CMP_RDBMS</type-identifier>
<type-version>5.1.0</type-version>
</persistence-use>
clustering-descriptor
The clustering-descriptor stanza defines the replication properties and behavior for EJBs deployed in a WebLogic Server cluster. The clustering-descriptor stanza and each of its elements are optional, and are not applicable to single-server systems.
The following shows all elements contained in the clustering-descriptor stanza:
<clustering-descriptor>
<home-is-clusterable>...</home-is-clusterable>
<home-load-algorithm>...</home-load-algorithm>
<home-call-router-class-name>.. .</home-call-router-class-name>
<stateless-bean-is-clusterable>...</stateless-bean-is-
clusterable>
<stateless-bean-load-algorithm>...
</stateless-bean-load-algorithm>
<stateless-bean-call-router-class-name>. . .</stateless-bean-call-router-class-name>
<stateless-bean-methods-are-idempotent>. . .</stateless-bean-methods-are-idempotent>
</clustering-descriptor>
home-is-clusterable
You can set this element to either true or false. When home-is-clusterable is true, the EJB can be deployed from multiple WebLogic Servers in a cluster. Calls to the home stub are load-balanced between the servers on which this bean is deployed, and if a server hosting the bean is unreachable, the call automatically fails over to another server hosting the bean.
home-load-algorithm
home-load-algorithm specifies the algorithm to use for load balancing between replicas of the EJB home. If this property is not defined, WebLogic Server uses the algorithm specified by the server property, weblogic.cluster.defaultLoadAlgorithm.
You can define home-load-algorithm as one of the following values:
home-call-router-class-name
home-call-router-class-name specifies the custom class to use for routing bean method calls. This class must implement weblogic.rmi.cluster.CallRouter. If specified, an instance of this class is called before each method call. The router class has the opportunity to choose a server to route to based on the method parameters. The class returns either a server name or null, which indicates that the current load algorithm should select the server.
stateless-bean-is-clusterable
Use stateless-bean-is-clusterable to specify whether a stateless session bean's EJBObject interface is clustered. Clustered EJBObjects support load balancing and failover.
If stateless-bean-is-clusterable is true, when a home interface of a clustered stateless session bean creates a bean instance, it returns a EJBObject stub to the client that lists all of the servers in the cluster. Given the stateless nature of the bean, any instance can service any client request.
stateless-bean-load-algorithm
Use stateless-bean-is-clusterable to specify whether a stateless session bean's EJBObject interface is clustered. Clustered EJBObjects support load balancing and failover.
If stateless-bean-is-clusterable is true, when a home interface of a clustered stateless session bean creates a bean instance, it returns a EJBObject stub to the client that lists all of the servers in the cluster. Given the stateless nature of the bean, any instance can service any client request.
stateless-bean-call-router-class-name
This property is similar to home-call-router-class-name, but it is applicable only to stateless session EJBs.
stateless-bean-methods-are-idempotent
You can set this element to either true or false. Set stateless-bean-methods-are-idempotent to true only if the bean is written such that repeated calls to the same method with the same arguments has exactly the same effect as a single call. This allows the failover handler to retry a failed call without knowing whether the call actually completed on the failed server. Setting this property to true makes it possible for the bean stub to automatically recover from any failure as long as another server hosting the bean can be reached.
Note: This property is applicable only to stateless session EJBs.
transaction-descriptor
The transaction-descriptor stanza contains elements that define transaction behavior in WebLogic Server. Currently, this stanza includes only one element:
<transaction-descriptor>
<trans-timeout-seconds>20</trans-timeout-seconds>
<transaction-descriptor>
trans-timeout-seconds
The trans-timeout-seconds element specifies the maximum duration for the EJB's container-initiated transactions. If a transaction lasts longer than trans-timeout-seconds, WebLogic Server rolls back the transaction.
If you specify no value for trans-timeout-seconds, container-initiated transactions timeout after five minutes, by default.
reference-descriptor
The reference-descriptor stanza maps references in the ejb-jar.xml file to the JNDI names of actual resource factories and EJBs available in WebLogic Server.
The reference-descriptor stanza contains one or more additional stanzas to define resource factory references and EJB references. The following shows the organization of these elements:
<reference-descriptor>
<resource-description>
<res-ref-name>. . .</res-ref-name>
<jndi-name>. . .</jndi-name>
</resource-description>
<ejb-reference-description>
<ejb-ref-name>. . .</ejb-ref-name>
<jndi-name>. . .</jndi-name>
</ejb-reference-description>
</reference-descriptor>
resource-description
The following elements define an individual resource-description:
ejb-reference-description
The following elements define an individual ejb-reference-description:
enable-call-by-reference
By default, EJB methods called from within the same EAR pass arguments by reference. This increases the performance of method invocation since parameters are not copied.
If you set enable-call-by-reference to false, parameters to EJB methods are copied (pass by value) in accordance with the EJB 1.1 specification. Pass by value is always necessary when the EJB is called remotely (not from within the same application).
jndi-name
The jndi-name element specifies a jndi-name for a bean, resource, or reference.
transaction-isolation
The transaction-isolation stanza specifies the transaction isolation level for EJB methods. The stanza consists of one or more isolation-level elements that apply to a range of EJB methods. For example:
<transaction-isolation>
<isolation-level>Serializable</isolation-level>
<method>
<description>...</description>
<ejb-name>...</ejb-name>
<method-intf>...</method-intf>
<method-name>...</method-name>
<method-params>...</method-params>
</method>
</transaction-isolation>
The following sections describe each element in transaction-isolation.
isolation-level
isolation-level defines a valid transaction isolation level to apply to specific EJB methods. The following are possible values for isolation-level:
Refer to your database documentation for more information on the implications and support for different isolation levels.
method
The method stanza defines the EJB methods to which an isolation level applies. method defines a range of methods using the following elements:
For example, the following method stanza designates all methods in the "AccountBean" EJB:
<method>
<ejb-name>AccountBean</ejb-name>
<method-name>*</method-name>
</method>
The following stanza designates all methods in the remote interface of "AccountBean:"
<method>
<ejb-name>AccountBean</ejb-name>
<method-intf>Remote</method-intf>
<method-name>*</method-name>
</method>
security-role-assignment
The security-role-assignment stanza maps application roles in the ejb-jar.xml file to the names of security principals available in WebLogic Server.
security-role-assignment can contain one or more pairs of the following elements:
|
|
|
|
|
|
Copyright © 2001 BEA Systems, Inc. All rights reserved.
|