12 JMS Resource Adapter Deployment Descriptor Elements and Properties

acknowledgeMode

String

Set to Auto-acknowledge or Dups-ok-acknowledge. This controls the quality-of-service (QoS) provided by listener threads which consume messages and call the MDB's onMessage method.

Note: This release of the JMS resource adapter ignores this property. A QoS at least as strong as Auto-acknowledge is always used. Future versions may honor requests for Dups-ok-acknowledge.

Default is Auto-acknowledge.

clientId

String

A string value used to identify a JMS client. If set, the connection(s) used by the listener threads are set to use this value.

A clientId is required for applications interoperating with WebLogic Server JMS topics.

connectionFactory

String

The JNDI name of the connection factory.

The JMS resource adapter uses this connection factory to create the JMS connection it uses to receive messages for an MDB's onMessage. If the exception queue is enabled, the JMS Connector also uses a connection created from this connection factory for the production of messages to the exception queue.

See the description of the useExceptionQueue property, in this table, for more information.

If the onMessage method is configured to be XA transacted, then the connection factory specified by this property must XA-backed.

You must supply a connectionFactory, it cannot be a null value.

destination

String

The JNDI name of the destination.

The JMS resource adapter receives messages from this destination and passes the received messages to this MDB's onMessage.

You must supply a destination, it cannot be a null value.

destinationType

JMStype

One of the following: javax.jms.Topic, javax.jms.Queue, javax.jms.Destination.

You must supply a destinationType, it cannot be a null value.

exceptionQueue

String

The JNDI location of the jjavax.jms.Queue used as the exception queue.

See Using an Exception Queue for more information.

Required when UseExceptionQueue is true, and ignored when UseExceptionQueue is false.

FailureRetryInterval

long

The amount of time, in milliseconds, an application server waits to for a WorkManager to allocate a listener thread for an endpoint.

Default is 60,000 milliseconds.

includeBodiesInExceptionQueue

boolean

When true, messages sent to the exception queue include the message body. If many messages are sent to the exception queue during normal operation and the message body has no use in the exception queue, you can set the value to false to improve performance. This property is ignored when using an Exception Queue is false.

See Using an Exception Queue for more information.

There are two cases where this property does not apply:

• If the original message did not have a message body, then the message sent to the exception queue will not have a message body.

• If a copy of the original message can not be created for any reason, then the original may be sent to the exception queue instead. This may result in a message body being sent to the exception queue.

Default value is true.

listenerThreadMaxIdleDuration

long

The amount of time, in milliseconds, a listener thread which is not receiving any messages is kept available before being returned to the pool.

As long as an endpoint is active, idle threads are not dropped if the result it causes the number of available threads to be less than the value of minListenerThreads.

See minListenerThreads for more information.

Default value is 300,000.

loggerName

String

The name used to obtain a logger for this endpoint (see java.util.logging.Logger.getLogger).

logLevel

Level

Each log message has an associated severity level. The level gives a rough guide to the importance and urgency of a log message. Supported values are:

• ConnectionPool

• ConnectionOps

• TransactionalOps

• ListenerThreads

• INFO

• CONFIG

• FINE

• FINER

• FINEST

• SEVERE

• WARNING

• OFF

maxDeliveryCount

int

If a message has a JMSXDeliveryCount value greater than the value of MaxDeliveryCnt, the message is discarded.

If an exception queue is enabled, a copy of the message is sent to the exception queue. If the value of MaxDeliveryCnt is 0, no messages are discarded.

See the description of the useExceptionQueue property, in this table, for more information.

Note: When an MDB responds to a message by throwing an exception, the message is not considered delivered and it may be redelivered. If an MDB always respond to a given message by throwing an exception, and MaxDeliveryCnt is 0 to prevent messages from ever being discarded, the result may be an MDB stuck in an infinite loop that continuously fails to process the same message.

Default value is 5.

maxListenerThreads

int

The maximum number of listener threads created for an endpoint.

• For queues: Using more than one thread may be useful in increasing the rate at which messages are consumed.

• For topics: This value should always be 1.Each listener thread gets its own session and TopicSubscriber.

• For durable subscribers: This value can be greater than 1 if multiple topic subscribers use the same subscription name simultaneously and from multiple connections.

• For nondurable subscribers: Use one thread. Creating more threads creates more subscribers which translates into more copies of each message to process.

Default value is 1.

maxTotalListenerThreads

int

The additional number of listener threads created for an endpoint.

The JMS resource adapter implements a fairness policy for allocating threads whereby any destination which is below and needs more threads can reallocate threads from any other endpoint which has at least 2 more threads that it does.

See maxListenerThreads for more information.

This fairness policy continues functioning even if the application server's WorkManager does not grant the JMS resource adapter's requests for additional maxTotalListenerThreads new threads.

