Corporate Info  |  News  |  Solutions  |  Products  |  Partners  |  Services  |  Events  |  Download  |  How To Buy
	e-docs   |   Site Map   |   Search   |   Contact   |   Glossary   |   WebLogic Server Documentation
Programming WebLogic Enterprise JavaBeans:   Previous topic   |   Next topic   |   Contents

The following sections provide a complete reference of the WebLogic specific XML deployment properties used in the WebLogic Server 6.0 EJB 2.0 container and an explanation of how to edit the XML deployment properties manually.

• Manually Editing XML Deployment Files

• weblogic-ejb-jar.xml Deployment Descriptor File

• Index of weblogic-ejb-jar Deployment Elements

• weblogic-cmp-rdbms-jar.xml Deployment Descriptor File

• Index of weblogic-cmp-rdbms-jar.xml Deployment Elements

Manually Editing XML Deployment Files

To create and deploy message-driven beans, or use the new caching and clustering deployment elements, you must edit the following XML deployment files manually, using a text editor:

• weblogic-ejb.jar

• weblogic-cmp-rdbms.jar

See also Basic Conventions for more information on the conventions to use when modifying XML deployment files.

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 correct text for the PUBLIC element for each XML deployment file is as follows.

XML File	PUBLIC Element String
ejb-jar.xml	`-//Sun Microsystems, Inc.//DTD Enterprise JavaBeans 2.0//EN' `http://www.java.sun.com/dtd/ejb-jar_2_0.dtd'
weblogic-ejb-jar.xml	`-//BEA Systems, Inc.//DTD WebLogic 6.0.0 EJB//EN` `http://www.bea.com/servers/wls600/dtd/weblogic-ejb-jar.dtd`
weblogic-cmp-rdbms -jar.xml	`-// BEA Systems, Inc.//DTD WebLogic 6.0.0 EJB RDBMS Persistence//EN` `http://www.bea.com/servers/wls600/dtd/weblogic-rdbms20-persistence-600.dtd`

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

<!DOCTYPE weblogic-ejb-jar PUBLIC 
'-//BEA Systems, Inc.//DTD WebLogic 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.

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.

The following links provide the new public DTD locations for XML deployment files used with the WebLogic Server EJB 2.0 container:

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

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

• http://www.bea.com/servers/wls600/dtd/weblogic-rdbms20-
  persistence-600.dtd contains the DTD that defines container-managed persistence properties for entity EJBs. This DTD is changed from WebLogic Server Version 5.1, and you must still include a weblogic-cmp-rdbms-jar.xml file for entity EJBs using WebLogic Server RDBMS-based persistence.

  Use the existing DTD file located at:

  http://www.bea.com/servers/wls600/dtd/weblogic-rdbms-
  persistence-600.dtd

  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 Deployment Descriptor File

weblogic-ejb-jar.xml defines EJB deployment descriptor DTDs which are unique to WebLogic Server. The EJB 2.0 container uses a version of weblogic-ejb-jar.xml that is different from the one shipped with WebLogic Server Version 5.1. The revised DTD for weblogic-ejb-jar.xml includes new elements for enabling stateful session EJB replication, configuring entity EJB locking behavior, and assigning JMS Queue and Topic names for message-driven beans. The new DTD also reorganizes the major stanzas into more logical sections.

You can continue to use the earlier weblogic-ejb-jar.xml DTD for EJB 1.1 that you will deploy into the EJB 1.1 container. However, if you want to use any of the new EJB 2.0 features or deploy beans into the EJB 2.0 container, you must use the DTD described in the sections listed in Index of weblogic-ejb-jar Deployment Elements.

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

• description of the file

• Copyright information

• weblogic-enterprise-bean

  • ejb-name

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

  • transaction-descriptor

  • reference-descriptor

  • enable-call-by-reference

  • jndi-name

• security-role-assignment

• transaction-isolation

Use the links above, or see Manually Editing XML Deployment Files for more information about individual EJB 2.0 deployment stanzas and elements. See also Manually Editing XML Deployment Files for complete information about the deployment elements introduced for EJB 1.1.

• allow-concurrent-calls

• description

• ejb-name

• ejb-reference-description

• ejb-ref-name

• enable-call-by-reference

• entity-cache

• entity-clustering

• entity-descriptor

• concurrency-strategy

• db-is-shared

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

• destination-jndi-name

• finders-load-bean

• home-call-router-class-name

• home-is-clusterable

• home-load-algorithm

• idle-timeout-seconds

• initial-beans-in-free-pool

• is-modified-method-name

• isolation-level

• jndi-name

• lifecycle

• max-beans-in-cache

• max-beans-in-free-pool

• message-driven-descriptor

• method

• method-intf

• method-name

• method-param

• method-params

• passivation-strategy

• persistence

• persistence-type

• persistence-use

• persistent-store-dir

• pool

• principal-name

• read-timeout-seconds

• reference-descriptor

• replication-type

• res-ref-name

• resource-description

• role-name

• security-role-assignment

• stateful-session-cache

• stateful-session-clustering

• stateful-session-descriptor

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

• stateless-bean-is-clusterable

• stateless-bean-load-algorithm

• stateless-bean-methods-are-idempotent

• stateless-clustering

• stateless-session-descriptor

• transaction-descriptor

• transaction-isolation

• trans-timeout-seconds

• type-identifier

• type-storage

• type-version

• res-env-ref-name

• resource-env-description

• run-as-identity-principal

allow-concurrent-calls

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

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

See stateful-session-descriptor.

This element determines ejbLoad() and ejbStore() behavior for entity EJB instances. You can set this element to one of three possible values:

