11 Deployment Elements and Annotations for MDBs

Table 11-1 shows deployment elements and configuration properties that affect the behavior of MDBs. Each row in the table describes a deployment element (used in an EJB deployment descriptor) and its associated configuration property (specified in annotations). Not all elements have associated properties.

For information about using deployment descriptors vs. using annotations in MDBs, see Programming EJB 3.0 Compliant MDBs.

Note:

For those elements that have an associated configuration property, Oracle recommends that you use that property instead of the element.

Table 11-1 is organized as follows:

Table 11-1 Deployment Elements and Annotations for MDBs

Element Configuration Property Description Allowable Values Default

acknowledge-mode

(ejb-jar.xml)

acknowledgeMode

Notifies the JMS provider that the message was received and processed. The acknowledgement mode is ignored if using container-managed transactions. (The acknowledgement is performed in the context of the transaction.)

  • AUTO_ACKNOWLEDGE - the message is acknowledged immediately

  • DUPS_OK_ACKNOWLEDGE - the acknowledgement may be delayed, allowing duplicate messages to be received

AUTO_ACKNOWLEDGE

connection-factory-jndi-name

(weblogic-ejb-jar.xml)

connectionFactoryJndiName

The JNDI name of the JMS ConnectionFactory that the MDB looks up to create its queues and topics. See How to Set connection-factory-jndi-name.

Valid JNDI name

weblogic.jms.MessageDrivenBeanConnectionFactory

connection-factory-resource-link

(weblogic-ejb-jar.xml)

connectionFactoryResourceLink

Maps to a resource within a JMS module defined in ejb-jar.xml to an actual JMS Module Reference in WebLogic Server. Rarely used.

Valid resource within a JMS module

n/a

destination-jndi-name

(weblogic-ejb-jar.xml)

destinationJndiName

The JNDI name used to associate an MDB with an actual JMS queue or topic deployed in the WebLogic Server JNDI tree. See How to Set destination-jndi-name.

Valid JNDI name

n/a

destination-resource-link

(weblogic-ejb-jar.xml)

destinationResourceLink

Maps to a resource within a JMS module defined in ejb-jar.xml to an actual JMS Module Reference in WebLogic Server. Rarely used.

Valid resource within a JMS module

n/a

dispatch-policy

(weblogic-ejb-jar.xml)

n/a

This optional element allows you to specify a particular WorkManager for the bean. See "Tuning Message-Driven Beans" in Performance and Tuning for Oracle WebLogic Server.

Valid execute queue name

n/a

distributed-destination-connection

(weblogic-ejb-jar.xml)

distributedDestinationConnection

Specifies whether an MDB that accesses a WebLogic JMS distributed destination (topic or queue) in the same cluster consumes from all distributed destination members or only those members local to the current WebLogic Server instance. May not apply to all use cases. See JMS Distributed Destinations, and Chapter 10, "Configuring and Deploying MDBs Using JMS Topics."

  • LocalOnly

  • EveryMember

LocalOnly

durable-subscription-deletion

(weblogic-ejb-jar.xml)

durableSubscriptionDeletion

Indicates whether you want durable topic subscriptions to be automatically deleted when an MDB is undeployed or removed.

  • True

  • False

False

generate-unique-jms-client-id

(weblogic-ejb-jar.xml)

See the generateUniqueClientID attribute of the weblogic.javaee.JMSClientID annotation.

Indicates whether or not you want the EJB container to generate a unique client-id for every instance of an MDB. This setting should be used only when topicMessagesDistributionMode is set to Compatibility (the default). See Chapter 10, "Configuring and Deploying MDBs Using JMS Topics."

  • True

  • False

False

initial-beans-in-free-pool

(weblogic-ejb-jar.xml)

n/a

Sets the initial size of the free 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 MDB, because initial requests for the bean can be satisfied without generating a new instance.

0 to maxBeans

0

initial-context-factory

(weblogic-ejb-jar.xml)

initialContextFactory

The initial context factory that the EJB container uses to create its connection factories. See How to Set initial-context-factory.

Valid name of an initial context factory

weblogic.jndi.WLInitialContextFactory

init-suspend-seconds

(weblogic-ejb-jar.xml)

initSuspendSeconds

The initial number of seconds to suspend an MDB's JMS connection when the EJB container detects a JMS resource outage. See Configuring Suspension of Message Delivery During JMS Resource Outages.

Any integer

5

jms-client-id

(weblogic-ejb-jar.xml)

jmsClientId

The client ID for the MDB when it connects to a JMS destination. Optional. Used for durable subscriptions to JMS topics. For more information, see Appendix B, "Topic Subscription Identifiers."

n/a

Depends on the topicMessagesDistributionMode activation config property and possibly on generate-unique-client-id. See Appendix B, "Topic Subscription Identifiers")

