# Configuring a JMS Control

The JMS control enables WebLogic Workshop applications to interact with JMS messaging systems. When you create a JMS control, you specify the messaging style (queue or topic) and provide the JNDI identification for the sending and receiving queue or topic. You also specify a connection factory for the control. You can modify these settings later in the Property Editor pane in Design View, or you can directly modify the attributes of the @jc:jms annotation in Source View. For detailed information on the @jc:jms annotation and its attributes, see @jc:jms annotation.

Once you've set up the JMS control, you can add code to send and receive messages via JMS.

## JMS Control Methods

The JMS control has the following default methods upon creation:

- The getSession() method, which gives you programmatic access to the JMS session. You don't need to call this method, but it's available to you if you want more control.
- One of the following methods for sending a message to the service, depending on what value you selected for the Message Type when you created the control: sendTextMessage(), sendBytesMessage(), sendObjectMessage(), or sendJMSMessage(). You can use one or more of these methods, or you can define your own methods for sending a message to the service.
- The subscribe() method, which you can call from your code to subscribe to a JMS topic.
- The unsubscribe() method, which you can call from your code to unsubscribe from a JMS topic.

All of the methods you define on the JMS control send or publish to the queue or topic named by the send-jndi-name attribute of the @jc:jms annotation.

## JMS Control Callback

The JMS control has a single callback defined by default. You can replace this callback with your own, but you may have only one callback on the JMS control. The reason for this restriction is that the messaging service returns a message to the control via this callback, and it can call only one. Depending on the value you selected for the Message Type when you created the control, the default callback will be one of the following: receiveTextMessage(), receiveBytesMessage(), receiveObjectMessage(), or receiveJMSMessage(). The callback you define on the JMS control receives from the topic or queue named by the receive-jndi-name attribute of the control's @jc:jms annotation.

If the JMS control cannot deliver a message to a control instance via the callback (for example, if there is no conversation ID for a control that listens to a queue), it throws an exception from the JMSControl.onMessage method. This causes the current transaction to be rolled back. What happens next depends on how the administrator set up the JMS destination. The destination should be set up to have a small retry count and an error destination, which allows the processing to stop when an error is thrown. However, if the destination is configured with a large retry count or no retry count and with no error destination, the JMS control infrastructure continues attempting to process the message (unsuccessfully) forever.

Note that failure to deliver a message can be caused by an uncaught exception in code running in the callback handler, or in code running in a method called by the callback handler. Make sure that you catch all exceptions so that your code can adapt to this situation if it happens.

## A Note On Testing Callback Handlers

When testing callback handlers, you must invoke the handler via a service control. If you invoke the service from the test interface, the callback handlers are never invoked. The callback handlers have to be tested from a client that implements the callback interface, which the test interface cannot.

## Working With Multiple Types of Web Services

If you have multiple types of web services (which is different from having multiple instances of the same type) that reference the same receive-jndi-name for a queue, you must use the receive-selector attribute in a way that causes the web services to partition all received messages into disjoint sets. If this is not handled properly, messages for a particular conversation might be sent to a control instance that does not participate in that conversation.
Note that if you rename a web service that uses a JMS control without undeploying the initial version, the initial version and the new version will be using an identically configured JMS control and will violate this caveat.

## Experimenting with JMS Control Samples

In order to support JMS control samples, two queues and one topic are configured on the sample Workshop domain when WebLogic Workshop is installed. The queues are named SimpleJmsQ and CustomJmsCtlQ, and the topic is named jms.AccountUpdate. The connection factory that provides connections to these queues has the JNDI name weblogic.jws.jms.QueueConnectionFactory. You can use these resources to experiment with JMS controls.

You can see samples of the JMS control in the SamplesApp application, in the jms directory of the WebServices project.

Note: Each JMS control should use a unique queue. Multiple JMS controls on the same server may not simultaneously use the same queue.

Related Topics

JMS Control

Creating a New JMS Control