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 4.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:

  • 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 Beans, Version 4.0, for Oracle WebLogic Server. For elements in ejb-jar.xml, see the schema at https://jakarta.ee/xml/ns/jakartaee/ejb-jar_4_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 4.0 Compliant MDBs.

    Note:

    Based on the Enterprise Bean 4.0 specification, the jakarta.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

Specifies the JMS acknowledgement mode for messages received outside a transaction. For container-managed message delivery with the Required transaction attribute, acknowledgement is controlled by transaction completion.

Auto-acknowledge — Automatically acknowledges messages according to the provider's nontransactional delivery semantics, typically after the message has been successfully processed.

Dups-ok-acknowledge — Allows lazy acknowledgement, which can result in duplicate message delivery.

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 connection factory that the MDB uses to create connections to the JMS provider. See How to Set connection-factory-jndi-name.

Valid JNDI name

weblogic.jms.MessageDrivenBeanConnectionFactory

connection-factory-resource-link

(weblogic-ejb-jar.xml)

connectionFactoryResourceLink

Identifies an existing connection factory in a packaged JMS application module. For existing applications using these modules, see Using Application-Scoped JMS Resources.

JMSModuleName#ResourceName, where JMSModuleName matches the module's name in weblogic-application.xml, and ResourceName matches the resource's name in that 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

Identifies an existing queue or topic in a packaged JMS application module. For existing applications using these modules, see Using Application-Scoped JMS Resources.

JMSModuleName#ResourceName, where JMSModuleName matches the module's name in weblogic-application.xml, and ResourceName matches the resource's name in that 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.

A configured Work Manager name or a legacy 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)

generateUniqueID member of @weblogic.javaee.JMSClientID, for example, @weblogic.javaee.JMSClientID(value = "MyClient", generateUniqueID = true).

Controls whether WebLogic generates unique JMS client IDs for MDB connections in Compatibility mode. It does not assign a separate client ID to each pooled MDB instance. In the One-Copy modes, JMS client IDs are determined by the selected distribution mode's behavior. See Topic Subscription Identifiers.

  • 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.

WebLogic descriptor: 0 through 2147483647

0

initial-context-factory

(weblogic-ejb-jar.xml)

initialContextFactory

The initial context factory used to create the JNDI context in which the container looks up the JMS connection factory and destination. 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.

WebLogic descriptor: non-negative integer, 0 through 2147483647

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-jms-client-id. See Topic Subscription Identifiers.

jms-client-id

(weblogic-ejb-jar.xml)

jmsClientId

WebLogic-specific configuration of the MDB's JMS client ID. Its use and the effective ID depend on the topic distribution mode. See Topic Subscription Identifiers.

n/a

Depends on the topicMessagesDistributionMode activation config property and possibly on generate-unique-jms-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.

WebLogic descriptor: non-negative integer, 0 through 2147483647

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.

WebLogic descriptor: 0 through 2147483647

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.

WebLogic descriptor: positive integer, 1 through 2147483647

1

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.

WebLogic descriptor: non-negative integer, 0 through 2147483647

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.

  • jakarta.jms.Queue

  • jakarta.jms.Topic

n/a

activation-config-property (ejb-jar.xml)

messagesMaximum

Overrides the WebLogic JMS session's Messages Maximum setting, which limits the number of prefetched messages awaiting delivery to the MDB listener. The limit applies to asynchronous delivery and to synchronous prefetch when enabled. At the limit, further messages are retained on the server until the client can accept them. This property is ignored for foreign JMS providers.

-1 for no configured message-count limit, or 1 through 2147483647. Do not specify 0.

No MDB override. The session uses the JMS connection factory's Messages Maximum setting; the WebLogic connection-factory default is 10.

activation-config-property (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)

messageListenerInterface member of @jakarta.ejb.MessageDriven, for example, @jakarta.ejb.MessageDriven(messageListenerInterface = jakarta.jms.MessageListener.class).

Identifies the message listener interface implemented by the MDB. For JMS delivery, this is jakarta.jms.MessageListener; resource-adapter delivery can use the listener interface supported by that adapter.

The fully qualified name of a supported message listener interface.

Inferred from the bean class when the message listener interface can be determined unambiguously. Otherwise, specify the interface explicitly.

provider-url

(weblogic-ejb-jar.xml)

providerURL

The provider URL used to create the JNDI context for the JMS resource lookups, for example, t3://host:port for WebLogic Server. The URL syntax depends on the JNDI provider. 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

activation-config-property (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

Specifies the topic subscription name. WebLogic's direct JMS MDB integration uses this property for durable subscriptions. For resource-adapter delivery, supported use depends on the resource adapter.

A subscription-name string.

For durable subscriptions in WebLogic's direct JMS integration, the name is derived from the MDB-generated client-ID expression in Compatibility mode and from the EJB name in the One-Copy modes. See Topic Subscription Identifiers. For resource-adapter delivery, consult the adapter's configuration.

activation-config-property (ejb-jar.xml)

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)

value member of @TransactionManagement (TransactionManagementType.BEAN or TransactionManagementType.CONTAINER). Example on the MDB class: 

@jakarta.ejb.TransactionManagement(jakarta.ejb.TransactionManagementType.CONTAINER)

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)

value member of @TransactionAttribute. Example on the MDB's message listener method: 

@jakarta.ejb.TransactionAttribute(jakarta.ejb.TransactionAttributeType.REQUIRED)

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

Note: If 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.

For message listener methods: Required or NotSupported. For timeout callback methods: Required, RequiresNew or NotSupported. The corresponding annotation values are REQUIRED, REQUIRES_NEW and NOT_SUPPORTED, subject to the same method restrictions.

Required

trans-timeout-seconds

(weblogic-ejb-jar.xml)

value member of @weblogic.javaee.TransactionTimeoutSeconds. Example on the MDB class: @weblogic.javaee.TransactionTimeoutSeconds(60).

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.

Non-negative integer, 0 through 2147483647.

When no MDB timeout is supplied, or its effective value is 0, the domain JTA timeout is used; the domain default is 30 seconds. A @TransactionTimeoutSeconds annotation with no argument specifies 30 seconds, unless overridden by the deployment descriptor.

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 AQ 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.

Dynamic session closing does not apply to non-durable topic subscriptions.

  • True

  • False

False