Chapter 14 Using the Java Message Service

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

For detailed information about JMS concepts and JMS support in Sun Java System Application Server, see the Sun Java System Application Server Administration Guide.

The JMS Provider

Administration of the JMS Service

Message Queue Resource Adapter

ConnectionFactory Authentication

Message Queue varhome Directory

Delivering SOAP Messages Using the JMS API

The JMS Provider

Sun Java System Application Server support for JMS messaging, in general, and for message-driven beans, in particular, requires messaging middleware that implements the JMS specification: a JMS provider. Sun Java System Application Server uses the Sun Java System Message Queue software as its native JMS provider. The Sun Java System Message Queue software is tightly integrated into Sun Java System Application Server, providing transparent JMS messaging support. This support (known within Sun Java System Application Server as the JMS Service) requires only minimal administration.

For more information about the Sun Java System Message Queue, refer to the following documentation:

Administration of the JMS Service

To configure the JMS Service and prepare JMS resources for use in applications deployed to the Sun Java System Application Server, you must perform these tasks:

Configuring the JMS Service

Checking Whether the JMS Provider Is Running

Creating Physical Destinations

Creating JMS Resources: Destinations and Connection Factories

For information about other JMS administration tasks, see the Sun Java System Application Server Administration Guide and the Sun Java System Message Queue documentation at:

Configuring the JMS Service

Using the Administration Console

Using the Command Line Interface



Note	Sun Java System Application Server should be restarted after configuration of the JMS Service.

The “Using The Administration Console” section describes each JMS Service setting. The “Using The Command Line Interface” section merely lists syntax and default values.

Using the Administration Console

To edit the JMS Service configuration using the Administration Console, perform the following tasks:

http://host:port/asadmin

For example:

http://localhost:4848/asadmin

Click on the Java Message Service component.

You can edit the following information. Defaults are displayed.

Start Timeout (secs) - Specifies the amount of time the server waits at startup for the corresponding JMS instance to respond. If there is no response, startup is aborted. If set to 0, the server waits indefinitely. The default is 30 seconds.

Type - A value of LOCAL means the JMS provider is started along with the application server. A value of REMOTE means the JMS host is remote and is not started by the application server. A value of NONE means no JMS service is used.

Start Arguments - Specifies the string of arguments supplied for startup of the corresponding JMS instance. By default, there are no arguments.

To add a property, click the Add Property button and enter the property name and value. To delete properties, check the properties you want to delete, then click the Delete Properties button. The following table lists the standard JMS Service properties.

Table 14-1 JMS Service Properties
Property	Default	Description
instance-name	imqbroker	Specifies the full Sun Java System Message Queue broker instance name.
instance-name-suffix	none	Specifies a suffix to add to the full Sun Java System Message Queue broker instance name. The suffix is separated from the instance name by an underscore character (_). For example, if the instance name is imqbroker, appending the suffix xyz changes the instance name to imqbroker_xyz.
append-version	false	If true, appends the major and minor version numbers, preceded by underscore characters (_), to the full Sun Java System Message Queue broker instance name. For example, if the instance name is imqbroker, appending the version numbers changes the instance name to imqbroker_8_0.

Open on the Java Message Service component.

Open the JMS Hosts component and click on default_JMS_host.

You can edit the following information. Defaults are displayed.

Host - Specifies the host name of the JMS provider. The default is localhost.

Port - Specifies the port number used by the JMS provider. The default is 7676.

Admin Username - Specifies the administrator user name for the JMS provider. The default is admin.

Admin Password - Specifies the administrator password for the JMS provider. The default is admin.

Click the Save button.

Using the Command Line Interface

To configure the JMS service using the command line interface, use the asadmin set command. The syntax is as follows, with defaults shown for optional parameters that have them:

For more information about the optional general asadmin parameters (--password, --passwordfile, --host, --port, --secure, --terse, --echo, and --interactive), see the Sun Java System Application Server Administration Guide.

The jms_attribute_name is the JMS service attribute that needs to be configured. For example:

