Using Jakarta Messaging

This chapter describes how to use the Jakarta Messaging (JMS) API. Payara Server has a fully integrated JMS provider: the Open Message Queue software.

JMS resources are supported only in the Full Profile, not in the Web Profile.

For information about the JMS, see "Messaging" in The Jakarta EE Tutorial.

For detailed information about JMS concepts and JMS support in Payara Server, see "Administering Jakarta Messaging (JMS)" in the Payara Server General Administration section.

Using Application-Scoped JMS Resources

You can define an application-scoped JMS or other resource for an enterprise application, web module, EJB module, connector module, or application client module by supplying a payara-resources.xml deployment descriptor file. For details, see "Application-Scoped Resources" in the Payara Server Application Deployment section.

Load-Balanced Message Inflow

You can configure ActivationSpec properties of the jmsra resource adapter in the glassfish-ejb-jar.xml file for a message-driven bean using activation-config-property elements. Whenever a message-driven bean (EndPointFactory) is deployed, the connector runtime engine finds these properties and configures them accordingly in the resource adapter.

See "activation-config-property" in the Payara Server Application Deployment section.

Payara Server transparently enables messages to be delivered in random fashion to message-driven beans having the same ClientID.

The ClientID is required for durable subscribers.
For non-durable subscribers in which the ClientID is not configured, all instances of a specific message-driven bean that subscribe to same topic are considered equal.

When a message-driven bean is deployed to multiple instances of Payara Server, only one of the message-driven beans receives the message. If multiple distinct message-driven beans subscribe to same topic, one instance of each message-driven bean receives a copy of the message.

To support multiple consumers using the same queue, set the maxNumActiveConsumers property of the physical destination to a large value. If this property is set, the Open Message Queue software allows multiple message-driven beans to consume messages from the same queue.

The message is delivered randomly to the message-driven beans. If maxNumActiveConsumers is set to -1, there is no limit to the number of consumers.

To ensure that local delivery is preferred, set addresslist-behavior to priority. This setting specifies that the first broker in the AddressList is selected first.

This first broker is the local co-located message queue instance. If this broker is unavailable, connection attempts are made to brokers in the order in which they are listed in the AddressList. This setting is the default for Payara Server instances that belong to a cluster or deployment group.

Authentication With `ConnectionFactory`

If your web, EJB, or client module has res-auth set to Container, but you use the ConnectionFactory.createConnection("user","password") method to get a connection, Payara Server searches the container for authentication information before using the supplied user and password.

Delivering SOAP Messages Using the JMS API

Web service clients use the Simple Object Access Protocol (SOAP) to communicate with web services. SOAP uses a combination of XML-based data structuring and Hyper Text Transfer Protocol (HTTP) to define a standardized way of invoking methods in objects distributed in diverse operating environments across the Internet.

You can take advantage of the JMS provider’s reliable messaging when delivering SOAP messages. You can convert a SOAP message into a JMS message, send the JMS message, then convert the JMS message back into a SOAP message.

To Send SOAP Messages Using the JMS API

Import the MessageTransformer library.
```
import com.sun.messaging.xml.MessageTransformer;
```
This is the utility class whose methods you use to convert SOAP messages to JMS messages and vice-versa. You can then send a JMS message containing a SOAP payload as if it were a normal JMS message.

Initialize the TopicConnectionFactory, TopicConnection, TopicSession, and publisher components.

var tcf = new TopicConnectionFactory();
var tc = tcf.createTopicConnection();
var session = tc.createTopicSession(false,Session.AUTO_ACKNOWLEDGE);
var topic = session.createTopic(topicName);
var publisher = session.createPublisher(topic);

Construct a SOAP message using the SOAP with Attachments API for Java (SAAJ).

/*construct a default soap MessageFactory */
MessageFactory mf = MessageFactory.newInstance();
* Create a SOAP message object.*/
SOAPMessage soapMessage = mf.createMessage();
/** Get SOAP part.*/
SOAPPart soapPart = soapMessage.getSOAPPart();
/* Get SOAP envelope. */
SOAPEnvelope soapEnvelope = soapPart.getEnvelope();
/* Get SOAP body.*/
SOAPBody soapBody = soapEnvelope.getBody();
/* Create a name object. with name space */
/* http://www.sun.com/imq. */
Name name = soapEnvelope.createName("HelloWorld", "hw",
 "http://www.sun.com/imq");
* Add child element with the above name. */
SOAPElement element = soapBody.addChildElement(name)
/* Add another child element.*/
element.addTextNode( "Welcome to Payara Web Services." );
/* Create an atachment with activation API.*/
URL url = new URL ("http://java.sun.com/webservices/");
DataHandler dh = new DataHandler (url);
AttachmentPart ap = soapMessage.createAttachmentPart(dh);
/*set content type/ID. */
ap.setContentType("text/html");
ap.setContentId("cid-001");
/** add the attachment to the SOAP message.*/
soapMessage.addAttachmentPart(ap);
soapMessage.saveChanges();

Convert the SOAP message to a JMS message by calling the MessageTransformer.SOAPMessageintoJMSMessage() method.
```
Message m = MessageTransformer.SOAPMessageIntoJMSMessage(soapMessage, session);
```
Publish the JMS message.
```
publisher.publish(m);
```
Close the JMS connection.
```
tc.close();
```

To Receive SOAP Messages Using the JMS API

Import the MessageTransformer library.
```
import com.sun.messaging.xml.MessageTransformer;
```
This is the utility class whose methods you use to convert SOAP messages to JMS messages and vice-versa. The JMS message containing the SOAP payload is received as if it were a normal JMS message.

Initialize the TopicConnectionFactory, TopicConnection, TopicSession, TopicSubscriber, and Topic.

var messageFactory = MessageFactory.newInstance();
var tcf = new com.sun.messaging.TopicConnectionFactory();
var tc = tcf.createTopicConnection();
var session = tc.createTopicSession(false, Session.AUTO_ACKNOWLEDGE);
var topic = session.createTopic(topicName);
var subscriber = session.createSubscriber(topic);
var subscriber.setMessageListener(this);
tc.start();

Use the OnMessage method to receive the message. Use the SOAPMessageFromJMSMessage method to convert the JMS message to a SOAP message.

public void onMessage (Message message) {
    var soapMessage = MessageTransformer.SOAPMessageFromJMSMessage(message,messageFactory);
}

Retrieve the content of the SOAP message.