1. Developing Message-Driven Beans for Oracle WebLogic Server
  2. Deployment Elements and Annotations for MDBs

11 Deployment Elements and Annotations for MDBs

Examine the deployment elements and configuration properties that affect the behavior of MDBs.

Each row in Table 11-1 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 versus using annotations in MDBs, see Programming EJB 3.2 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:

  • Each element in the Element column is followed in parentheses by the name of the deployment descriptor in which the element is used. Elements in the weblogic-ejb-jar.xml descriptor link to a more complete explanation of the element in weblogic-ejb-jar.xml Deployment Descriptor Reference in Developing Enterprise JavaBeans, Version 2.1, for Oracle WebLogic Server. For elements in ejb-jar.xml, see the schema at http://xmlns.jcp.org/xml/ns/javaee/ejb-jar_3_0.xsd.

  • Unless otherwise noted, all the properties listed in the Configuration Property column are activation configuration properties, that is, properties defined using @ActivationConfigProperty annotations or using an activation-config-property element in the message-driven stanza of an ejb-jar.xml descriptor. For more information about using @ActivationConfigProperty, see Programming EJB 3.2 Compliant MDBs.

    Note:

    Based on the Enterprise JavaBean specification, the javax.ejb.ActivationConfigProperty annotation is used for MDBs only. This annotation is not used for session or entity beans.

  • The Configuration Property column also lists annotations and properties that are not @ActivationConfigProperty properties. In those cases, the property is followed by the name of the annotation and by the import statement required for using that annotation.

Table 11-1 Deployment Elements and Annotations for MDBs

Element Configuration Property Description Allowable Values Default

activation-config-property

(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)

connectionFactoryLookup

The lookup name of a JMS connection factory that will be used to connect to the JMS provider from which a JMS message-driven bean is to receive messages.

Valid lookup name

weblogic.jms.MessageDrivenBeanConnectionFactory

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 Oracle WebLogic Server. Rarely used.

Valid resource within a JMS module

n/a

destination-jndi-name

(weblogic-ejb-jar.xml)

destinationLookup

The lookup name of a JMS queue or topic from which a JMS message-driven bean is to receive messages.

Valid lookup name

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 Oracle 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 Oracle 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 Tuning Performance of 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 Oracle WebLogic Server instance. May not apply to all use cases. See JMS Distributed Destinations, and 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 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. Oracle 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)

clientID

The client identifier that will be used when connecting to the JMS provider from which a JMS message-driven bean is to receive messages.

n/a

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

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 Topic Subscription Identifiers.

n/a

Depends on the topicMessagesDistributionMode activation config property and possibly on generate-unique-client-id. See 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 Tuning Performance of 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

messages-maximum

(weblogic-ejb-jar.xml)

messagesMaximum

The maximum number of messages that can exist for an asynchronous session, which have not yet been passed to the message listener. A value of -1 indicates that there is no limit on the number of messages. In this case, however, the limit is set to the amount of remaining virtual memory.

When the number of messages reaches the specified value, the following occurs:

  • For multicast sessions, new messages are discarded according to the specified overrun policy, and a DataOverrunException is thrown.

  • For non-multicast sessions, new messages are flow-controlled, or retained on the server until the application can accommodate the messages.

For multicast sessions, when a connection is stopped, messages will continue to be accumulated, but only until the specified maximum value is reached. Once this value is reached, messages will be discarded based on the overrun policy.

-1 and 1–263-1

10

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 Oracle 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 Oracle 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 Oracle 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

activation-config-property

(ejb-jar.xml)

subscriptionName

The name of the subscription if the message-driven bean is intended to receive messages published to a topic. You can set this property for durable or non-durable topic subscribers.

n/a

n/a

n/a

topicMessagesDistributionMode

Sets the distribution mode for topic messages. See 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 time-out 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 time-out is not specified or is set to 0, the transaction time-out configured for the domain is used. If a time-out is not configured for the domain, the default is 30.

use81-style-polling

(weblogic-ejb-jar.xml)

use81StylePolling

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

  • True

  • False

False

activation-config-property

(ejb-jar.xml)

aqMDBReceiveNoWait

If AQ JMS is the JMS provider for the MDB and this property is set to true, synchronous polling uses the MessageConsumer.receiveNoWait() method to optimize QA JMS dequeue performance.

  • True

  • False

False

activation-config-property

(ejb-jar.xml)

mdbDestinationPollIntervalMillis

 When the JMS destination has no messages and synchronous polling is used for MDB, this property sets the message polling interval in milliseconds. When MDB interoperates with AQ JMS and minimizeAQSessions is set to true, you can avoid database connection usage bursts by setting this property to a value that is greater than 5000. This configuration randomly starts message polling when multiple MDBs are started.

> or = 0 (Integer)

0

activation-config-property

(ejb-jar.xml)

minimizeAQSessions

This property is only used when MDB interoperates with AQ JMS. When this property is set to true, it reduces database resource usage by dynamically closing AQ JMS sessions.

  • True

  • False

False

activation-config-property

(ejb-jar.xml)

TopicMessagePartitionMode

When MDBs that are deployed to different partitions subscribe to the same topic destination, this property controls MDB topic subscription sharing among partitions in a WebLogic Server multitenant (MT) environment.

  • Isolated

  • Shared

Isolated