17 Using the Java Message Service

This chapter describes how to use the Java Message Service (JMS) API. The Oracle GlassFish Server has a fully integrated JMS provider: the GlassFish Server Message Queue software.

Note:

JMS resources are supported only in the full GlassFish Server, not in the Web Profile.

For information about the JMS API, see "Java Message Service Concepts" in The Java EE 6 Tutorial and "Java Message Service Examples" in The Java EE 6 Tutorial.

For detailed information about JMS concepts and JMS support in the GlassFish Server, see "Administering the Java Message Service (JMS)" in Oracle GlassFish Server Administration Guide.

For more information about Message Queue software, see the Oracle GlassFish Server Message Queue Administration Guide.

The following topics are addressed here:

Using Application-Scoped JMS Resources
Load-Balanced Message Inflow
Authentication With ConnectionFactory
Delivering SOAP Messages Using the JMS API

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 glassfish-resources.xml deployment descriptor file. For details, see "Application-Scoped Resources" in Oracle GlassFish Server Application Deployment Guide.

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 Oracle GlassFish Server Application Deployment Guide.

The GlassFish Server transparently enables messages to be delivered in random fashion to message-driven beans having same ClientID. The ClientID is required for durable subscribers.

For nondurable 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 the GlassFish 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 Oracle Message Queue software allows multiple message-driven beans to consume messages from 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 colocated 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 GlassFish Server instances that belong to a cluster.

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, the GlassFish Server searches the container for authentication information before using the supplied user and password. Version 7 of the GlassFish Server threw an exception in this situation.

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.

For more information about SOAP, see the Apache SOAP web site at http://xml.apache.org/soap/index.html.

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.

The following topics are addressed here:

To Send SOAP Messages Using the JMS API
To Receive SOAP Messages Using the JMS API

To Send SOAP Messages Using the JMS API

Import the MessageTransformer library.
```
import com.sun.messaging.xml.MessageTransformer;
```
This is the utility whose methods you use to convert SOAP messages to JMS messages and the reverse. 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.

tcf = new TopicConnectionFactory();
tc = tcf.createTopicConnection();
session = tc.createTopicSession(false,Session.AUTO_ACKNOWLEDGE);
topic = session.createTopic(topicName);
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 GlassFish 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 whose methods you use to convert SOAP messages to JMS messages and the reverse. 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.

messageFactory = MessageFactory.newInstance();
tcf = new com.sun.messaging.TopicConnectionFactory();
tc = tcf.createTopicConnection();
session = tc.createTopicSession(false, Session.AUTO_ACKNOWLEDGE);
topic = session.createTopic(topicName);
subscriber = session.createSubscriber(topic);
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) {
SOAPMessage soapMessage =
 MessageTransformer.SOAPMessageFromJMSMessage( message,
 messageFactory ); }

Retrieve the content of the SOAP message.