iWay Service Manager > Queuing Protocol Adapters > JMSQ

JMSQ

Topics:

Registering JMS JAR Files
JMSQ Listener Configuration Example
Configuring a JMS Emitter
JMS Emitter Configuration Example
Configuring a JMS Emitter for Server for JMS
JMSQ Troubleshooting

Reference:

JMSQ Listener Properties
JMSQ Listener Special Registers

Enterprise messaging is recognized as an essential tool for building enterprise applications and e-commerce systems. Java Message Service Queue (JMSQ) provides a common way for Java programs to create, send, receive, and read enterprise messaging system messages. The JMSQ application programming interface (API) is a Java technology API for inter-client communication among distributed applications.

JMSQ provides a common interface that wraps around the underlying message delivery system. The delivery system can be provided by any number of vendors. JMSQ is a service-oriented API specification, that is, the JMSQ API prescribes messaging functionality in terms of interfaces, which JMSQ vendors then implement. Therefore, programmers work with JMSQ through these interfaces.

JMSQ is a set of interfaces and associated semantics that define how a JMSQ client accesses the facilities of an enterprise-messaging product. Rather than communicate directly with each other, the components in an application, based around a message service, send messages to a message server. The message server, in turn, delivers the messages to the specified recipients.

iWay Service Manager can read messages arriving on a JMS queue and route the response to either another queue or to a non-JMSQ destination. Similarly, Service Manager can direct messages received through its listeners to a JMS queue. During the message flow, Service Manager can apply the standard document analysis, validation, transformation, and business logic capabilities to the document.

The iWay Adapter for JMS is a generic listener/emitter that provides an interface to various message-oriented middleware products that adopted the JMSQ standard. Each product must supply the required interface libraries that must be registered in the Service Manager configuration. Therefore, the properties listed differ depending on the JMSQ vendor, and you must add the required JMS JAR files for each to the class path.

Registering JMS JAR Files

JMSQ architecture is closely allied with a web server and JNDI (Java Naming Directory Interface), which locates the drivers. Therefore, the JMSQ listener requires that you register the specific JAR files supplied by the JMSQ vendor.

The JMSQ listener requires that you register:

Server/Software	JAR Files
WebLogic Server	weblogic.jar
TIBCO Enterprise for JMSQ software	tibjms.jar tibjmsnaming.jar jms.jar tibjmsadmin.jar
OpenJMS	concurrent-1.3.4.jar openjms-0.7.7-beta-1.jar openjms-common-0.7.7-beta-1.jar openjms-net-0.7.7-beta-1.jar spice-jndikit-1.2.jar

For instructions on registering JAR files, see Registering Library Files and Setting JVM Options.

Reference: JMSQ Listener Properties

The following table lists and describes the JMSQ listener properties. For instructions on creating a listener, see How to Create a Listener.

