Programming WebLogic Enterprise JavaBeans
|
 |
 |
|
 |
 |
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 contents and arrangement of elements in your XML files must conform to the Document Type Definition (DTD) for each file you use. WebLogic Server ignores the DTDs embedded within the DOCTYPE header of XML deployment files, and instead uses the DTD locations that were installed along with the server. However, the DOCTYPE header information must include a valid URL syntax in order to avoid parser errors.
When editing or creating XML deployment files, it is critical to include the correct DOCTYPE header for each deployment file. In particular, using an incorrect PUBLIC element within the DOCTYPE header can result in parser errors that may be difficult to diagnose.
The header refers to the location and version of the Document Type Definition (DTD) file for the deployment descriptor. Although this header references an external URL at java.sun.com, WebLogic Server contains its own copy of the DTD file, so your host server need not have access to the Internet. However, you must still include this <!DOCTYPE...> element in your weblogic-ejb-jar.xml and weblogic-cmp-jar.xml files, and have them reference the external URL because the version of the DTD contained in this element is used to identify the version of this deployment descriptor.
XML files with incorrect header information may yield error messages similar to the following, when used with a tool that parses the XML (such as appc):
The correct text for the PUBLIC elements for the WebLogic-Server-specific weblogic-ejb-jar.xml file is listed, by WebLogic Server version, in Table A-1.
Table A-1 PUBLIC Elements of weblogic-ejb-jar.xml
The correct text for the PUBLIC elements for the WebLogic-Server-specific weblogic-cmp-jar.xml file is listed, by WebLogic Server version, in Table A-2.
Table A-2 PUBLIC Elements of weblogic-cmp-jar.xml
See weblogic-cmp-jar.xml Deployment Descriptor Reference, for more information on the weblogic-cmp-jar.xml file.
The correct text for the PUBLIC elements for the Sun-Microsystems-specific ejb-jar.xml file is listed, by Enterprise JavaBeans version, in Table A-3.
Table A-3 PUBLIC Elements of ejb-jar.xml
|
|
||
|
|
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:
descriptionweblogic-versionweblogic-enterprise-beanejb-name
These changes were made to weblogic-ejb-jar.xml in WebLogic Server 8.1:
False in Weblogic Server 8.1.
This list of the elements in weblogic-ejb-jar.xml includes all elements that were supported in any service pack of WebLogic Server 8.1. The previous section, Changes to weblogic-ejb-jar.xml in WebLogic Server 8.1 lists elements that were new, changed, or deprecated in Weblogic Server 8.1, or a subsequent service pack.
Specifies whether a stateful session bean instance allows concurrent method calls. By default, allows-concurrent-calls is False, in accordance with the EJB specification, and WebLogic Server will throw a RemoteException when a stateful session bean instance is currently handling a method call and another (concurrent) method call arrives on the server.
When this value is set to True, the EJB container blocks the concurrent method call and allows it to proceed when the previous call has completed.
See stateful-session-descriptor.
Specifies that the remove method on a stateful session bean can be invoked within a transaction context.
Note: Stateful session beans implementing the Synchronization interface should not use this tag and then call remove before the transaction ends. If this is done the EJB container will not invoke the synchronization callbacks.
See stateful-session-descriptor.
Formerly the db-is-shared element, specifies whether the EJB container will cache the persistent data of an entity bean across (between) transactions.
Specify True to enable the EJB container to perform long term caching of the data. Specify False to enable the EJB container to perform short term caching of the data.
A Read-Only bean ignores the value of the cache-between-transactions element because WebLogic Server always performs long term caching of Read-Only data.
See Limiting Database Reads with cache-between-transactions (Long-Term Caching) for more information.
See persistence.
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 max-beans-in-cache.
<stateful-session-cache><cache-type>NRU</cache-type>
</stateful-session-cache>
Specifies whether the EJB supports or requires client authentication.
Specifies whether the EJB supports or requires client certificate authentication at the transport level.
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.
<weblogic-enterprise-bean>
<ejb-name>AccountBean</ejb-name>
...
<clients-on-same-server>True</clients-on-same-server>
</weblogic-enterprise-bean>
Specifies how the container should manage concurrent access to an entity bean. Set this element to one of four values:
Exclusive causes WebLogic Server to place an exclusive lock on cached entity EJB instances when the bean is associated with a transaction. Other requests for the EJB instance are blocked until the transaction completes. This option was the default locking behavior for WebLogic Server versions 3.1 through 5.1.Database causes WebLogic Server to defer locking requests for an entity EJB to the underlying datastore. With the Database concurrency strategy, WebLogic Server allocates a separate entity bean instance and allows locking and caching to be handled by the database. This is the default option.ReadOnly is used for read-only entity beans. Activates a new instance for each transaction so that requests proceed in parallel. WebLogic Server calls ejbLoad() for ReadOnly beans are based on the read-timeout-seconds parameter.Optimistic holds no locks in the EJB container or database during a transaction. The EJB container verifies that none of the data updated by a transaction has changed before committing the transaction. If any updated data changed, the EJB container rolls back the transaction.See Choosing a Concurrency Strategy for more information on the Exclusive and Database locking behaviors. See Read-Write versus Read-Only Entity Beans for more information about read-only entity EJBs.
<weblogic-enterprise-bean>
<ejb-name>AccountBean</ejb-name>
<entity-descriptor>
<entity-cache>
<concurrency-strategy>ReadOnly</concurrency-strategy>
</entity-cache>
</entity-descriptor>
</weblogic-enterprise-bean>
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.
Specifies the JNDI name of the JMS Connection Factory that a message-driven EJB looks up to create its queues and topics. See Configuring MDBs for Destinations and How to Set connection-factory-jndi-name.
<message-driven-descriptor><connection-factory-jndi-name>java:comp/env/jms/MyConnectionFactory</connection-factory-jndi-name>
</message-driven-descriptor>
Introduced in WebLogic Server 8.1 SP01, specifies the principal to be used in situations where ejbCreate would otherwise run with an anonymous principal. Under such conditions, the choice of which principal to run as is governed by the following rule:
if create-as-principal-name is set
then use that principal
else
If a run-as role has been specified for the bean in ejb-jar.xml then use a principal according to the rules for setting the run-as-role-assignment
else
run ejbCreate as an anonymous principal.
The create-as-principal-name element only needs to be specified if operations within ejbCreate require more permissions than the anonymous principal would have.
This element effects the ejbCreate methods of stateless session beans and message-driven beans.
See also remove-as-principal-name, passivate-as-principal-name, and principal-name.
Set the delay-updates-until-end-of-tx element to True (the default) to update the persistent store of all beans in a transaction at the completion of the transaction. This setting generally improves performance by avoiding unnecessary updates. However, it does not preserve the ordering of database updates within a database transaction.
If your datastore uses an isolation level of TransactionReadCommittedUncommitted, you may want to allow other database users to view the intermediate results of in-progress transactions. In this case, set delay-updates-to-end-of-tx to False to update the bean's persistent store at the conclusion of each method invoke. See Understanding ejbLoad() and ejbStore() Behavior for more information.
Note: Setting delay-updates-until-end-of-tx to False does not cause database updates to be "committed" to the database after each method invoke; they are only sent to the database. Updates are committed or rolled back in the database only at the conclusion of the transaction.
<entity-descriptor><persistence>......<delay-updates-until-end-of-tx>False</delay-updates-until-end-of-tx></persistence>
</entity-descriptor>
<dscription>Contains a description of parent element</description>
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.
Specifies that WebLogic Server should disable the warning message whose ID is specified. Set this element to one of four values:
BEA-010001—Disables this warning message: "EJB class loaded from system classpath during deployment."BEA-010054—Disables this warning message: "EJB class loaded from system classpath during compilation."BEA-010200—Disables this warning message: "EJB impl class contains a public static field, method or class."BEA-010202—Disables this warning message: "Call-by-reference not enabled."To disable the warning message: "Call-by-reference not enabled", set <disable-warning>, as shown below.
<disable-warning>BEA-010202</disable-warning>
Designates which server execute thread pool the EJB should run in. Dispatch polices are supported for all types of beans, including entity, session and message-driven.
If no dispatch-policy is specified, or the specified dispatch-policy refers to a nonexistent server execute thread pool, then the server's default execute thread pool is used instead.
WebLogic Server ignores dispatch-policy if the host server instance does not have an execute thread queue bearing a corresponding name.
If a message-driven bean (MDB) is driven by a foreign (non-WebLogic) destination source, WebLogic Server might ignore dispatch-policy, as the MDB may instead run in the foreign provider's threading mechanism. For example, for the IBM WebSphere MQSeries messaging software, dispatch-policy is not honored for non-transactional queues; instead the application code runs in an MQSeries thread. For MQSeries transactional queues, and both non-transactional and transactional topics, dispatch-policy is honored.
The maximum number of concurrently running MDB instances is designated by a combination of max-beans-in-free-pool and dispatch-policy values.
maxConcurrentMDBs = Min(max-beans-free-pool, default-thread-pool-size/2+1).
MDBs that run in the default thread pool limit their concurrency to half the thread pool size plus one to prevent deadlocks with other services and applications that share the default thread pool.
<dispatch-policy>queue_name</dispatch-policy>
Maps the JNDI name of an EJB in the WebLogic Server instance that is referenced by the bean in the ejb-local-ref element.
<ejb-local-reference-description>
<ejb-ref-name>AdminBean</ejb-ref-name>
<jndi-name>payroll.AdminBean</jndi-name>
</ejb-local-reference-description>
Specifies an enterprise bean's name, using the same name for the bean that is specified in ejb-jar.xml. The enterprise bean code does not depend on the name; therefore the name can be changed during the application assembly process without breaking the enterprise bean's function. There is no architected relationship between the ejb-name in the deployment descriptor and the JNDI name that the Deployer will assign to the enterprise bean's home.
Note: Not recommended in weblogic-enterprise-bean. For more information, see Using EJB Links.
See method.
Maps the JNDI name of an EJB in WebLogic Server to the name by which it is specified in the ejb-ref-name element in ejb-jar.xml.
<ejb-reference-description>
<ejb-ref-name>AdminBean</ejb-ref-name>
<jndi-name>payroll.AdminBean</jndi-name>
</ejb-reference-description>
Specifies a resource reference name. This element is the reference that the EJB provider places within the ejb-jar.xml deployment file.
<reference-descriptor>
<ejb-reference-description>
<ejb-ref-name>AdminBean</ejb-ref-name>
<jndi-name>payroll.AdminBean</jndi-name>
</ejb-reference-description>
</reference-descriptor>
By default, the EJB implementation class is loaded in the same classloader as the rest of the EJB classes. When the enable-bean-class-redeploy element is enabled, the implementation class, along with its super classes, gets loaded in a child classloader of the EJB module classloader. This allows the EJB implementation class to be redeployed without redeploying the entire EJB module.
There are some potential problems with loading the bean class in a child classloader. First, the bean class will no longer be visible to any classes loaded in the parent classloader, so those classes cannot refer to the bean class or errors will occur. Also, the bean class will not be able to invoke any package protected methods on any classes loaded in a different classloader. So, if your bean class invokes a helper class in the same package, the helper class methods must be declared public or IllegalAccessErrors will result.
Note: Two-phase deployment must be used for this feature to be enabled. WebLogic Server ignores the enable-bean-class-redeploy setting will be ignored if two-phase deployment is not used. For information on two-phase deployment, see Two-Phase Deployment Protocol in Deploying WebLogic Server Applications.
The following XML stanza enables redeployment of an individual bean class:
<enable-bean-class-redeploy>True</enable-bean-class-redeploy>
When enable-call-by-reference is False, parameters to the EJB methods are copied—or passed by value—regardless of whether the EJB is called remotely or from with the same EAR.
Note: Even when set to false, call-by-reference is used when it is used:
When enable-call-by-reference is True, EJB methods called from within the same EAR file or standalone JAR file will pass arguments by reference. This improves the performance of method invocation since parameters are not copied.
Note: Method parameters are always passed by value when an EJB is called remotely.
<weblogic-enterprise-bean><entity-descriptor><ejb-name>AccountBean</ejb-name>
...<enable-call-by-reference>False</enable-call-by-reference></entity-descriptor></weblogic-enterprise-bean>
Set to True to enable dynamic queries. Dynamic queries are only available for use with EJB 2.0 CMP beans.
<enable-dynamic-queries>True</enable-dynamic-queries>
Defines the following options used to cache entity EJB instances within WebLogic Server:
See Understanding Entity Caching for more information.
<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>
Refers to an application level entity cache that the entity bean uses. An application level cache is a cache that may be shared by multiple entity beans in the same application. The value you specify for entity-cache-name must match the name assigned to an application level entity cache in the weblogic-application.xml file
For more information about the weblogic-application.xml file, see Enterprise Application Deployment Descriptor Elements in Developing WebLogic Server Applications.
See entity-cache-ref.
Refers to an application level entity cache which can cache instances of multiple entity beans that are part of the same application. Application level entity caches are declared in the weblogic-application.xml file.
Use concurrency-strategy to define the type of concurrency you want the bean to use. The concurrency-strategy must be compatible with the application level cache's caching strategy. For example, an Exclusive cache only supports beans with a concurrency-strategy of Exclusive. A MultiVersion cache supports the Database, ReadOnly, and Optimistic concurrency strategies.
<entity-cache-ref>
<entity-cache-name>AllEntityCache</entity-cache-name>
<read-timeout-seconds>600</read-timeout-seconds>
<cache-between-transactions>true</cache-between-transactions>
<concurrency-strategy>ReadOnly</concurrency-strategy>
<estimated-bean-size>20</estimated-bean-size>
</entity-cache-ref>
Specifies 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>
<use-servside-stubs>True</use-servside-stubs>
</entity-clustering>
Specifies the following deployment parameters that are applicable to an entity bean:
poolentity-cache or entity-cache-refpersistenceentity-clusteringinvalidation-targetenable-dynamic-queries<entity-descriptor>
<entity-cache>...</entity-cache>
<persistence>...</persistence>
<entity-clustering>...</entity-clustering>
<invalidation-target>...</invalidation-target>
<enable-dynamic-queries>...</enable-dynamic-queries>
</entity-descriptor>
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 and bean B share a cache, called AB-cache, that has a size of 1000 bytes and the size of A is 10 bytes and the size of B is 20 bytes, then the cache can hold at most 100 instances of A and 50 instances of B. If 100 instance s of A are cached, this implies that 0 instances of B are cached.
See entity-cache-ref.
Indicates that a particular security role is defined externally in a security realm, outside of the deployment descriptor. Because the security role and its principal-name mapping is defined elsewhere, principal-names are not to be specified in the deployment descriptor. This tag is used as an indicative placeholder instead of a set of principal-name elements.
Valid only for CMP entity EJBs. The finders-load-bean element determines whether WebLogic Server loads the EJB into the cache after a call to a finder method returns a reference to the bean. If you set this element to True, WebLogic Server immediately loads the bean into the cache if a reference to a bean is returned by the finder. If you set this element to False, WebLogic Server does not automatically load the bean into the cache until the first method invocation; this behavior is consistent with the EJB 1.1 specification.
<entity-descriptor>
<persistence>
<finders-load-bean>True</finders-load-bean>
</persistence>
</entity-descriptor>
The global-role element is deprecated and will be removed in a future version of WebLogic. Use the externally-defined element instead.
The global-role element indicates that a particular security role is defined "globally" in a security realm. Because the security role and its principal-name mapping is defined elsewhere, principal-names are not to be specified in the deployment descriptor. This tag is used as an indicative placeholder instead of a set of principal-name elements.
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.
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.
Specifies the algorithm to use for load balancing between replicas of the EJB home in a cluster. If this element is not defined, WebLogic Server uses the algorithm specified by the server element, weblogic.cluster.defaultLoadAlgorithm.
You can define home-load-algorithm as one of the following values:
round-robin—Load balancing is performed in a sequential fashion among the servers hosting the bean.random—Replicas of the EJB home are deployed randomly among the servers hosting the bean.weight-based—Replicas of the EJB home are deployed on host servers according to the servers' current workload.round-robin-affinity—server affinity governs connections between external Java clients and server instances; round robin load balancing is used for connections between server instances.weight-based-affinity—server affinity governs connections between external Java clients and server instances; weight-based load balancing is used for connections between server instances.random-affinity—server affinity governs connections between external Java clients and server instances; random load balancing is used for connections between server instances.For more information, see Load Balancing for EJBs and RMI Objects in Using WebLogic Server Clusters.
See entity-clustering and stateful-session-clustering.
Defines list of methods of a clustered EJB which are written in such a way that repeated calls to the same method with the same arguments has exactly the same effect as a single call. This allows the failover handler to retry a failed call without knowing whether the call actually compiled on the failed server. When you enable idempotent-methods for a method, the EJB stub can automatically recover from any failure as long as it can reach another server hosting the EJB.
Clustering must be enabled for the EJB. To enable clustering, see entity-clustering, stateful-session-clustering, and stateless-clustering.
The methods on stateless session bean homes and read-only entity beans are automatically set to be idempotent. It is not necessary to explicitly specify them as idempotent.
<idempotent-method>
<method>
<description>...</description>
<ejb-name>...</ejb-name>
<method-intf>...</method-intf>
<method-name>...</method-name>
<method-params>...</method-params>
</method>
</idempotent-method>
Specifies whether the EJB supports or requires identity assertion.