JMS Adapter

The JMS Adapter is an out-of-process adapter. You can configure the JMS Adapter as either an input adapter or an output adapter. Both adapters work with JMS messages that have message body type "MapMessage" or "TextMessage".

This adapter attempts to establish a JMS (Java Messaging Service) session and does one of the following:

If the adapter is configured as an input adapter, it subscribes to the given topic and listens on that session. When the adapter receives a message from the JMS server, it sends the message as a tuple into the Sybase CEP Server (in other words, into a stream), framed by reset and commit tuples. Messages must be set up in such a way that fields in MapMessages correspond exactly to the stream's tuple descriptor.
If the adapter is configured as an output adapter, it takes data received from a Sybase CEP Server stream and publishes the data to the JMS topic. Messages sent out are JMS MapMessages. The order and type of fields in the JMS messages must exactly match order and type of fields in the Sybase CEP stream's tuple descriptor.

Note: In order to use the Sybase CEP Adapter for JMS to integrate or communicate with TIBCO Enterprise Message Services, you must have a valid license for TIBCO Enterprise Message Services from TIBCO or from an authorized TIBCO channel.

The JMS server should use the JMS 1.1 protocol.

This adapter can be configured to use Sybase CEP's Guaranteed Delivery when reading from or writing to a Sybase CEP stream. If GD is turned on, then the adapter provides At Least Once semantics for outbound MapMessage and TextMessage messages from Sybase CEP and Exactly Once semantics for inbound messages.

To run the JMS adapter, execute the following steps:

Make sure that you have a JMS server up and running.
Make sure that you have installed the JMS client.
Set the desired values in the jndi.properties file, and set your CLASSPATH to include the directory that holds the jndi.properties file. The CLASSPATH should include only the path, not the path plus the filename, of the jndi.properties file.
Set your CLASSPATH environment variable according to the instructions in Sybase CEP Java SDK. The instructions for setting CLASSPATH apply to all out-of-process Java adapters, whether provided by Sybase CEP or written by you.
Update your CLASSPATH to include the necessary JMS libraries.
Note: Sybase CEP does not supply the libraries for any JMS implementation.
Execute the following command:
```
java com/sybase/c8/adapter/JMSAdapter <parameters>
```
Each parameter is of the form

--<paramname>=<paramvalue>

note that "--" (two dashes) must precede each parameter name. For example:
```
java com/sybase/c8/adapter/JMSAdapter --topic=test1 --GD=true ...
```
Use the command-line parameters shown in the table below. These parameters are case-sensitive.

Parameter	Description	Required/Optional
kind={input \| output}	Indicates whether the adapter should run as an input adapter or an output adapter.	Required.
serverURL=<URL to server>	URL of Sybase CEP Server, for example `http://localhost:6789`. If your manager and containers are separate, this must be the URL of the manager.	Required.
queue=<queueName>	Name of the JMS queue, to be looked up in JNDI.	You must specify either a queue or a topic.
topic=<topicName>	Name of the JMS topic, to be looked up in JNDI.	You must specify either a queue or a topic.
GD={true \| false}	Indicates whether to use Guaranteed Delivery. The default value is false. For best results, the stream's GD setting should match the adapter's setting.	Optional.
sessionID=<text>	The session ID is an arbitrary identifier, but must be unique among all publishers to a stream and among all subscribers to a stream. An adapter instance must be started with the same sessionID each time.	Required for GD.
clientID=<text>	A JMS clientID.	Required for GD input using a topic.
durableName=<text>	The name used within the clientID for the durable subscription (JMS GD input adapter only).	Required for GD input using a topic.
factoryName=<factoryName>	The name of the factory in JMS. This varies depending on the which vendor's JMS you are using.	Required.
initialNamingFactory= <initialNamingFactory>	The initial naming factory for JMS implementation. For example, the Joram JMS implementation uses `fr.dyade.aaa.jndi2.client.NamingContextFactory` as the value. This value is also the default value.	Optional.
streamURL=<CCL_URL>	The CCL URL of the stream to which the adapter should publish or subscribe. For example, `ccl://localhost:6789/Stream/Default/JMSTest/InStream`	Required.
messageType=<message type>	MapMessage or TextMessage. The default is MapMessage.	Optional.
C8username=<userID>	If this is set, then the connection to Sybase CEP Server uses credentials to authenticate the user.	Optional.
C8password=<password>	The password for the specified username, used in the credentials along with the c8username.	Optional.
JMShost=<hostname>	The host computer on which the JMS server is running. The default value is `localhost`.	Optional.
JMSport=<port>	The port that the JMS server is using. The default value is 16400.	Optional.
batchSize=<integer>	If the adapter is using GD, then the adapter will attempt to send rows in batches of the specified size. When running as an input adapter, the adapter sends the data to the Sybase CEP Server as soon as either the batch size or commitIntervalMsec is reached, whichever comes first. If both batchsize and rate are set, rate is used. When running as an output adapter, the adapter performs a JMS transaction when it reaches either the batchSize or the commitIntervalMsec, whichever comes first. The default batch size is 500.	Optional.
rate=<float>	For GD input, the adapter attempts to send at approximately this rate. If both rate and batchSize are set, rate is used.	Optional.
commitIntervalMsec=<integer>	The adapter sends a batch at least this often (in milliseconds) unless there are Optional. rows to send. The default value is 500 milliseconds.	Optional.
statusFile=<filename>	The file name to which the adapter should write status if the adapter is either a GD output adapter, or aGD input adapter for topics. File names must be different for each instance of the adapter. The default file name is JMSAdapter.status.	Optional.
debug=true	Indicates whether to print out debug information about "high-level" operations. By default, debugging is off.	Optional.
debugVerbose=true	Indicates whether to print out debug information about each message. By default verbose debugging is off.	Optional.

Although the GD settings of the stream and adapter are not required to match, we strongly recommend that both turn on GD or both turn off GD. A stream's GD settings may be specified at the level of the stream, or can be inherited from the project that the stream is within.

When the JMS adapter constructs the message, the adapter uses the current time as the message time. This can cause issues if the commit interval for the server is larger than the max delay (or even approximately the same length as the max delay), or if the adapter machine’s clock is set significantly later than the server machine’s clock.

Troubleshooting:When the adapter starts, it prints all the arguments set on the command line and in the jndi.properties file. Check these values to ensure that the arguments the adapter used are the arguments you intended. The jndi.properties printing serves two purposes. First, it shows that the adapter found a jndi.properties file in one of the directories specified in the CLASSPATH. Second, it shows the contents.

If you use GD with topics as opposed to queues, you will need durable subscriptions. Not all JMS implementations support durable subscriptions.