Property Name	Property Description
Connection (required)	The resource that contains information about the JMS Server.
JNDI Factory	The name of the JNDI factory. Provided by the JNDI service provider.
JNDI URL	The path to the JNDI server for the initial JNDI context handle to use.
Form of Input	The form of input. TOPIC: Used for a TopicSession in the Publish and Subscribe domain. QUEUE:U sed for a QueueSession in the PTP domain.
Form of Acknowledgment	The acknowledgment mode support. The session acknowledgment mode is either transactional (to send and receive a series of messages and then explicitly commit or rollback the group) or one of the following acknowledgment modes. Client Provides: An explicit acknowledge on a message acknowledges the receipt of all messages produced and consumed by the session that gives the acknowledgment. When a session is forced to recover, it restarts with its first unacknowledged message. Duplicates Permitted: The session lazily acknowledges the delivery of messages to consumers, possibly allowing duplicate messages after a system outage. Auto Acknowledge: The session automatically acknowledges the client receipt of a message. By successfully returning from a call to receive (synchronous mode) or when the session message listener successfully returns (asynchronous mode), the last message can be delivered again.
External Transaction Rollback	Use external rollback facilities to manage transactions, for example, the BEA WebLogic pending facilities.
Receiver Name (required)	The name of the queue on which input documents will be received for processing by Service Manager.
Set Reply Correlation Id	The entered value is used as the correlation ID of the response.
Default Reply	The default queue or topic to which the response document will be written.
Default Output Form	You can select a topic or queue target.
Pending Queue	The name of the queue where Service Manager keeps failed requests that are retried.
User	A valid user ID defined to the JMS Server.
Password	A valid password defined to the JMS Server.
Duration	The maximum time, in milliseconds, that a document can remain in the retry pending queue.
Retry	The interval between retrying pending requests contained in a message.
Message Selector	In PTP domains, message selection occurs on the server. However, in Pub/Sub domains, by default, messages for a subscribed topic are delivered to the subscriber, and then, the filter is applied to determine what is consumed. Message selectors can consist of: Literals and indefinites Operators and expressions Comparison tests Parentheses White space
Message Priority	A priority is suggested to the JMSQ provider and can only order the delivery of undelivered messages. JMSQ defines ten levels of message priority with values 0 through 9, where 0 is the lowest and 9 is the highest. Zero through four are considered normal settings, and five through nine, expedited. The Message Priority field is the default priority value set in the JMSQ header.
Output Message Type	Defines the type of the output message (bytes, dynamic, text, map, object, or stream).
JMSReplyTo	The queue or topic (used for JNDI lookup).
Get Correlld As Bytes	Accounts for binary in correlation IDs.
Request Header Namespace	The special register namespace into which protocol headers from the incoming request will be saved.
Response Header Namespace	The special register namespace from which protocol headers for the outbound response will be taken.
Whitespace Normalization	Specifies how the parser treats whitespace in Element content. Select preserve to turn off all normalization as prescribed by the XML Specification. Select condense to remove extra whitespace in pretty printed documents and for compatibility with earlier versions.
Accepts non-XML (flat) only	If set to true, then non-XML input is expected. If enabled, XML input still can be passed to the listener. Preparsers do not run.
Optimize Favoring	Use this option to customize how the listener performs. For smaller transactions, select performance. For large payloads that could monopolize the amount of memory used by Service Manager, select memory.
Multithreading	Indicates the number of worker threads. (Equivalent to the number of requests that Service Manager can handle in parallel.) Setting this to greater than 1 enables the listener to handle a second request while an earlier request is still being processed. The total throughput of a system can depend on the number of threads operating. Default: 1 Max value: 99
Execution Time Limit	The maximum time a request can take to complete. A request that takes longer to complete terminates. Prevents runaway requests.
Polling Interval	The interval (in seconds) at which the listener checks for new input. The listener is constantly connected to the queue to retrieve incoming messages. The default value is 2.0.
Default Java File Encoding	The default encoding if an incoming message is not self-declaring (that is, XML).
Agent Precedence	Sets the order by which Service Manager selects agents. Service Manager looks for a document entry in the configuration library and when a match is found, the agent specified in that document entry is selected. If no matching document entry is found or agent specified, the engine looks in the input protocol configuration (listener). To have the processing agent taken directly from the listener (thus ignoring the document entry), use <listener> overrides <document>. <document> overrides <listener> is the default value.
Always reply to listener default	If set to true, the default reply definition is used in addition to defined destinations.
Error Documents treated normally	If set to true, error documents are processed by configured preemitters.
Listener is Transaction Manager	If set to true, the agents run in a local transaction. Agents can roll back uncompleted transactions.
Record in Activity Log(s)	If set to true, activity on this channel will be recorded in the activity logs. If set to false, the activity will not be recorded.

Note: The JMSQ listener supports streaming. Streaming is used for large documents or documents for which the application needs to split the input into sections under the same transaction. For more information on streaming and configuring streaming preparsers, see the iWay Service Manager Component and Functional Language Reference Guide.

Reference: JMSQ Listener Special Registers

The following table lists and describes the special registers (SREGs) available on the JMSQ listener.

Name	Source	Level	Type	Description
correlid	Listener	Document	String	The correlation ID.
destination	Listener	Document	String	The default destination for reply (from message).
iwayconfig	Listener	System	String	The current active configuration name.
msgid	Listener	Document	String	The message ID.
msgsize	Listener	Document	Integer	The physical length of the message payload.
name	Listener	System	String	The assigned name of the master (listener).
priority	Listener	Document	String	The priority of this message.
protocol	Listener	System	String	The protocol on which this message was received.
source	Listener	Document	String	The queue or topic on which message was received.
tid	Listener	Document	String	Unique transaction ID.

JMSQ Listener Configuration Example

You are receiving documents on a JMS queue, named queue1, located at the following host: tcp://172.30.246.146:3035. You would like to configure a listener on this queue. Specify the values as follows:

Connection: ConnectionFactory
JNDI Factory: org.exolab.jms.jndi.InitialContextFactory
JNDI URL: tcp://172.30.246.146:3035/
Receiver Name: queue1
User logon ID/password: Supply the correct logon credentials.
Note: For more information on configuration parameters, see the OpenJMS documentation at http://openjms.sourceforge.net.

Configuring a JMS Emitter

Topics:

JMS Emitter Properties

Messages are sent to the destinations at the completion of a workflow. The state of the document determines which destination is used. The order in which the destinations are used cannot be predicted. Destinations cannot accept responses. These configurations also are used to send a message over a different protocol.

Note: Configuring a JMS emitter is not required if the emitter protocol used in the outlet of the channel is the same as the listener protocol used in the inlet of the channel. For more information on inlets and outlets, see Defining an Inlet and Defining an Outlet.

To route an output document or error message to a protocol other than that of the listener, you must configure an emitter. For example, an application may send input over TCP but want to route the output to a JMS queue.

JMS Emitter Properties

The following table lists and describes the JMS emitter properties. For instructions on creating an emitter, see How to Create an Emitter.

