| Oracle® Containers for J2EE Enterprise JavaBeans Developer's Guide 10g Release 3 (10.1.3) B14428-02 |
|
 Previous |
 Next |
| Oracle® Containers for J2EE Enterprise JavaBeans Developer's Guide 10g Release 3 (10.1.3) B14428-02 |
|
Previous |
Next |
This chapter describes the various options that you must configure in order to use an EJB 2.1 message-driven bean.
Table 18-1 lists these options and indicates which are basic (applicable to most applications) and which are advanced (applicable to more specialized applications).
For more information, see:
Table 18-1 Configurable Options for an EJB 2.1 Message-Driven Bean
You can configure an EJB 3.0 MDB to use a non-J2CA message service provider using deployment XML (see "Using Deployment XML").
For more information, see:
You can use the ejb-jar.xml or orion-ejb.jar.xml file. You use the orion-ejb-jar.xml file configuration to override settings in ejb-jar.xml or to add OC4J-specific settings. For example, the connection factory and destination name that you define in ejb-jar.xml may be logical names that may not exist in your local JNDI environment. The deployer can override these settings in the orion-ejb-jar.xml file and map them to the actual names. For more information on mapping logical names, see "Configuring an Environment Reference to a JMS Destination or Connection Resource Manager Connection Factory (JMS 1.0)".
Example 18-1 shows how to configure ejb-jar.xml to configure a message-driven bean to use a non-J2CA JMS message service provider. It assumes that you have defined connection factory jms/MyQCF and queue jms/MyQueue in the jms.xml file. For more information on configuring a non-J2CA message service provider, see "Configuring an OracleAS JMS Message Service Provider" or "Configuring an OJMS Message Service Provider".
Example 18-1 ejb-jar.xml for a Non-J2CA Message Service Provider
<message-driven>
<ejb-name>QueueMDB</ejb-name>
<ejb-class>test.QueueMDB</ejb-class>
<message-destination-type>javax.jms.Queue</message-destination-type>
<transaction-type>Container</transaction-type>
<activation-config>
<activation-config-property>
<activation-config-property-name>
ConnectionFactoryJndiName
</activation-config-property-name>
<activation-config-property-value>
jms/MyQCF
</activation-config-property-value>
</activation-config-property>
<activation-config-property>
<activation-config-property-name>
DestinationName
</activation-config-property-name>
<activation-config-property-value>
jms/MyQueue
</activation-config-property-value>
</activation-config-property>
</activation-config>
</message-driven>
For a complete list of all activation configuration properties, download and unzip one of the how-to-gjra-with-xxx.zip files from http://www.oracle.com/technology/tech/java/oc4j/1013/how_to/index.html, where xxx is the name of the relevant resource provider. The orion-ejb-jar.xml demo file contains comments describing all activation configuration properties. For more information, see "JMS Resource Adapter" in the Oracle Containers for J2EE Services Guide.
The actual names you use depend on your message service provider installation. For more information, see:
You can configure an EJB 3.0 MDB to use a J2CA message service provider using deployment XML (see "Using Deployment XML").
For more information, see "J2EE Connector Architecture (J2CA) Adapter Message Provider".
You must use both ejb-jar.xml and orion-ejb.jar.xml file. You use the orion-ejb-jar.xml file configuration to override settings in ejb-jar.xml and to add the OC4J-specific setting for resource adapter. For example, the connection factory and destination name that you define in ejb-jar.xml may be logical names that may not exist in your local JNDI environment. The deployer can override these settings in the orion-ejb-jar.xml file and map them to the actual names. For more information on mapping logical names, see "Configuring an Environment Reference to a JMS Destination or Connection Resource Manager Connection Factory (JMS 1.0)".
To configure an EJB 3.0 MDB to use a J2CA message service provider:
Configure the ejb-jar.xml file.
Example 18-2 shows how to configure ejb-jar.xml to configure a message-driven bean to use the Oracle JMS resource adapter named OracleASjms. It assumes that you have defined connection factory OracleASjms/MyQCF in the oc4j-ra.xml file and destination name OracleASjms/MyQueue in the oc4j-connectors.xml. For more information on configuring a J2CA message service provider, see "Configuring a Message Service Provider Using J2CA". To complete this configuration, you must
Example 18-2 ejb-jar.xml for a J2CA Message Service Provider
<message-driven>
<ejb-name>JCA_QueueMDB</ejb-name>
<ejb-class>test.JCA_MDB</ejb-class>
<messaging-type>javax.jms.MessageListener</messaging-type>
<transaction-type>Container</transaction-type>
<activation-config>
<activation-config-property>
<activation-config-property-name>
DestinationType
</activation-config-property-name>
<activation-config-property-value>
javax.jms.Queue
</activation-config-property-value>
</activation-config-property>
<activation-config-property>
<activation-config-property-name>
DestinationName
</activation-config-property-name>
<activation-config-property-value>
OracleASjms/MyQueue
</activation-config-property-value>
</activation-config-property>
<activation-config-property>
<activation-config-property-name>
ConnectionFactoryJndiName
</activation-config-property-name>
<activation-config-property-value>
OracleASjms/MyQCF
</activation-config-property-value>
</activation-config-property>
</activation-config>
</message-driven>
Configure the orion-ejb-jar.xml file.
Example 18-3 shows how to configure the orion-ejb-jar.xml to configure this message-driven bean to use the Oracle JMS resource adapter named OracleASjms. You must set the resource-adapter attribute. Optionally, you can override or configure additional activation configuration properties using one or more config-property elements.
Example 18-3 orion-ejb-jar.xml for a J2CA Message Service Provider
<message-driven-deployment
name="JCA_QueueMDB"
resource-adapter="OracleASjms">
...
<config-property>
<config-property-name>DestinationName</config-property-name>
<config-property-value>OracleASJMSRASubcontext/MyQ</config-property-value>
</config-property>
...
</message-driven-deployment>
For a complete list of all activation configuration properties, download and unzip one of the how-to-gjra-with-xxx.zip files from http://www.oracle.com/technology/tech/java/oc4j/1013/how_to/index.html, where xxx is the name of the relevant resource provider. The orion-ejb-jar.xml demo file contains comments describing all activation configuration properties. For more information, see "JMS Resource Adapter" in the Oracle Containers for J2EE Services Guide.
You may also set the optional attributes that Table A-3 lists.
The actual names you use depend on your message service provider installation. For more information, see "J2CA Message Service Provider Connection Factory Names".
When you use an MDB, it is blocked in a receive state waiting for incoming messages. In a non-Windows environment, if you shutdown OC4J while the MDB is in a wait state, OC4J shuts down in a timely fashion.
If you are using message-driven beans with the OJMS provider (see "Oracle JMS (OJMS) Provider: Advanced Queueing (AQ)-Based") and OC4J is running in a Windows environment or when the back-end database is running in a Windows environment and you shutdown OC4J while an MDB is in a wait state, then the OC4J instance cannot be stopped and the MDB cannot be undeployed in a timely manner: in this case, the OC4J process will hang for at least 2.5 hours
Using the oracle.mdb.fastUndeploy system property (see "Using System Properties"), you can modify the behavior of the MDB in the Windows environment to ensure that your message-driven beans can be undeployed, and OC4J can be shut down, in a timely manner, when necessary.
The oracle.mdb.fastUndeploy system property is set to the frequency, as an integer number of seconds, at which OC4J polls the database (requiring a database round-trip) to determine whether or not the session is shut down when an MDB is not processing incoming messages and in a wait state.
For optimal performance, a reasonable value should be 120 seconds or more.
If you set this property to 120 (seconds), then every 120 seconds, OC4J will poll the database.
If your MDB application uses OJMS with an Oracle RAC database, you must configure your application to handle a database failover scenario, as follows:
Configure message-driven beans to retry if message dequeing fails (see "Using Deployment XML")
Configure the MDB client to retry if connection acquisition fails (see "Using Java")
|
Note: The RAC-enabled attribute of a data source is discussed in Data Sources chapter in the Oracle Containers for J2EE Services Guide. |
To support RAC failover, you must configure orion-ejb-jar.xml file element message-driven-deployment attributes dequeue-retry-count and dequeue-retry-interval as Example 18-4 shows.
The dequeue-retry-count attribute tells the container how many times to retry the database connection in case a failure happens; the default is 0 seconds.
The dequeue-retry-interval attribute tells the container how long to wait between retry attempts to accommodate for the time it takes for RAC database failover to complete; the default value is 60 seconds.
Example 18-4 orion-ejb-jar.xml For Oracle RAC Failover with an MDB
<message-driven-deployment name="MessageBeanTpc" connection-factory-location="java:comp/resource/cartojms1/TopicConnectionFactories/aqTcf" destination-location="java:comp/resource/cartojms1/Topics/topic1" subscription-name="MDBSUB" dequeue-retry-count=3 dequeue-retry-interval=90/> ...
To support RAC failover, you must configure a standalone OJMS client running against an RAC database to retry if connection acquisition fails.
Oracle recommends that you use com.evermind.sql.DbUtil method oracleFatalError to determine if the connection object is invalid (see Example 18-5). If so, then reestablish the database connection if necessary.
Example 18-5 Client Retrying After Connection Acquisition Failure
import com.evermind.sql.DbUtil;
...
getMessage(QueueSesssion session)
{
try
{
QueueReceiver rcvr = session.createReceiver(rcvrQueue);
Message msgRec = rcvr.receive();
}
catch(Exception e )
{
if (exc instanceof JMSException)
{
JMSException jmsexc = (JMSException) exc;
sql_ex = (SQLException)(jmsexc.getLinkedException());
db_conn = oracle.jms.AQjmsSession)session.getDBConnection();
if ((DbUtil.oracleFatalError(sql_ex, db_conn))
{
// failover logic
}
}
}
}
By configuring the number of listener threads to x, where x is greater than one (see "Using Deployment XML"), OC4J will instantiate x number of message-driven bean instances all listening to the message-driven bean's message location in parallel.
Topics can only have one thread. Queues can have more than one.
You set the number of listener threads in the orion-ejb-jar.xml file. How you configure this value depends on the type of message-service provider you are using:
Non-J2CA Adapter Message Service Provider
If you are using a non-J2CA adapter message service provider like OracleAS JMS or Oracle JMS (OJMS), use the listener-threads attribute of the <message-driven-deployment> element.
For example, if you are using OracleAS JMS or Oracle JMS (OJMS), and you wanted to set the number of listener threads to 3, you would do as follows:
<message-driven-deployment ... listener-threads="3" ... </message-driven-deployment>
J2CA Adapter Message Service Provider
If you are using a J2CA adapter message service provider, use the <config-property> element to set the listenerThreads configuration property.
For example, if you are using a J2CA adapter message service provider, and you wanted to set the number of listener threads to 3, you would do as follows:
<message-driven-deployment ... >
...
<config-property>
<config-property-name>listenerThreads</config-property-name>
<config-property-value>3</config-property-value>
</config-property>
...
</message-driven-deployment>
In either case, if you change this property using this method, you must restart OC4J to apply your changes.
You can configure the maximum number of times OC4J will attempt the immediate re delivery of a message to a message-driven bean's onMessage method if that method returns failure: fails to invoke an acknowledgment operation, throws an exception, or both (see "Using Deployment XML").
After this number of re deliveries, the message is deemed undeliverable and is handled according to the policies of your message service provider. For example, OracleAS JMS will put the message on its exception queue (jms/Oc4jJmsExceptionQueue).
You set the maximum delivery count in the orion-ejb-jar.xml file. How you configure this value depends on the type of message-service provider you are using:
Non-J2CA Adapter Message Service Provider
If you are using a non-J2CA adapter message service provider like OracleAS JMS or Oracle JMS (OJMS), use the max-delivery-count attribute of the <message-driven-deployment> element.
For example, if you are using OracleAS JMS or Oracle JMS (OJMS), and you wanted to set the maximum delivery count to 3, you would do as follows:
<message-driven-deployment ... max-delivery-count="3" ... </message-driven-deployment>
J2CA Adapter Message Service Provider
If you are using a J2CA adapter message service provider, use the <config-property> element to set the maxDeliveryCount configuration property.
For example, if you are using a J2CA adapter message service provider, and you wanted to set the maximum delivery count to 3, you would do as follows:
<message-driven-deployment ... >
...
<config-property>
<config-property-name>MaxDeliveryCnt</config-property-name>
<config-property-value>3</config-property-value>
</config-property>
...
</message-driven-deployment>
In either case, if you change this property using this method, you must restart OC4J to apply your changes.
You can configure how often a message-driven bean's listener thread tries to re-acquire its JMS session once database failover has occurred and how many seconds to wait between retries (see "Using Deployment XML".
This value is only for CMT transactions in a message-driven bean.
For more information about failover, see "Understanding OC4J EJB Application Clustering Services".
You set the dequeue retry count and interval in the orion-ejb-jar.xml file. How you configure this value depends on the type of message-service provider you are using:
Non-J2CA Adapter Message Service Provider
If you are using a non-J2CA adapter message service provider like OracleAS JMS or Oracle JMS (OJMS), use the dequeue-retry-count and dequeue-retry-interval attribute of the <message-driven-deployment> element. The default dequeue retry count is zero and the default dequeue retry interval is 60 seconds.
For example, if you are using OracleAS JMS or Oracle JMS (OJMS), and you wanted to set the dequeue retry count to 3 and the dequeue retry interval to 90 seconds, you would do as follows:
<message-driven-deployment ... dequeue-retry-count="3" dequeue-retry-interval="90" ... </message-driven-deployment>
J2CA Adapter Message Service Provider
If you are using a J2CA adapter message service provider, use the <config-property> element to set the dequeueRetryCount and dequeueRetryInterval configuration properties.
For example, if you are using a J2CA adapter message service provider, and you wanted to set the number of listener threads to 3, you would do as follows:
<message-driven-deployment ... >
...
<config-property>
<config-property-name>DequeueRetryCount</config-property-name>
<config-property-value>3</config-property-value>
</config-property>
<config-property>
<config-property-name>dequeueRetryInterval</config-property-name>
<config-property-value>90</config-property-value>
</config-property>
...
</message-driven-deployment>
In either case, if you change this property using this method, you must restart OC4J to apply your changes.