jms-polling-interval-seconds

(weblogic-ejb-jar.xml)

jmsPollingIntervalSeconds

The number of seconds between attempts by the EJB container to reconnect to a JMS destination that has become unavailable. See Migration and Recovery for Clustered MDBs.

Any integer

10 seconds

max-beans-in-free-pool

(weblogic-ejb-jar.xml)

n/a

The maximum number of bean instances in an MDB free pool. The actual number of instances is also limited by thread pool size as well as other factors. See "Tuning Message-Driven Beans" in Performance and Tuning for Oracle WebLogic Server.

0 to maxBeans

1000

max-messages-in-transaction

(weblogic-ejb-jar.xml)

maxMessagesInTransaction

Specifies the maximum number of messages that can be in a transaction for this MDB.

All positive integers

n/a

max-suspend-seconds

(weblogic-ejb-jar.xml)

maxSuspendSeconds

The maximum number of seconds to suspend an MDB's JMS connection when the EJB container detects a JMS resource outage. See Configuring Suspension of Message Delivery During JMS Resource Outages.

Any integer

60

message-destination-type

(ejb-jar.xml)

destinationType

Specifies the type of the JMS destination—the Java interface expected to be implemented by the destination.

  • javax.jms.Queue

  • javax.jms.Topic

n/a

message-selector

(ejb-jar.xml)

messageSelector

A string used by a client to specify, by header field references and property references, the messages it is interested in. Only messages whose header and property values match the selector are delivered

Conditional expression using message properties, or message header

Null

messaging-type

(ejb-jar.xml)

n/a

Rarely used.

javax.jms.MessageListener

n/a

provider-url

(weblogic-ejb-jar.xml)

providerURL

The URL provider to be used by the InitialContext. Typically, this is the host:port. See How to Set provider-url.

Valid URL

Null

resource-adapter-jndi-name

(weblogic-ejb-jar.xml)

resourceAdapterJndiName

For JCA-driven MDBs, identifies the resource adapter from which this MDB receives messages.

n/a

n/a

security-role-assignment

(weblogic-ejb-jar.xml)

n/a

Maps application roles in the ejb-jar.xml file to the names of security principals available in WebLogic Server.

n/a

n/a

start-mdbs-with-application

(weblogic-application.xml)

n/a

Controls when MDBs start processing messages. When set to true, an MDB starts processing messages as soon as it is deployed, even if WebLogic Server has not completed booting. This can cause an MDB application to access uninitialized services or applications during boot up and, therefore, to fail.

Set to false to defer message processing until after WebLogic Server opens its listen port.

  • True

  • False

False

subscription-durability

(ejb-jar.xml)

subscriptionDurability

Specifies whether a JMS topic subscription is Durable or NonDurable. For more information, see Setting Subscription Durability.

  • Durable

  • NonDurable

NonDurable

n/a

topicMessagesDistributionMode

Sets the distribution mode for topic messages. See Chapter 10, "Configuring and Deploying MDBs Using JMS Topics.".

  • One-Copy-Per-Application

  • One-Copy-Per-Server

  • Compatibility

Compatibility

transaction-type

(ejb-jar.xml)

See trans-attribute

Specifies an enterprise bean's transaction management type. For more information, see Configuring Transaction Management Strategy for an MDB.

  • Bean

  • Container

Container

trans-attribute

(ejb-jar.xml)

TransactionAttributeType property of @TransactionAttribute, for example:

import javax.ejb.TransactionAttribute
@TransactionAttribute(TransactionAttributeType.REQUIRED)

Specifies how the container must manage the transaction boundaries when delegating a method invocation to an enterprise bean's business method.

Note: f the bean is specified as using container-managed transaction demarcation, either the REQUIRED or the NOT_SUPPORTED transaction attribute must be used for the message listener methods, and either the REQUIRED, REQUIRES_NEW, or the NOT_SUPPORTED transaction attribute for timeout callback methods. For more information, see Configuring Transaction Management Strategy for an MDB.

  • Required

  • NotSupported

  • Supports

  • RequiresNew

  • Mandatory

  • Never

Required

trans-timeout-seconds

(weblogic-ejb-jar.xml)

@TransactionTimeoutSeconds

import weblogic.javaee.TransactionTimeoutSeconds

The maximum duration for an EJB's container-initiated transactions, in seconds, after which the transaction is rolled back. See Configuring Transaction Management Strategy for an MDB.

0 to max

If the transaction timeout is not specified or is set to 0, the transaction timeout configured for the domain is used. If a timeout is not configured for the domain, the default is 30.

use81-style-polling

(weblogic-ejb-jar.xml)

use81StylePolling

Enables backwards compatibility for WebLogic Server version 8.1-style polling.

  • True

  • False

False