Property Name	Property Description
Destination (required)	Queue@connectionFactory. A connection factory is a resource that contains information about the JMS Server.
JNDI URL	The path to the JNDI Server to find the initial context handle to use JNDI.
JNDI Factory	InitialContext is a bound handle to a directory server, which looks up administered resources. The JNDI factory is specific to the implementation of the JNDI provider.
Form of Output	TOPIC Is for a TopicSession in the Publish and Subscribe domain. QUEUE Is for a QueueSession in the PTP domain.
Set Reply Correlation Id	If set to a value, this is used as the correlation ID of the response.
Message Priority	A priority is suggested to the JMSQ provider and can only order the delivery of undelivered messages. JMSQ defines ten levels of message priority with values 0 through 9, where 0 is the lowest and 9 is the highest. Zero through four are considered normal settings and five through nine, expedited. The Message Priority field is the default priority value set in the JMSQ header.
User	A valid user ID defined to the JMS Server.
Password	A valid password defined to the JMS Server.
Output Message Type	Select Bytes, Text, or Dynamic.
JMSReplyTo	The queue or Topic (used for JNDI lookup).
Request Header Namespace	The special register namespace from which protocol headers for the outbound request will be taken.

JMS Emitter Configuration Example

You want to route documents or error messages to a protocol other than a listener. You must configure an emitter to do this. Specify the values as follows:

Destination: queue@ConnectionFactory
JNDI Factory: org.exolab.jms.jndi.InitialContextFactory
JNDI URL: tcp://172.30.246.146:3035/
User logon ID/password: Supply the correct logon credentials.

Note: For more information on configuration parameters, see the OpenJMS documentation at http://openjms.sourceforge.net.

Configuring a JMS Emitter for Server for JMS

Topics:

JMS Emitter Properties for Server for JMS

To route an output document or error message to a protocol other than that of the listener, you must configure an emitter. For example, an application may send input over TCP, but want to route to a JMS queue.

Note: This procedure is not required if the emitter protocol used in the outlet of the channel is the same as the listener protocol used in the inlet of the channel. For more information on inlets and outlets, see Defining an Inlet and Defining an Outlet.

JMS Emitter Properties for Server for JMS

The following table lists and describes the JMS emitter properties for Server for JMS. For instructions on creating an emitter, see How to Create a Listener.

Property Name	Property Description
Destination (required)	Queue@connectionFactory. A connection factory is a resource that contains information about the JMS Server. If you attempt to emit a message to a queue name, TestQueue, the value in this field would be TestQueue@QueueConnectionFactory.
JNDI URL	This property is required to access the iWay Server for JMSQ. The iWay Server for JMSQ can listen on a variety of protocols. The default protocol is TCP. If connecting to the iWay Server for JMSQ through TCP, the JNDI URL is tcp://host:3035.
JNDI Factory	The InitialContext is a bound handle to a directory server, which looks up administered resources. The JNDI factory is specific to the implementation of the JNDI provider. The JNDI factory for the iWay Server for JMSQ is: org.exolab.jms.jndi.mipc.IpcJndiInitialContextFactory.
Form of Output	TOPIC Is for a TopicSession in the Publish and Subscribe domain. QUEUE Is for a QueueSession in the PTP domain.
Set Reply Correlation Id	If a value is set, that value is used as the correlation ID of the response.
Message Priority	The outgoing message priority (if omitted, uses incoming priority).
User	The user ID at broker machine.
Password	The password associated with user ID.
Output Message Type	Bytes, dynamic, or text.
JMSReplyTo	The queue or topic (used for JNDI lookup).

JMSQ Troubleshooting

The following table lists and describes errors that you may encounter when using a JMSQ listener.

Error	Reason	Solution
Could not start: XD[FAIL] Can't create JMSQ session.: [line 6]	The class path was not updated to include the required JAR files for the JNDI Server. Alternatively, although these libraries were included using this pane, the server was not stopped and started again to enable this library to be included in the configuration.	Use the Path Settings pane to register the appropriate JMSQ JAR files in the ClassPath section. The server must be stopped and restarted for this to take effect.
Cannot emit reply to .XDJMSQEmit <no dead letter path>: XD[FAIL} in emit{} error create queue.	The system was unable to find the queue(s) specified.	Either the queue was not defined, or it was spelled incorrectly. The JMSQ listener is case-sensitive. Verify that the queue name exists and is entered in the configuration pane in the correct case.

Error

Reason

Solution

Could not start: 
XD[FAIL] Can't create 
JMSQ session.: [line 6]

The class path was not updated to include the required JAR files for the JNDI Server.

Alternatively, although these libraries were included using this pane, the server was not stopped and started again to enable this library to be included in the configuration.

Use the Path Settings pane to register the appropriate JMSQ JAR files in the ClassPath section. The server must be stopped and restarted for this to take effect.

Cannot emit reply to 
.XDJMSQEmit <no dead 
letter path>:  XD[FAIL} 
in emit{} error create 
queue.

The system was unable to find the queue(s) specified.

Either the queue was not defined, or it was spelled incorrectly. The JMSQ listener is case-sensitive. Verify that the queue name exists and is entered in the configuration pane in the correct case.