JMSQ

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

Server/Software	JAR Files
WebLogic Server	weblogic.jar
TIBCO Enterprise for JMSQ software	tibjms.jar tibjmsnaming.jar jms.jar tibjmsadmin.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)	Resource that contains information about the JMS Server.
JNDI Factory	Name of the JNDI factory, in the form JNDI context.INITIAL_CONTEXT_FACTORY; provided by the JNDI service provider.
JNDI URL	Bootstrap path to the JNDI server for the initial context handle to use JNDI, in the form JNDI Context.PROVIDER_URL.
Form of Input	TOPIC Is for a TopicSession in the Publish and Subscribe domain. QUEUE Is for a QueueSession in the PTP domain.
Form of Acknowledgment	Acknowledgement mode support. The session acknowledgement mode is either transactional (to send and receive a series of messages and then explicitly commit or rollback the group) or is in one of the available acknowledgement modes. Client Provides: An explicit acknowledge on a message acknowledges the receipt of all messages produced and consumed by the session that gives the acknowledgement. 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. Transactional Auto Acknowledge: The session automatically acknowledges the client's receipt of a message: By successfully returning from a call to receive (synchronousmode) or When the session message listener successfully returns (asynchronousmode). 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)	Name of the queue on which input documents will be received for processing by Service Manager.
Set Reply Correlation Id	Entered value is used as the correlation ID of the response.
Default Reply	Default queue or topic to which response document will be written.
Default Output Form	Select a topic or queue target.
Pending Queue	Name of the queue where Service Manager keeps failed requests that are retried.
User	Valid user ID defined to the JMS Server.
Password	Valid password defined to the JMS Server.
Duration	Maximum time, in milliseconds, that a document can remain in the retry pending queue.
Retry	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	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, or text).
JMSReplyTo	Queue or topic (used for JNDI lookup).
Get Correlld As Bytes	Accounts for binary in correlation IDs.
Accepts non-XML (flat) only	Select true if 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	Maximum time a request can take to complete. A request that takes longer to complete terminates. Prevents runaway requests.
Polling Interval	Interval (in seconds) at which listener checks for new input. The listener is constantly connected to the queue to retrieve incoming messages. 2.0 is the default value.
Default Java File Encoding	Default encoding if 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 true, the default reply definition is used in addition to defined destinations.
Error Documents treated normally	If true, error documents are processed by configured preemitters.
Listener is Transaction Manager	If true, agents run in a local transaction. Agents can roll back uncompleted transactions.
Record in Activity Log(s)	If set, activity on this channel will be recorded in the activity logs, else the activity will not be recorded.

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

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.

Top of page

JMS Emitter Properties

The following table lists and describes the JMS emitter properties. 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.
JNDI URL	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	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	Valid user ID defined to the JMS Server.
Password	Valid password defined to the JMS Server.
Output Message Type	Select Bytes, Text, or Dynamic.
JMSReplyTo	Queue or Topic (used for JNDI lookup).

JMS Emitter Configuration Example

You want to 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 the iWay Adapter for JMS to Connect to Open JMS Server

This section describes how to configure a JMSQ listener for the iWay Adapter for JMS. JMSQ architecture is closely allied with Web servers and JNDI (Java Naming and Directory Interface), used to locate the drivers. Therefore, you must register the JMSQ specific JAR files supplied by the JMSQ vendor for the JMSQ listener.

For iWay, register the libraries in the following directory in the Path Settings PreClassPath section:
```
C:\program files\openjms\lib
```
To register JMSQ JAR files for Open JMS server, specify the full path to where the file is located; for example:
```
C:\program files\openjms\lib\openjms-0.7.6.jar
```

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

Note: OpenJMS is an open source software implementing Sun Microsystems's Java Message Service API 1.1 Specification. For more information please see http://openjms.sourceforge.net/

Top of page

JMSQ Listener Properties for Open JMS Server

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

Property Name

Property Description

Connection (required)

Contains the JMSQ connection factory name. Type JmsQueueConnectionFactory.

JNDI Factory

Java Naming Directory Interface (JNDI) name. The JNDI factory for the iWay Server for JMSQ is:

org.exolab.jms.jndi.mipc.lpcJndiInitialContextFactory

JNDI URL

URL to reach the JNDI Server.

Form of Input

TOPIC

Is for a TopicSession in the Publish and Subscribe domain.

QUEUE

Is for a QueueSession in the PTP domain.

Form of Acknowledgment

How listener acknowledges received messages:

auto acknowledge

client provides

duplicates permitted

transactional

External Transaction Rollback

Use external rollback facilities to manage transactions.

Receiver Name (required)

Name of the queue on which input documents will be received for processing by Service Manager.

Set Reply Correlation Id

If set to a value, used as the correlation ID of the response.

Default Reply

Default queue or topic to which response document will be written.

Default Output Form