Default value is 1000.

messageSelector

String

A selector expression used to filter messages sent to the MDB's onMessage method. It is used filter messages for the JMS sessions created for the listener threads.

Default value is null, no message filtering.

minListenerThreads

int

The minimum number of listener threads created for this endpoint.

Valid values are range from 1 to maxListenerThreads.

See maxListenerThreads for more information.

If the application server allows the creation of 1 or more listener threads, but does not create that number of threads specified by MinListenerThreads, the endpoint activation does not fail and uses the available number of listener threads.

Default value is 1.

noLocal

boolean

If true, messages are not published locally.

In some cases, a connection may both publish and subscribe to a topic. The subscriber noLocal attribute allows a subscriber to inhibit the delivery of messages published by its own connection.

Default value is false.

password

String

The password of the resource provider.

See Setting User Name and Password Properties for more information

Default value is null.

providerProperties

String

A list of additional vendor specific properties defined as name/value pairs separated by a comma (",").

For example:

my_property_name=my_property_value,another_property_name=another_property_value

See WLConnection in Java API Reference for Oracle WebLogic Server.

receiveTimeout

long

The amount of time, in milliseconds, the JMS resource adapter waits for a message to arrive before exiting the current transaction.

The transaction manager limits the amount of time a transaction lasts. Set this value such that such that the transaction manager does timeout a transaction during onMessage unless there is a problem with the transaction. For example: If the transaction manager timeout is set to 30 seconds, and the onMessage routine never takes more than 10 seconds unless there is a problem with the transaction, then set this value to 200,000 (20 seconds).

Default value is 15,000.

subscriptionDurability

boolean

When Durable, specifies a subscription receives messages sent while a subscriber is not active.

Valid values are Durable or NonDurable.

Requires DestinationType of javax.jms.Topic or javax.jms.Destination) and a non-null subscriptionName property.

See the description of the useExceptionQueue property, in this table, for more information.

Default value is NonDurable.

subscriptionName

String

The reference name mapped to a subscriber when creating a durable subscriber for the listener thread.

This property is required when the value of the subscriptionDurability property is Durable and DestinationType is javax.jms.Topic or javax.jms.Destination. Ignored in all other cases.

For a given JMS server, a subscription name is assigned to at most one MDB which must have at most one listener thread.

useExceptionQueue

boolean

When true, messages that would otherwise be discarded are sent to the exception queue. Messages are normally sent to an exception queue when the maxDeliveryCount value is exceeded. Requires a valid exceptionQueue name.

See maxDeliveryCount for more information.

userName

String

The user name of the resource provider.

See Setting User Name and Password Properties for more information.

Default value is null.

group

String

The name of the group to associate with this connection definition.

See Configuring JMS Resource Adapter Connection Factory Properties for more information.

rpResourceLocation

String

Provides information to the resource adapter describing how to look up the JMS connection factory associated with the <connection-definition> element. Typically the form is: connector:connectorName/remote-jndi-name.

The macros defined in a groupDefinition may be used as values in this field.

See Configuring JMS Resource Adapter Connection Factory Properties for more information.

autoCloseSession

boolean

When true, the JMS resource adapter attempts to close sessions when closing connections.

This is a workaround for some foreign JMS providers that do not close XA connections when a session is open.

providerCustomization

String

Specifies the JMS-provider-specific custom code. The value is a fully qualified class name.

Provider custom code may customize anything for which the JMS resource adapter customization API provides a hook, which may include inbound, outbound and recovery scenarios. The ProviderCustomization property need not be set if the JMS provider's connection factories implement the public String getOracleJMSRAProviderCustomization() method. If both are specified, the ProviderCustomization property (if not set to a null or blank value) takes precedence over the getOracleJMSRAProviderCustomization() method.

clientId

String

Optional.

All connections created from this connection-definition have the JMS clientID set to the setClientId value.

This should be used only when no clientId has been preconfigured for the connection factory in the WebLogic Server instance.

group

String

The name of the group to associate with this connection definition.

See Configuring Destinations and Naming Contexts for more information.

rpResourceLocation

String

Provides information to the resource adapter describing how to look up the JMS connection factory associated with the <connection-definition> element. Typically the form is: connector:connectorName/remote-jndi-name. connectorName must be defined in the resourceProviderDefinitions.

See Basic Resource Provider Configuration for more information.

The macros defined in a groupDefinition may be used as values in this field.

See Configuring Destinations and Naming Contexts for more information.

rpContextLocation

String

Provides information to the resource adapter describing how how to lookup the destination context that is used to locate the Queue or Topic in a WebLogic Server instance. Typically the form is: connector:connectorName/. connectorName must be defined in the resourceProviderDefinitions.

See Basic Resource Provider Configuration for more information.