To view the list of JMS service attribute names that can be configured using the asadmin set command, use the asadmin get command with a wildcard. The asadmin get command has the same syntax as the asadmin set command. For example:

A list of attribute names for configuring the JMS service of the server1 application server instance is displayed as follows:

server.jms-service.init-timeout-in-seconds = 60
server.jms-service.start-args = <null>
server.jms-service.type = LOCAL

asadmin set --user joeuser server.jms-service.jms-host.default_JMS_host.port=7677

The attribute_name for a JMS property is a hierarchical name that looks like this:

The jms_property_name is the JMS service property that needs to be configured. Here is an example of running the asadmin set command to set a JMS property:

Checking Whether the JMS Provider Is Running

You can use the asadmin jms-ping command to check whether a Sun Java System Message Queue instance is running. The syntax is as follows, with defaults shown for optional parameters that have them:

Creating Physical Destinations

Produced messages are delivered for routing and subsequent delivery to consumers using physical destinations in the JMS provider. A physical destination is identified and encapsulated by an administered object (a Topic or Queue destination resource) that an application component uses to specify the destination of messages it is producing and the source of messages it is consuming.

Using the Administration Console

Using the Command Line Interface

The “Using The Administration Console” section describes each physical destination setting. The “Using The Command Line Interface” section merely lists syntax and default values.

Using the Administration Console

To create a JMS physical destination using the Administration Console, perform the following tasks:

http://host:port/asadmin

For example:

http://localhost:4848/asadmin

Open the Java Message Service component.

Click Service, then click Physical Destinations.

Click the New button.

Enter the following information:

Destination Name (required) - Specify the name of the physical destination.

Type (required) - Select queue or topic from the list.

Click the OK button.

Using the Command Line Interface

To create a JMS physical destination using the command line, use the asadmin create-jmsdest command. The syntax is as follows, with defaults shown for optional parameters that have them:

asadmin create-jmsdest --user user --desttype dest_type [--property (name=value)[:name=value]*] dest_name

Creating JMS Resources: Destinations and Connection Factories

You can create two kinds of JMS resources in Sun Java System Application Server:

Connection Factories: administered objects that implement the QueueConnectionFactory or TopicConnectionFactory interfaces.

Destination Resources: administered objects that implement the Queue or Topic interfaces.

In either case, the steps for creating a JMS resource are the same. You can create a JMS resource in the following ways:

Using the Administration Console

Using the Command Line Interface

The “Using The Administration Console” section describes each JMS resource setting. The “Using The Command Line Interface” section merely lists syntax and default values.

Using the Administration Console

To create a JMS resource using the Administration Console, perform the following tasks:

http://host:port/asadmin

For example:

http://localhost:4848/asadmin

Open the Java Message Service component.

Click Connection Factories to create a connection factory, or click Destination Resources to create a queue or topic.

Click the New button.

Enter the following information:

JNDI Name (required) - Enter the JNDI name that application components must use to access the JMS resource.

Type (required) - Select the type of the JMS resource.

If you are on the Connection Factories page, the types are:

javax.jms.TopicConnectionFactory
javax.jms.QueueConnectionFactory

If you are on the Destination Resources page, the types are:

javax.jms.Topic
javax.jms.Queue

Description (optional) - You can enter a text description of the JMS resource.

Check the Resource Enabled box to enable the JMS resource.

If a JMS resource is disabled, no application component can connect to it, but its configuration remains in the domain.

Click the OK button.

To add a property, click the Add Property button and enter the property name and value. To delete properties, check the properties you want to delete, then click the Delete Properties button.

The following table lists the most commonly used JMS resource properties. For a complete list of the available properties (called administered object attributes in Sun Java System Message Queue), see the Sun Java System Message Queue Administration Guide.

