<message-driven-deployment>

The <message-driven-deployment> section provides additional deployment information for a message driven bean deployed within this JAR file.

The <message-driven-deployment> section contains the following structure:

<message-driven-deployment cache-timeout=... connection-factory-location=...       destination-location=... name=... subscription-name=...
      listener-threads=... transaction-timeout=...
      dequeue-retry-count=... dequeue-retry-interval=... interceptor-type=... >
  <env-entry-mapping name=...></env-entry-mapping>
  <ejb-ref-mapping location=... name=... remote=... jndi-properties=... />
  <resource-ref-mapping location=... name=... >
    <lookup-context location=...>
       <context-attribute name=... value=... />
    </lookup-context>
  </resource-ref-mapping>
  <resource-env-ref-mapping location=... name=... />
  <message-destination-ref-mapping location=... name=... />
  <config-property>
    <config-property-name> ... </config-property-name>
    <config-property-value> ... </config-property-value>
  </config-property>
</message-driven-deployment>

Note: Alternatively, in an EJB 3.0 application, you can use the OC4J-proprietary annotation @MessageDrivenDeployment. You can use the orion-ejb-jar.xml file <message-driven-deployment> configuration to override @MessageDrivenDeployment configuration. For more information, see "Configuring OC4J-Proprietary Deployment Options on an EJB 3.0 MDB".

For information on each of these elements and sub-elements, see: the following

• <message-driven-deployment> Attributes

• <env-entry-mapping>

• <ejb-ref-mapping>

• <resource-ref-mapping>

• <resource-env-ref-mapping>

• <message-destination-ref-mapping>

• <config-property>

Examples

A message-driven bean example, which includes the <message-driven-deployment> element, is described in the following:

• "Implementing an EJB 3.0 Message-Driven Bean"

• "Implementing an EJB 2.1 Message-Driven Bean"

• "Configuring OC4J-Proprietary Deployment Options on an EJB 3.0 Session Bean"

<message-driven-deployment> Attributes

Table A-3 lists the attributes of the <message-driven-deployment> element that you can use to configure message service options. This table also lists the following corresponding configuration alternatives:

• attributes of the @MessageDrivenDeployment annotation;

• activation configuration property names that you can use in the following annotations and elements:

  • <config-property> element owned by a <message-driven-deployment> element;

  • @ActivationConfigProperty annotation owned by a @MessageDrivenDeployment or @MessageDriven annotation.

Note: If you configure using attributes, your application can only access a message service provider without a J2CA resource adapter. If later you decide to access your message service provider using a J2CA resource adapter, your application will fail to deploy. If you configure using activation configuration properties, your application can access a message service provider with or without a J2CA resource adapter. Oracle recommends that you use <config-property> or @ActivationConfigProperty options.

For more information, see the following:

• "Message Service Configuration Options: Annotations or XML? Attributes or Activation Configuration Properties?"

• "What Message Service Providers Can you use With Your MDB?"

Table A-3 Attributes for the <message-driven-deployment> Element

