|
AcknowledgeMode
|
How listener threads, which consume messages and call a message-driven bean's message listener method (for example, the onMessage method for a JMS message listener), acknowledge the delivery of a message.
The following are valid values:
-
Auto-acknowledge (default): the listener thread sends an acknowledgment as soon as a message is received by the MDB.
-
Dups-ok-acknowledge: the listener thread sends an acknowledgment lazily; this can improve performance. It is possible for the MDB to receive duplicates of the message until the acknowledgment is actually sent. If you select this option, your MDB must be able to handle duplicate messages.
|
|
ClientId
|
The String name that a listener thread will set on connections it acquires on behalf of its message-driven bean.
The default is no name.
|
|
EndpointFailureRetryInterval
|
The number of milliseconds that OC4J will wait before attempting to start a new listener thread and reconnect with the JMS provider after any failure that causes the number of listener threads to drop to zero.
Listener threads are automatically terminated on JMS provider failure: for example, if a listener thread calling MessageConsumer method receive results in an exception. If all listener threads terminate while the endpoint is still running (for example, due to a sustained network failure or if the JMS server is not up), the MDB cannot receive messages. In this situation, the Oracle JMS Connector attempts to start a new listener thread and reconnect with the JMS provider every EndpointFailureRetryInterval milliseconds until it is either successful or the endpoint is shut down. Once a listener thread is successfully created, normal listener thread management resumes (see ReceiverThreads, ListenerThreadMaxIdleDuration, and ListenerThreadMinBusyDuration).
Consider the following consequences of connection failure recovery:
-
message ordering: since recovery from a connection failure requires the creation of a new JMS session, and JMS message ordering guarantees only apply to messages received within a single session, messages received after the reconnect may not be ordered with respect to messages received before the reconnect;
-
lost messages: if the endpoint is a nondurable subscriber, messages may be lost or duplicated. This problem will not happen when using queues or when using topics with durable subscribers.
Whether or not you experience these problems may be subject to the specific behavior of your JMS provider
The default is 60000 milliseconds.
|
|
ExceptionQueueName
|
The JNDI name of the of the javax.jms.Queue object to use as the exception queue.
This property is required when UseExceptionQueue is true, and ignored when false.
|
|
IncludeBodiesInExceptionQueue
|
Determines whether or not messages sent to the exception queue will include a message body.The following are valid values:
-
true (default): OC4J includes the message body in messages sent to the exception queue;
-
false: OC4J does not include the message body in messages sent to the exception queue. If many messages are sent to the exception queue during normal operation and the message body is of no use in the exception queue, then this property may be set false to improve performance.
This property does not apply:
-
If UseExceptionQueue is false.
-
If the original message did not have a message body, then the message sent to the exception queue will not have one either.
-
If a copy of the original message cannot 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.
|
|
ListenerThreadMaxIdleDuration
|
The number of milliseconds that OC4J will keep a listener thread that is not receiving any messages. At least one listener thread will remain as long as the endpoint is active.
The default is 300000 milliseconds.
|
|
ListenerThreadMaxPollInterval
|
The upper limit (in milliseconds) on the polling interval of the Oracle JMS Connector adaptive polling interval algorithm.
The Oracle JMS Connector uses an adaptive algorithm to determine the actual polling interval: during periods of activity, it uses shorter polling intervals (higher polling rates) and during periods of inactivity, it uses longer polling intervals (lower polling rates) that will not exceed this property.
Listener threads poll to see if there is a message waiting to be processed. The more frequently this polling is performed, the faster (on average) a given listener thread can respond to a new message. The price for frequent polling is overhead–the resource provider must process a receive request each time it is polled.
The default is 5000 milliseconds.
|
|
ListenerThreadMinBusyDuration
|
If a listener thread has just received a message, has not been idle (had to wait for a new message to arrive) at any point during the past ListenerThreadMinBusyDuration milliseconds, and the current number of listener threads for this endpoint is less than ReceiverThreads, then OC4J will create an additional listener thread if possible.
The default is 10000 milliseconds.
|
|
LoggerName
|
The logger name for Oracle JMS Connector log messages. The LoggerName property is required when setting the LogLevel property.
|
|
LogLevel
|
Determines the level of detail of Oracle JMS Connector log messages. Although primarily intended for debugging the Oracle JMS Connector itself, these messages may also be useful when debugging issues related to its use. Oracle recommends that you set this property temporarily for debugging purposes; this property should not be set in production code. Note that specific log messages and log levels may be added, removed, or modified in future versions of the Oracle JMS Connector. The LoggerName property is required when setting the LogLevel property.
The following are valid values:
-
ConnectionPool: log connection pool related messages only.
-
ConnectionOps: log connection related messages only.
-
TransactionalOps: log transaction related messages only.
-
ListenerThreads: log listener thread related messages only.
-
INFO: logs the login/logout for each server session, including the user name. After acquiring the session, detailed information is logged.
-
CONFIG: logs only login, JDBC connection, and database information.
-
FINE: logs some internal information.
-
FINER: similar to warning. Includes stack trace.
-
FINEST: includes additional low level information.
-
SEVERE: logs exceptions indicating TopLink cannot continue, as well as any exceptions generated during login. This includes a stack trace.
-
WARNING: logs exceptions that do not force TopLink to stop, including all exceptions not logged with severe level. This does not include a stack trace.
-
OFF: disables logging.
|
|
MaxDeliveryCnt
|
The maximum number of times a listener thread will attempt to deliver a message to a message-driven bean. A value of 0 means never discard a message.
If a message has the JMSXDeliveryCount property, whose value is greater than MaxDeliveryCnt, then the message will be discarded: that is, the listener thread will not call the message-driven bean's message listener method (for example, the onMessage method for a JMS message listener).
If the exception queue is enabled (see UseExceptionQueue), a copy of the message will be sent to the exception queue.
Use a value of 0 with caution. If MaxDeliveryCnt is set to 0 to prevent a message from ever being discarded, and a message-driven bean always responds to a given message by throwing an exception, then the message-driven bean may endlessly fail to process the same message as it is redelivered over and over again.
The default value is 5.
|
|
MessageSelector
|
The String selector expression of message properties that match the type of message your MDB should receive. Messages that do not match the expression are filtered (not delivered to the MDB).
This is used as the messageSelector for the JMS sessions created for the listener threads.
The default is no filtering.
|
|
ReceiverThreads
|
The maximum number of listener threads to create for this endpoint.
For queues, using more than one thread may help increase the rate at which messages can be consumed.
For topics this value must always be 1.
Each listener thread gets its own session and topic subscriber. For durable subscribers, it would be an error to have more than one subscriber with the same subscription name. For nondurable, subscribers having more than one thread will not help because more threads translates into more subscribers which translates into more copies of each message.
See also ListenerThreadMinBusyDuration.
The default is 1.
|
|
ResPassword
|
The String password that OC4J passes to the resource provider. The ResPassword property supports standard password indirection options (for example, you can use ->joeuser to represent the password of joeuser).
When set, OC4J passes this value to the create*Connection method as the password argument.
When only one of ResUser or ResPassword is set, OC4J passes null for the unset property.
When neither ResUser nor ResPassword are set, connections used for this MDB's inbound message handling and exception queue handling (see UseExceptionQueue) are created using the no-argument version of the create*Connection method.
The default is null.
|
|
ResUser
|
The String user name that OC4J passes to the resource provider.
When set, OC4J passes this value to the create*Connection method as the user argument.
When only one of ResUser or ResPassword is set, OC4J passes null for the unset property.
When neither ResUser nor ResPassword are set, connections used for this MDB's inbound message handling and exception queue handling (see UseExceptionQueue) are created using the no-argument version of the create*Connection method.
The default is null.
|
|
SubscriptionDurability
|
Determines the durability of the topic consumer used by a listener thread. This is applicable only for topics (do not set this property for queues).
The following are valid values:
-
Durable: messages are not missed even if the OC4J is not running. Reliable applications will typically make use of durable topic subscriptions rather than non-durable topic subscriptions. When this property is set to Durable (and DestinationType is javax.jms.Topic or javax.jms.Destination), the SubscriptionName property is required.
-
NonDurable (default): OC4J ensures that a message-drive bean is available to service a message as long as OC4J is running. Messages may be missed if OC4J is not running for any period of time.
|
|
SubscriptionName
|
The String name that a listener thread uses when it creates a durable subscriber. In a given JMS server, you should assign a given subscription name to at most one MDB (which must have at most one listener thread).
This property is required when SubscriptionDurability is Durable (and DestinationType is javax.jms.Topic or javax.jms.Destination). In all other cases, this property is ignored.
|
|
TransactionTimeout
|
The upper limit (in milliseconds) that the Oracle JMS Connector will wait for a message to arrive before exiting the current transaction.
The OC4J transaction manager limits the amount of time a transaction can last (see transaction-timeout in transaction-manager.xml). Set this property so that the transaction manager will not timeout the transaction during a call to a message-driven bean's message listener method (for example, the onMessage method for a JMS message listener) unless something is wrong. For example, If the transaction manager timeout is set to 30 seconds, and the onMessage routine will never take more than 10 seconds unless something is wrong, then you could set TransactionTimeout to 20 seconds (20000 milliseconds).
The default is 300000 milliseconds.
|
|
UseExceptionQueue
|
Determines how OC4J handles messages that it cannot deliver because the message-driven bean's message listener method (for example, the onMessage method for a JMS message listener) throws an exception or the listener thread exceeds the MaxDeliveryCnt threshold.
The following are valid values:
-
true: OC4J sends undeliverable messages to the exception queue as described later.
In this case, the ExceptionQueueName property is required.
-
false (default): OC4J discards undeliverable messages.
The default is false.
When UseExceptionQueue is set to true, OC4J sends undeliverable messages to the exception queue as follows:
-
Create a new message of the same type.
-
Copy the properties and body from the original message to the new message.
-
Translate headers in the original to properties in the copy, assigning each header obtained through getJMS{Header} to property GJRA_CopyOfJMS{Header}. Since javax.jms.Destination is not a valid property type, translate destination headers into descriptive messages.
This service is not provided for JMSX* properties, most notably the JMSXDeliveryCount property.
OC4J translates headers this way because if the headers were copied, sending the message to the exception queue would cause most of them to be lost (over-written by the resource-provider).
-
Add a string property called GJRA_DeliveryFailureReason which indicates why the message was not delivered.
-
If the message-driven bean's message listener method generated an exception immediately prior to the delivery failure, add a string property called GJRA_onMessageExceptions which contains exception information.
-
Validate the new message:
If the copy and augmentation process is successful, add a boolean property called GJRA_CopySuccessful with the value true.
If some part of the copy or augmentation process fails, OC4J does not stop. It attempts to complete the rest of the procedure. For Bytes, Map, and Stream message types, this can mean that part of the body is copied and the rest is not. In this case, add a boolean property called GJRA_CopySuccessful with the value false.
-
Use the connection factory specified by the ConnectionFactoryJndiName property to send the resulting message to the exception queue.
Only one attempt is made to send the message to the exception queue. Should this attempt fail, the message will be discarded without being placed in the exception queue.
Because OC4J uses the connection factory specified by the ConnectionFactoryJndiName property to send the message to the exception queue (in addition to being used for the primary destination), if the primary destination (specified by the DestinationName property) is a topic, then the connection factory must support both queues and topics (that is, the connection factory must be either javax.jms.ConnectionFactory or javax.jms.XAConnectionFactory).
For potential variations of the previous procedure, see IncludeBodiesInExceptionQueue.
|