Select a topic or queue target.

Pending Queue

Holds documents pending retry.

User

User ID defined to the JMS Server.

Password

Valid password defined to the JMS Server.

Duration

Maximum time that a document can remain in the retry pending queue.

Retry

Interval between retrying pending requests.

Message Selector

If used, input is filtered by this selector.

Message Priority

Outgoing message priority (if omitted, uses incoming priority).

Output Message Type

Select Bytes, Text, or Dynamic.

JMSReplyTo

Queue or topic (used for JNDI lookup).

Get Correlld As Bytes

Accounts for binary in correlation IDs.

Accepts non-XML (flat) only

Select true if non-XML input is expected. If enabled, XML input still can be passed to the listener. Preparsers do not run.

Optimize Favoring

Option for optimizing listener performance. For smaller transactions, select performance. For large payloads that could monopolize the amount of memory used by Service Manager, select memory.

Multithreading

Indicates number of worker threads (documents or requests) that Service Manager can handle in parallel. Setting it greater than 1 enables the listener to handle a second request while an earlier request is still being processed.

Default: 1 Max value: 99

Execution Time Limit

Maximum time a request can take to complete. A request that takes longer to complete terminates. Prevents runaway requests.

Polling Interval

Interval (in seconds) at which to check for new input or stop listener requests. 2.0 it the default value.

Default Java File Encoding

Default encoding if incoming message is not self-declaring (that is, XML).

Agent Precedence

Sets the order by which Service Manager selects agents. Service Manager usually 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 true, the default reply definition is used in addition to defined destinations.

Error Documents treated normally

If true, error documents are processed by configured preemitters.

Listener is Transaction Manager

If true, agents run in a local transaction. Agents can roll back uncompleted transactions.

Initialization Agent

Name (parameters) of the processing module called at listener start up.

Property Name	Property Description
Connection (required)	Contains the JMSQ connection factory name. Type JmsQueueConnectionFactory.
JNDI Factory	Java Naming Directory Interface (JNDI) name. The JNDI factory for the iWay Server for JMSQ is: org.exolab.jms.jndi.mipc.lpcJndiInitialContextFactory
JNDI URL	URL to reach the JNDI Server.
Form of Input	TOPIC Is for a TopicSession in the Publish and Subscribe domain. QUEUE Is for a QueueSession in the PTP domain.
Form of Acknowledgment	How listener acknowledges received messages: auto acknowledge client provides duplicates permitted transactional
External Transaction Rollback	Use external rollback facilities to manage transactions.
Receiver Name (required)	Name of the queue on which input documents will be received for processing by Service Manager.
Set Reply Correlation Id	If set to a value, used as the correlation ID of the response.
Default Reply	Default queue or topic to which response document will be written.
Default Output Form	Select a topic or queue target.
Pending Queue	Holds documents pending retry.
User	User ID defined to the JMS Server.
Password	Valid password defined to the JMS Server.
Duration	Maximum time that a document can remain in the retry pending queue.
Retry	Interval between retrying pending requests.
Message Selector	If used, input is filtered by this selector.
Message Priority	Outgoing message priority (if omitted, uses incoming priority).
Output Message Type	Select Bytes, Text, or Dynamic.
JMSReplyTo	Queue or topic (used for JNDI lookup).
Get Correlld As Bytes	Accounts for binary in correlation IDs.
Accepts non-XML (flat) only	Select true if non-XML input is expected. If enabled, XML input still can be passed to the listener. Preparsers do not run.
Optimize Favoring	Option for optimizing listener performance. For smaller transactions, select performance. For large payloads that could monopolize the amount of memory used by Service Manager, select memory.
Multithreading	Indicates number of worker threads (documents or requests) that Service Manager can handle in parallel. Setting it greater than 1 enables the listener to handle a second request while an earlier request is still being processed. Default: 1 Max value: 99
Execution Time Limit	Maximum time a request can take to complete. A request that takes longer to complete terminates. Prevents runaway requests.
Polling Interval	Interval (in seconds) at which to check for new input or stop listener requests. 2.0 it the default value.
Default Java File Encoding	Default encoding if incoming message is not self-declaring (that is, XML).
Agent Precedence	Sets the order by which Service Manager selects agents. Service Manager usually 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 true, the default reply definition is used in addition to defined destinations.
Error Documents treated normally	If true, error documents are processed by configured preemitters.
Listener is Transaction Manager	If true, agents run in a local transaction. Agents can roll back uncompleted transactions.
Initialization Agent	Name (parameters) of the processing module called at listener start up.

Configuring a JMS Emitter 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.

Top of page

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	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	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, used as the correlation ID of the response.
Message Priority	Outgoing message priority (if omitted, uses incoming priority).
User	User ID at broker machine.
Password	Password associated with user ID.
Output Message Type	Bytes, dynamic, or text.
JMSReplyTo	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]

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.