Table 14-2 JMS Resource Properties
Property	Default	Description
Name	none	Specifies the JMS physical destination name associated with this JMS resource. You must specify this property for JMS resources of the Type javax.jms.Topic or javax.jms.Queue.
Description	none	Specifies a text description of the JMS resource.
MessageServiceAddressList	none	Specifies a list of host/port combinations of the Sun Java System Message Queue. For JMS resources of the Typejavax.jms.TopicConnectionFactory or javax.jms.QueueConnectionFactory.
ClientID	none	Specifies the JMS Client Identifier to be associated with a Connection created using the createQueueConnection and createTopicConnection methods of the QueueConnectionFactory and TopicConnectionFactory classes, respectively. For JMS resources of the Typejavax.jms.TopicConnectionFactory or javax.jms.QueueConnectionFactory. Durable subscription names are unique and only valid within the scope of a client identifier. To create or reactivate a durable subscriber, the connection must have a valid client identifier. The JMS specification ensures that client identifiers are unique and that a given client identifier is allowed to be used by only one active connection at a time.
UserName	guest	Specifies the username for connecting to the Sun Java System Message Queue. For JMS resources of the Typejavax.jms.TopicConnectionFactory or javax.jms.QueueConnectionFactory.
Password	guest	Specifies the password for connecting to the Sun Java System Message Queue. For JMS resources of the Typejavax.jms.TopicConnectionFactory or javax.jms.QueueConnectionFactory.



Note	All JMS resource properties that used to work with version 7 of the Application Server are supported for backward compatibility.

Click the OK button.

Using the Command Line Interface

To create a JMS resource using the command line, use the asadmin create-jms-resource command. The syntax is as follows, with defaults shown for optional parameters that have them:

asadmin create-jms-resource --user user --restype resource_type [--enabled=true] [--description text] [--property (name=value)[:name=value]*] jndi_name

asadmin create-jms-resource --user joeuser --restype javax.jms.Topic --property imqDestinationName=testTopic MyTopic

Message Queue Resource Adapter

The Sun Java System Message Queue is integrated into the Sun Java System Application Server using a resource adapter that is compliant with the Connector 1.5 specification. The module name of this system resource adapter is jmsra. Every JMS resource is converted to a corresponding connector resource of this resource adapter as follows:

Connection Factory: A connector connection pool with a max-pool-size of 250 and a corresponding connector resource.

Destination (Topic or Queue): A connector administered object.

You can use connector configuration tools to manage JMS resources. For more information, see:

ConnectionFactory Authentication

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

Message Queue varhome Directory

Sun Java System Message Queue uses a default directory for storing data such as persistent messages and its log file. This directory is called varhome. Sun Java System Application server uses domain_dir/imq as the varhome directory. Thus for the default Application Server domain, Message Queue data is stored in the following location:

When you execute Sun Java System Message Queue scripts such as install_dir/imq/bin/imqusermgr, you should use the -varhome option. For example:

imqusermgr -varhome $AS_INSTALL/domains/domain1/imq add -u testuser -p testpassword

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. The following sections explain how to do these conversions:

Sending SOAP Messages Using the JMS API

Receiving SOAP Messages Using the JMS API

Sending SOAP Messages Using the JMS API

You use the MessageTransformer utility to convert a SOAP message into a JMS message. You then send the JMS message containing the SOAP payload as you would a normal JMS message.

Import the library com.sun.messaging.xml.MessageTransformer. This is the utility whose methods you use to convert SOAP messages to JMS messages and the reverse.

import com.sun.messaging.xml.MessageTransformer;

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). For more information on constructing a SOAP message, see the Sun Java System Message Queue Developer’s Guide.

*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 Sun Java System 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();

Receiving SOAP Messages Using the JMS API

You receive the JMS message containing the SOAP payload as you would a normal JMS message. You then use the MessageTransformer utility to convert the JMS message back into a SOAP message.

Import the library com.sun.messaging.xml.MessageTransformer. This is the utility whose methods you use to convert SOAP messages to JMS messages and the reverse.

import com.sun.messaging.xml.MessageTransformer;

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.

Previous Contents Index Next
Sun Java System Application Server Platform Edition 8 Developer's Guide