<message-driven-deployment> Attribute	@MessageDrivenDeployment Attribute	Description	Activation Configuration Property NameFoot 1
cache-timeout	poolCacheTimeout	This parameter specifies how long to keep message-driven beans cached in the pool. If you specify a pool cache-timeout, then at every cache timeout interval, all beans of the corresponding bean type in the pool are removed. If the value specified is zero or negative, then the cache timeout is disabled and beans are not removed from the pool. The default value is 60 (seconds).	N/A
connection-factory-location	N/A	The JNDI location of the connection factory to use. The JMS Destination Connection Factory is specified in this attribute. The syntax is java:comp/resource + resource provider name + TopicConnectionFactories OR QueueConnectionFactories + user defined name. The nnnConnectionFactories details what type of factory is being defined.	See ConnectionFactoryJndiName in Table B-1.
dequeue-retry-count	dequeueRetryCount	Specifies how often the listener thread tries to re-acquire the JMS session once database failover has ocurred. This is applicable to only container-managed transactions in an MDB. The default value is 0. For more information, see the following: "Configuring Connection Failure Recovery for an EJB 2.1 MDB" "Understanding OC4J EJB Application Clustering Services"	N/A See EndpointFailureRetryInterval in Table B-2.
dequeue-retry-interval	dequeueRetryInterval	Specifies the interval between retries. The default value is 60 seconds. For more information, see the following: "Configuring Connection Failure Recovery for an EJB 2.1 MDB" "Understanding OC4J EJB Application Clustering Services"	N/A See EndpointFailureRetryInterval in Table B-2.
destination-location	destinationLocation	The JNDI location of the destination (queue/topic) to use. The JMS Destination is specified in the destination-location attribute. The syntax is java:comp/resource + resource provider name + Topics OR Queues + Destination name. The Topic or Queue details what type of Destination is being defined. The Destination name is the actual queue or topic name defined in the database.	See DestinationName in Table B-1.
interceptor-type	interceptorType	The attribute indicates how OC4J handles interceptor class life cycle. You can set the interceptor type to bean (stateful class) or singleton (stateless class). When set to bean, OC4J creates a separate interceptor class instance for each session bean instance that you associate with that interceptor class. This is in accordance with the EJB 3.0 specification. In this case, the interceptor class must be stateful. When set to singleton, OC4J creates a single interceptor class instance that all session bean instances share. In this case, the interceptor class must be stateless. For more information, see "Singleton Interceptors".	N/A
listener-threads	listenerThreads	The listener threads are used to concurrently consume JMS messages. The default is one thread. Topics can only have one thread. Queues can have more than one. For more information, see "Configuring Parallel Message Processing".	See ReceiverThreads in Table B-2.
max-delivery-count	maxDeliveryCount	The maximum number of times OC4J will attempt the immediate redelivery 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). After this number of redeliveries, the message is deemed undeliverable and is handled according to the policies of your message service provider. For example, OEMS JMS will put the message on its exception queue (jms/Oc4jJmsExceptionQueue). For more information, see "Configuring Maximum Delivery Count".	See MaxDeliveryCnt in Table B-2.
max-instances	maxInstances	The maximum number of bean implementation instances to be kept instantiated or pooled. The default is 0, which means infinite. To disable instance pooling, set max-instances to any negative number. This will create a new instance at the start of the EJB call and release it at the end of the call. For message-driven beans, the default pooling setting is typically appropriate. Change this value only if MDB life cycle methods are very expensive and you need fine-grained control over how often instances are created and managed in the pool. See "Configuring Bean Instance Pool Size" for more information.	N/A
min-instances	minInstances	The minimum number of bean implementation instances to be kept instantiated or pooled. The default value is 0. See "Configuring Bean Instance Pool Size" for more information.	N/A
name	name	The name of the bean, which matches the name of a bean in the assembly section of the EJB deployment descriptor (ejb-jar.xml).	N/A
resource-adapter	resourceAdapter	The name of the resource adapter instance that this MDB uses. Applicable only if this MDB is using a J2CA message service provider. In order for the MDB to be activated by messages received by the resource adapter, the MDB and resource adapter must be connected. For more information, see "Configuring a J2CA Resource Adapter for use With Your Message Service Provider".	N/A
subscription-name	subscriptionName	The name of the topic to which this message-drive bean subscribes.	See SubscriptionName in Table B-2.
transaction-timeout	transactionTimeout	This attribute controls the transaction timeout interval (in seconds) for any container-managed transactional MDB. The default is one day or 86,400 seconds. If the transaction has not completed in this time frame, the transaction is rolled back. This applies to both normal JMS and J2CA resource adapter-based message providers. For more information, see "Configuring a Transaction Timeout for a Message-Driven Bean"	See TransactionTimeout in Table B-2.

^Footnote 1 For use in a <message-driven-deployment> element <config-property> subelement, or in an @ActivationConfigProperty annotation owned by a @MessageDrivenDeployment or @MessageDriven annotation.

<env-entry-mapping>

The <env-entry-mapping> element maps environment variables to JNDI names and is discussed in "Configuring an Environment Reference to an Environment Variable".

<ejb-ref-mapping>

The <ejb-ref-mapping> element maps any EJB references to JNDI names and is discussed in "EJB Environment References".

<resource-ref-mapping>

The <resource-ref-mapping> element maps any resource manager references to JNDI names and is discussed in "Resource Manager Connection Factory Environment References".

<resource-env-ref-mapping>

The <resource-env-ref-mapping> element is used to map an administered object for a resource. For example, to use JMS, the bean must obtain both a JMS factory object and a destination object. These objects are retrieved at the same time from JNDI. The <resource-ref> element declares the JMS factory and the <resource-env-ref> element is used to declare the destination. Thus, the <resource-env-ref-mapping> element maps the destination object. See "Configuring an Environment Reference to a JMS Destination or Connection Resource Manager Connection Factory (JMS 1.0)" for more information.

<message-destination-ref-mapping>

The <message-destination-ref-mapping> element is only used if you are using JMS 1.1. Use this element to map the message-destination-ref-name in the client deployment descriptor to another location that is available in the OC4J environment. It provides means of linking message consumers and producers to one or more common logical destinations. For more information, see "Configuring an Environment Reference to a JMS Destination Resource Manager Connection Factory (JMS 1.1)".

<config-property>

The <config-property> element is only used if you are using a J2CA message service provider. Use this element to set J2CA resource adapter configuration properties. When OC4J deploys an MDB configured to use a J2CA message service provider, OC4J provides the MDB's activation specification to the resource adapter. This specification includes the properties you set in the <config-property> element.

Alternatively, for an EJB 3.0 message-driven bean, you can set J2CA resource adapter configuration properties using @MessageDriven attribute configProperty and @ActivationConfig annotation.

You can use the orion-ejb-jar.xml file <config-property> configuration to override @MessageDriven configuration.

For more information, see the following:

• "Configuring an EJB 3.0 MDB to Access a Message Service Provider Using J2CA"

• "Configuring an EJB 2.1 MDB to Access a Message Service Provider Using J2CA"