Adapter Details
Resource Configuration Notes
The JMS Listener adapter can interact only with a messaging system that supports the JMS (Java Message Service) open standard, version 1.1 or later.
The adapter interacts with the source JMS messaging system topic or queue through standard JNDI lookups of a specified connection factory and destination. Therefore, the messaging system administrator must ensure that the connection factory and destination have been previously created and are available through standard JNDI lookups.
Waveset Installation Notes
The JMS Listener resource adapter works only in an application server environment that supports the following:
-
Client API for JMS, version 1.1 or later
-
JNDI (Java Naming and Directory Interface) API 1.1 or later
The application server administrator must ensure that the Waveset web application can successfully bind through JNDI to the JMS connection factory and destination objects appropriate for the source JMS messaging system.
Usage Notes
This section provides information related to using the JMS Listener resource adapter, which is organized into the following sections:
Connections
When Active Sync processing begins, a connection to the source messaging system is first made using the connection factory specified with the JNDI name of Connection factory resource parameter field. If specified, the User and Password fields are used for authentication when establishing the connection. If the fields are not specified, the connection are established using the default authentication.
The JMS Listener adapter operates in synchronous mode. It establishes a synchronous message consumer on the queue or topic destination specified by the JNDI name of Destination field. During each poll interval, the adapter will receive and process all available messages. Messages can be (optionally) additionally qualified by defining a valid JMS message selector string for the Message Selector field.
The connection factory and destination attributes must specify objects that correspond to the specified destination type. If a destination type of Durable Topic is specified, the additional fields of Durable Topic ClientID and Durable Topic Subscription Label are used to configure the durable subscription.
Message Mapping
When the adapter processes a qualified message, the received JMS message is first converted to a map of named values using the mechanism specified by the Message Mapping field. Refer to this resulting map as the message value map.
The message value map is then translated to the Active Sync map using the account attributes schema map. If the adapter has account attributes specified, the adapter searches the message value map for key names that also appear as a resource user attribute in the schema map. If present, the value is copied to the Active Sync map, but the entry name in the Active Sync map is translated to the name specified in the Identity system user attribute column in the schema map.
If the message value map has an entry that cannot be translated using the account attributes schema map, then the entry from the message value map is copied unaltered to the Active Sync map.
Guaranteed Delivery/Reliable Processing
The responsibility of guaranteed delivery lies with the sender of the message. Only messages sent persistently will be stored until delivered by the messaging system. This guarantees that the message will not be lost due to a crash or shutdown of the messaging system. This is referred to as once-and-only-once delivery.
The Reliable Messaging Support field indicates the form of reliable message processing the adapter should perform.
-
If set to LOCAL, then the JMS session for the adapter is transacted. The session is always committed after the message is processed, regardless of any errors encountered during the processing stages. This ensures that the message is processed only once.
-
If set to AUTO, then the session is not transacted, but the message is automatically acknowledged immediately according to the JMS definition of AUTO_ACK.
-
If set to DUPS_OK, then the session is not transacted, but the message is automatically acknowledged immediately according to the JMS definition of DUPS_OK_ACK.
-
If set to CLIENT, then the session is not transacted, and the message is not acknowledged by the adapter. Instead, it is expected that a lifecycle listener specified by the Message LifeCycle Listener field acknowledges the message as needed. The lifecycle listener is called with an AWAITING_CLIENT_ACK lifecycle event at the typical point that an acknowledgement is expected. It is rare that this mode is needed.
LifeCycle Listener
An optional lifecycle listener class can be registered with the adapter with the Message LifeCycle Listener field. The lifecycle listener can be used to perform:
-
Custom logging of the processing stages of the adapter
-
Custom manipulation of data during processing stages of the adapter
-
Custom acknowledgement of messages received with CLIENT_ACK mode
Reconnections
If connection is lost to the messaging system (for example, the messaging system server has been shut down), the adapter can be configured to periodically attempt to reconnect with the messaging system to re-establish the listener.
The Re-initialize upon exception check box enables reconnect behavior. You can set the frequency to attempt reconnect with the Connection Retry Frequency (secs) field.
JMX Monitoring
The JMS Listener adapter provides multiple attributes and operations that can be monitored with Java Management Extensions (JMX). For detailed information about configuring JMX on an Waveset server, refer to the Configuration chapter in Business Administrator's Guide.
On the server running the Active Sync process, (which also contains the authoritative mbean), statistics are computed based on a specified window of time. The setWindowMillis operation sets the duration of the window. Each time the statistics are computed, the actual duration of the statistics window is recorded as the ActualWindowTime attribute.
For example, the setWindowMillis operation could be set to 10000 (10 seconds), but the ActualWindowTime could contain a value of 10005, indicating the actual window was 10.005 seconds. Other attributes, such as MsgCountInWindow, use the actual window to measure or count statistics. If MsgCountInWindow contained a value of 63, then 63 messages were retrieved from JMS in 10.005 seconds.
The following tables list the attributes and operations the adapter makes available to JMX. The attributes and operations can be viewed from the JMX console under IDM/Cluster/ Synchronization/Active Sync/JMS Listener/SyncStats:DestinationName. The value for DestinationName is generated by concatenating the values of the Destination Type and JNDI name of Destination resource parameters.
JMX Attributes
|
Attribute |
Description |
|---|---|
|
ActualWindowTime |
Indicates the actual time, in milliseconds, of the most recent window. |
|
Attributes |
Lists the values for the adapter’s resource parameters. |
|
Authoritative |
Indicates whether the server is the one running the Active Sync process. |
|
AvgMsgWaitTime |
Indicates the average time, in milliseconds, spent waiting for messages. |
|
AvgProcessTime |
Indicates the average time, in milliseconds, spent processing messages. |
|
CurrentMsgWaitStart |
Indicates the date and time when the wait for the current message wait started, or null if no wait is pending. |
|
CurrentMsgWaitTime |
Indicates the number of milliseconds spent waiting for a message. |
|
CurrentPollStart |
Indicates the date and time when Active Sync last started, if Active Sync is currently running. |
|
CurrentProcessStart |
Indicates the date and time when processing started for the message currently being processed. |
|
CurrentProcessTime |
Indicates the total number of milliseconds spent processing the current message. A value of 0 indicates no message is being processed. |
|
LastCalculatedPollTime |
Indicates the total number of milliseconds in the poll loop, including current poll, as of the last time it was calculated. |
|
MaxMsgWaitTime |
Indicates the maximum number of milliseconds spent waiting for a single message. |
|
MaxPollTime |
Indicates the maximum milliseconds for one poll cycle. |
|
MaxProcessTime |
Indicates the maximum number of milliseconds spent processing a single message. |
|
MsgCountInWindow |
Indicates the number of messages recieved durring the last window of time. |
|
MsgPerUnittime |
Indicates the number of messages processed during the specified window. |
|
PollMsgWaitPercent |
Indicates the percentage of time spent waiting for messages. |
|
PollOtherPercent |
Indicates the percentage of time spent as overhead. |
|
PollProcessPercent |
Indicates the percentage of time spent processing messages. |
|
PollStatistics |
Indicates the actual time of the most recent window. |
|
TotMsgCount |
Indicates the total number of messages received. |
|
TotMsgWaitTime |
Indicates the total number of milliseconds spent waiting for messages. |
|
TotProcessTime |
Indicates the total milliseconds spent processing messages. |
JMX Operations
|
Operation |
Description |
|---|---|
|
getWindowMillis |
Gets the duration of the statistics window, in milliseconds. This operation is available only if the authoritative attribute is true. |
|
refreshAttributes |
Returns the latest values of the resource attributes. |
|
resetStatistics |
Resets the statistics of the adapter. This operation is available only if the authoritative attribute is true. |
|
setWindowMillis |
Sets the duration, in milliseconds, of the statistics window. This operation is available only if the authoritative attribute is true. |
Security Notes
This section provides information about supported connections and privilege requirements.
Supported Connections
Many messaging systems support the capability to encrypt messages between clients and brokers. The configuration is specific to each messaging system. However, typically the encryption is abstracted so that the choice of a specially configured connection factory is sufficient to enable encryption between the JMS Listener adapter and the messaging system broker.
Required Administrative Privileges
The user and password configured for the JMS Listener adapter must be an authenticated user in the JMS messaging system, and that user must be granted sufficient privilege to read messages from the JMS destination.
The messaging system administrator should protect the JMS connection by disabling default authentication. For further protection, the messaging system administrator should configure the authorization (access control) to optimize security.
Provisioning Notes
The following table summarizes the provisioning capabilities of the JmsListener adapter.
|
Feature |
Supported? |
|---|---|
|
Create account |
No |
|
Update account |
No |
|
Delete account |
No |
|
Enable/disable account |
No |
|
Rename account |
No |
|
Pass-through authentication |
No |
|
Before/after actions |
No |
|
Data loading methods |
None |
Account Attributes
The JMS Listener adapter does not provide default account attributes because the account attributes vary greatly, depending on the semantics of the messages read from the topic or queue.
You must define an account attribute in which the Identity System user attribute is named accountId.
Resource Object Management
Not supported.
Identity Template
None. You must supply the identity template with a valid value.
Sample Forms
JmsListenerActiveSync.xml
Troubleshooting
Use the Waveset debug pages to set trace options on the following class:
com.waveset.adapter.JmsListenerResourceAdapter
You may also set the following Active Sync logging parameters for the resource instance:
-
Maximum Log Archives
-
Maximum Active Log Age
-
Maximum Log File Size
-
Log File Path
-
Log Level
The Test Configuration button in the resource wizard when creating or editing a resource of type JMS Listener does an extensive check. It is valuable to troubleshoot configuration issues.
Additionally, a simple tool to send or publish messages to a queue or topic is available in a report called Send JMS Message. To use the report, first import the exchange file $WSHOME/sample/SendJMSMessageReport.xml. You can then create instances of the Send JMS Message report. When an instance of this report is run, it writes the specified message to the specified queue or topic.
- © 2010, Oracle Corporation and/or its affiliates