• Exclusive was the default locking behavior for WebLogic Server versions 3.1 through 5.1. WebLogic Server places an exclusive lock on cached entity EJB instances when the bean is associated with a transaction. Other requests for the EJB instance block until the transaction completes.

• Database is the default locking behavior for Weblogic Server versions 6.x. This value causes WebLogic Server to defer locking requests for an entity EJB to the underlying datastore. With the Database concurrency strategy, WebLogic Server does not cache the intermediate results of entity EJBs involved in a transaction.

• ReadOnly designates an entity EJB that is never modified. WebLogic Server calls ejbLoad() for ReadOnly beans based on the read-timeout-seconds parameter.

See Locking and Caching Services for Entity EJBs for more information on the Exclusive and Database locking behaviors. See Read-Write Cache Strategy for more information about read-only entity EJBs.

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>

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

See persistence.

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

If your datastore uses an isolation level of TRANSACTION_READ_UNCOMMITTED, you may want to allow other database users to view the intermediate results of in-progress transactions. In this case, set delay-updates-until-end-of-tx to false to update the bean's persistent store at the conclusion of each method invoke. 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.

The following entry specifies that WebLogic Server call ejbStore() at the end of each method invocation:

<entity-descriptor>

  <persistence>

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

  </persistence>

</entity-descriptor>

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

destination-jndi-name specifies the JNDI name of an actual JMS Queue or Topic available in WebLogic Server.

See message-driven-descriptor.

ejb-name specifies the name of an EJB to which WebLogic Server applies isolation level properties.

See method.

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

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

<reference-descriptor>

  <ejb-reference-description>

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

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

  </ejb-reference-description>

</reference-descriptor>

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

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

• jndi-name specifies the JNDI name of an actual resource factory available in WebLogic Server.

Example

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

<reference-descriptor>

  <ejb-reference-description>

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

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

  </ejb-reference-description>

</reference-descriptor>

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

If you set enable-call-by-reference to False parameters to EJB methods are copied (pass-by-value) in accordance with the EJB 1.1 specification. Pass by value is always necessary when the EJB is called remotely (not from within the server).

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>

The entity-cache element defines options used to cache entity EJB instances within WebLogic Server. See EJB Life Cycle in WebLogic Server for a general discussion of the caching services available in WebLogic Server.

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

The entity-clustering stanza contains elements that determines how WebLogic Server replicates entity EJB instances in a cluster.

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

<entity-clustering>

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

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

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

</entity-clustering>

The entity-descriptor stanza defines caching, clustering, and persistence properties for entity EJBs in WebLogic Server.

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

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

See entity-clustering and stateful-session-clustering.

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.

See entity-clustering.

home-load-algorithm specifies the algorithm to use for load balancing between replicas of the EJB home. If this property is not defined, WebLogic Server uses the algorithm specified by the server property, weblogic.cluster.defaultLoadAlgorithm.

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

• round-robin: Load balancing is performed in a sequential fashion among the servers hosting the bean.

• random: Replicas of the EJB home are deployed randomly among the servers hosting the bean.

• weight-based: Replicas of the EJB home are deployed on host servers according to the servers' current workload.

Example

See entity-clustering and stateful-session-clustering.

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 in WebLogic Server for more information.

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>

    <entity-cache>

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

      <idle-timeout-seconds>1200</idle-timeout-seconds>

    </entity-cache>

  </stateful-session-descriptor>

</weblogic-enterprise-bean>

If you specify a value for initial-beans-in-free-pool, you set the intital size ofthe 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.

See pool.

is-modified-method-name specifies a method that WebLogic Server calls when the EJB is stored. The specified method must return a boolean value. If no method is specified, WebLogic Server always assumes that the EJB has been modified and always saves it.

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

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>isModified</is-modified-method-name>

  </persistence>

</entity-descriptor>

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

• ReadUncommitted: The transaction can view uncommitted updates from other transactions.

• ReadCommitted: The transaction can view only committed updates from other transactions.

• RepeatableRead: 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.

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

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

See transaction-isolation.

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

See resource-description and ejb-reference-description.

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

<entity-descriptor>

  <lifecycle>

    <passivation-strategy>...</passivation-strategy>

  </lifecycle>

</entity-descriptor>

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 in Locking and Caching Services for Entity EJBs.

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>

WebLogic Server maintains a free pool of EJBs for every 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 has no limit; the maximum number of beans in the free pool is limited only by the available memory. See Stateless Session EJB Life Cycle or Differences Between Message-Driven Beans and Stateless Session EJBs for more information.

See pool.

The message-driven-descriptor stanza associates a message-driven bean with a JMS destination in WebLogic Server. This stanza currently includes only one XML element, destination-jndi-name.

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

<message-driven-descriptor>

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

</message-driven-descriptor>

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

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 specifies the EJB interface to which WebLogic Server applies isolation level properties. Use this element only if you need to differentiate between methods having the same signature in the EJB's home and remote interface.

See method.

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.

See method.

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

See method-params.

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

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>

The passivation-strategy element determines whether or not WebLogic Server maintains the intermediate state of entity EJBs in its cache. See Locking and Caching Services for Entity EJBs for more information.

The following entry reverts to WebLogic Server locking and caching behavior:

<entity-descriptor>

  <lifecycle>

    <passivation-strategy>default</passivation-strategy>

  </lifecycle>

</entity-descriptor>

The persistence stanza defines properties that determine the persistence type, transaction commit behavior, and ejbLoad() and ejbStore() behavior for entity EJBs in WebLogic Server.

<entity-descriptor>

  <persistence>

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

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

    <finders-load-beand>...</finders-load-bean>

    <persistence-type>...</persistence-type>

    <db-is-shared>false</db-is-shared>