| Download Docs | Site Map | Glossary | |
|
|
|||
| bea.com | products | dev2dev | support | askBEA |
|
|
|
|||||||
 |
| e-docs > WebLogic Server > Programming WebLogic Enterprise JavaBeans > The weblogic-ejb-jar.xml Deployment Descriptor |
|
Programming WebLogic Enterprise JavaBeans
|
The weblogic-ejb-jar.xml Deployment Descriptor
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 see Important Information for EJB 1.1 Users.
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.
WebLogic provides a public location for you to access the correct text for the WebLogic Server-specific DTD file, weblogic-ejb-jar.xml. However, an identical version of this DTD file is embedded in WebLogic Server for internal use. weblogic.appc uses this file when the XML parser checks the sequence of the deployment descriptors files.
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.
|
`-//Sun Microsystems, Inc.//DTD Enterprise JavaBeans 2.0//EN' ` |
|
|
`-//Sun Microsystems, Inc.//DTD Enterprise JavaBeans 1.1//EN' |
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 8.1.0 EJB//EN' 'http://www.bea.com/servers/wls810/dtd/weblogic-ejb-jar.dtd'>
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 `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.
The following links provide the public locations for weblogic-ejb-jar.xml DTDs, by version number.
http://www.bea.com/servers/wls810/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/wls700/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-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/wls510/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.
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.
2.0 weblogic-ejb-jar.xml Deployment Descriptor 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:
2.0 weblogic-ejb-jar.xml Deployment Descriptor Elements
|
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. |
|
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.
See stateful-session-descriptor
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. 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.
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 Caching Between Transactions for more information.
See persistence.
The cache-type element specifies the order in which EJBs are removed from the cache. The values are:
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 cache-type.
The following example shows the structure of the cache-type element.
<stateful-session-cache>
<cache-type>NRU</cache-type>
</stateful-session-cache>
The client-authentication element specifies whether the EJB supports or requires client authentication.
The client-cert-authentication element specifies whether the EJB supports or requires client certificate authentication at the transport level.
The clients-on-same-server attribute 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.
The following example enables pass-by-value for EJB methods:
<weblogic-enterprise-bean>
<ejb-name>AccountBean</ejb-name>
...
<clients-on-same-server>True</clients-on-same-server>
</weblogic-enterprise-bean>
The concurrency-strategy element specifies how the container should manage concurrent access to an entity bean. Set this element to one of four values:
SeeEJB Concurrency Strategy for more information on the Exclusive and Database locking behaviors. SeeRead-Only Multicast Invalidation 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 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.
The connection-factory-jndi-name element specifies the JNDI name of the JMS ConnectionFactory that the MessageDriven Bean should look up to create its queues and topics. If this element is not specified, the default is the weblogic.jms.MessageDrivenBeanConnectionFactory in config.xml.
The following example shows the structure of the connection-factory-jndi-name element:
<message-driven-descriptor>
<connection-factory-jndi-name>weblogic.jms.MessageDrivenBean
ConnectionFactory</connection-factory-jndi-name>
</message-driven-descriptor>
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-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 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>
The description element is used to provide text that describes the parent element.
The following example specifies the description element.
<dscription>Contains a description of parent element</description>
|
Required in message-driven-descriptor. |
|
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 WebLogic Server JNDI tree.
See message-driven-descriptor.
|
Required element in method stanza. The name must conform to the lexical rules for an NMTOKEN. |
|
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.
See method.
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.
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>
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.
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
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.
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>
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 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 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 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.
The following example enables dynamic queries:
<enable-dynamic-queries>True</enable-dynamic-queries>
The entity-cache element defines the following options used to cache entity EJB instances within WebLogic Server:
SeeEJB Lifecycle in WebLogic Server for a general discussion of the caching services available in WebLogic Server.
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>
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 the application deployment descriptors.
See entity-cache-ref.
|
The entity-cache-name element in the entity-cache-ref stanza must contain the name of the application level cache. |
|
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 banes with a concurrency-strategy of Exclusive. While a MultiVersion cache supports the Database, ReadOnly, and Optimistic concurrency strategies.
The entity-cache-ref stanza is shown here:
<entity-cache-ref>
<entity-cache-name>AllEntityCache</entity-cache-name>
<concurrency-strategy>ReadOnly</concurrency-strategy>
<estimated-bean-size>20</estimated-bean-size>
</entity-cache-ref>
The entity-clustering element uses the following options to specify how an entity bean will be replicated in a WebLogic 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 element specifies the following deployment parameters that are applicable to an entity bean:
The following example shows the structure of the entity-descriptor stanza:
<entity-descriptor>
<entity-cache>...</entity-cache>
<persistence>...</persistence>
<entity-clustering>...</entity-clustering>
</entity-descriptor>
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.
See entity-cache-ref.
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.
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 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:
See entity-clustering and stateful-session-clustering.
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.
The method stanza can contain the elements shown here:
<idempotent-method>
<method>
<description>...</description>
<ejb-name>...</ejb-name>
<method-intf>...</method-intf>
<method-name>...</method-name>
<method-params>...</method-params>
</method>
</idempotent-method>
The identity-assertion element specifies whether the EJB supports or requires identity assertion.
|
weblogic-enterprise-bean, weblogic-enterprise-bean, |
|
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 EJB Lifecycle 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>
<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>
The iiop-security-descriptor element specifies security configuration parameters at the bean-level. These parameters determine the IIOP security information contained in the IOR.
The iiop-security-descriptor stanza can contain the elements shown here
<iiop-security-descriptor>
<transport-requirements>...</transport-requirements>
<client-authorization>suppoted<client-authentication>
<identity-assertion>supported</identity-assertion>
</iiop-security-description>
|
Optional element. Valid for stateless session, entity, and message-driven EJBs. |
|
|
weblogic-enterprise-bean, |
|
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.
See pool.
|
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. |
|
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.
The following example specifies the initial-context-factory element.
<message-driven-descriptor>
<initial-context-factory>weblogic.jndi.WLInitialContextFactory
</initial-context-factory>
</message-driven-descriptor>
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.
|
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. |
|
The invalidation-target element specifies a Read-Only entity EJB that should be invalidated when this container-managed persistence entity EJB has been modified.
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 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.
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 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.
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.
The following entry specifies the jms polling intervals for message-driven beans:
<jms-polling-interval-seconds>5</jms-polling-interval seconds>
The jms-client-id specifies an associated id for the JMS consumers. 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 connection factory does not have a client id or if you use the default connection factory, then the message-driven bean used the jms-client-id value as its client id.
The following entry specifies an associated id for JMS consumers:
<jms-client-id>MyClientID</jms-client-id>
|
Required in resource-description and ejb-reference-description. |
|
|
weblogic-enterprise-bean weblogic-enterprise-bean |
|
jndi-name specifies the JNDI name of an actual EJB, resource, or reference available in WebLogic Server.
See resource-description and ejb-reference-description.
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.
The following example shows the specifies the local-jndi-name element.
<local-jndi-name>weblogic.jndi.WLInitialContext
</local-jndi-name>
|
weblogic-enterprise-bean, weblogic-enterprise-bean |
|
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 inEJB Concurrency Strategy.
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-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 and Differences Between Message-Driven Beans and Stateless Session EJBs for more information.
See pool.
The message-driven-descriptor element associates a message-driven bean with a JMS destination in WebLogic Server. This element specifies the following deployment parameters:
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 element defines a method or set of methods for an enterprise bean's home or remote interface.
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.
|
Required element in method stanza. |
|
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.
|
Required element in method-params. |
|
The method-param element specifies the fully qualified Java type name 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 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:
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-beand>...</finders-load-bean>
<persistence-type>...</persistence-type>
<db-is-shared>False</db-is-shared>
<persistence-use>...</persistence-use>
</persistence>
</entity-descriptor>
The persistence-type element defines a persistence service that the entity EJB can use. You can define multiple persistence-type stanzas in weblogic-ejb-jar.xml for testing your EJB with multiple persistence services. Only the persistence type defined in persistence-use is actually used during deployment.
persistence-type includes several elements that identify the persistence types:
The following excerpt shows a sample persistence-type stanza:
<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-storage>
</persistence-type>
</persistence>
The persistence-use element is similar to persistence-type, but it defines the persistence service actually used during deployment. persistence-use uses the type-identifier and type-version elements defined in a persistence-type to identify the service.
To deploy an EJB using the WebLogic Server RDBMS-based persistence service defined in persistence-type, use the following persistence-use stanza:
<persistence-use>
<type-identifier>WebLogic_CMP_RDBMS</type-identifier>
<type-version>5.1.0</type-version>
</persistence-use>
The persistent-store-dir element specifies a file system directory where WebLogic Server stores the state of passivated stateful session bean instances.
See stateful-session-descriptor.
The pool element configures the behavior of the WebLogic Server free pool for stateless session and message-driven EJBs. The options are:
The pool stanza can contain the elements shown here:
<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>
|
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. |
|
principal-name specifies the name of an actual WebLogic Server principal to apply to the specified role-name.
The provider-url element 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.
The following example specifies the provider-url element.
<message-driven-descriptor>
<provider-url>WeblogicURL:Port</provider-url>
</message-driven-descriptor>
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, and WebLogic Server calls ejbLoad() only when the bean is brought into the cache.
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>
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.
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>
This element is no longer supported in WebLogic Server.
|
Optional element. Valid only for stateful session EJBs in a cluster. |
|
|
weblogic-enterprise-bean |
|
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.
See stateful-session-clustering.
|
A valid resource environment reference name from the ejb-jar.xml file |
|
|
weblogic-enterprise-bean |
|
The res-env-ref-name element specifies the name of a resource environment reference.
See resource-description.
|
Required element if the EJB specifies resource references in ejb-jar.xml |
|
|
weblogic-enterprise-bean |
|
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.
See resource-description.
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.
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>
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.
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>
|
Required element in security-role-assignment. |
|
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.
The security-permission element specifies a security permission
The security-permission stanza can contain one or more of the following elements:
<security-permission> </security-permission>
The security-permission element specifies a single security permission based on the Security policy file syntax.
The security-permission-spec stanza can contain one or more of the following elements:
<security-permission>
<security-permission-spec>grant</security-permission-spec>
</security-permission>
The security-role-assignment element maps application roles in the ejb-jar.xml file to the names of security principals available in WebLogic Server.
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>
The stateful-session-cache element defines the following options used to cache stateful session EJB instances within WebLogic Server.
SeeEJB Lifecycle in WebLogic Server for a general discussion of the caching services available in WebLogic Server.
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>
<read-timeout-seconds>...<read-timeout-seconds>
</stateful-session-cache>
The stateful-session-clustering stanza element specifies the following options that determine how WebLogic Server replicates stateful session EJB instances in a cluster:
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-name>
<replication-type>InMemory</replication-type>
</stateful-session-clustering>
The stateful-session-descriptor element specifies the following deployment parameters that are applicable for stateful session EJBs in WebLogic Server:
The following example shows the structure of the stateful-session-descriptor stanza:
<stateful-session-descriptor>
<stateful-session-cache>...</stateful-session-cache>
<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
|
Optional element. Valid only for stateless session EJBs in a cluster. |
|
|
weblogic-enterprise-bean, |
|
The stateless-bean-call-router-class-name element specifies the name of a custom class to use for routing bean method calls. This class must implement weblogic.rmi.extensions.CallRouter(). If specified, an instance of this class is called before each method call. The router class has the opportunity to choose a server to route to based on the method parameters. The class returns either a server name or null, which indicates that the current load algorithm should select the server.
See stateless-clustering.
|
Optional element. Valid only for stateless session EJBs in a cluster. |
|
|
weblogic-enterprise-bean, |
|
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.
See stateless-clustering.
|
Optional element. Valid only for stateless session EJBs in a cluster. |
|
|
weblogic-enterprise-bean, |
|
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:
See stateless-clustering.
stateless-bean-methods-are-idempotent
|
Optional element. Valid only for stateless session EJBs in a cluster. |
|
|
weblogic-enterprise-bean, |
|
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.
See stateless-clustering.
The stateless-clustering element specifies the following options that determine how WebLogic Server replicates stateless session EJB instances in a cluster:
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>
|
One stateless-session-descriptor element is required for each stateless session EJB in the JAR file. |
|
The stateless-session-descriptor element defines deployment parameters, such as caching, clustering, and persistence for stateless session EJBs in WebLogic Server.
The following example shows the structure of the stateless-session-descriptor stanza:
<stateless-session-descriptor>
<pool>...</pool>
<stateless-clustering>...</stateless-clustering>
</stateless-session-descriptor>
The transaction-descriptor element specifies options that define transaction behavior in WebLogic Server. Currently, this stanza includes only one element: trans-timeout-seconds.
The following example shows the structure of the transaction-descriptor stanza:
<transaction-descriptor>
<trans-timeout-seconds>20</trans-timeout-seconds>
<transaction-descriptor>
The transaction-isolation element defines method-level transaction isolation settings for an EJB.
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>
The transport-requirements element provides the transport requirements for the EJB.
The transport-requirements stanza can contain the elements shown here
<iiop-security-descriptor>
<transport-requirements>
<confidentiality>supported</confidentiality>
<integrity>supported</integrity>
<client-cert-authorization>suppoted
</client-cert-authentication>
</transport-requirements>
</iiop-security-description>
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.
|
Required only for entity EJBs that use container-managed persistence services. |
|
|
weblogic-enterprise-bean, |
|
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.
See persistence-type for an example that shows the complete persistence-type definition for WebLogic Server RDBMS-based persistence.
|
Required only for entity EJBs that use container-managed persistence services. |
|
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.
See persistence-type for an example that shows the complete persistence-type definition for WebLogic Server RDBMS-based persistence.
|
Required only for entity EJBs that use container-managed persistence services. |
|
|
weblogic-enterprise-bean, |
|
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').
See persistence-type for an example that shows the complete persistence-type definition for WebLogic Server RDBMS-based persistence.
weblogic-ejb-jar is the root element of the weblogic component of the EJB deployment descriptor.
The weblogic-enterprise-bean element contains the deployment information for a bean that is available in WebLogic Server.
|
|
|
|
||
 |
|
|
 |
 |
 |
|
||
