Sun Java logo     Previous      Contents      Index      Next     

Sun logo
Sun Java System Application Server Platform Edition 2004Q4 Beta Developer's Guide 

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 general information about the JMS API, see the J2EE tutorial:

http://java.sun.com/j2ee/1.4/docs/tutorial/doc/JMS.html#wp84181

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

This chapter contains the following sections:

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.

The relationship of the Sun Java System Message Queue software to the Sun Java System Application Server can be one of these types: LOCAL or REMOTE. The results of these choices are as follows:

For more information about setting the type and the default JMS host, see Configuring the JMS Service.

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

http://docs.sun.com/db/prod/s1.s1msgqu#hic

For general information about the JMS API, see the JMS web page at:

http://java.sun.com/products/jms/index.html

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:

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

http://developers.sun.com/prodtech/appserver/reference/techart/as8_connectors

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:

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

http://docs.sun.com/db/prod/s1.s1msgqu#hic

Configuring the JMS Service

The JMS Service configuration is available to all inbound and outbound connections pertaing to the Sun Java System Application Server. You can edit or check the JMS Service configuration in the following ways:

You can override the JMS Service configuration using JMS connection factory settings. For details, see the Sun Java System Application Server Administration Guide.

Note

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

Creating JMS Hosts

A JMS host refers to a Sun Java System Message Queue broker. A default JMS host for the JMS service is provided, named default_JMS_host. If you have created a cluster in the Sun Java System Message Queue software, delete the default JMS host, then add the Message Queue cluster’s brokers as JMS hosts.

You can create additional JMS hosts in the following ways:

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. For details, see the Sun Java System Application Server Utility Reference.

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.

This section describes how to create a physical destination. To create a destination resource, see Creating JMS Resources: Destinations and Connection Factories.

You can create a JMS physical destination in the following ways:

Creating JMS Resources: Destinations and Connection Factories

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

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

Restarting the JMS Client After JMS Configuration

When a JMS client accesses a JMS administered object for the first time, the client JVM retrieves the JMS service configuration from the Sun Java System Application Server. Further changes to the configuration are not available to the client JVM until the client is restarted.

JMS Connection Features

The Sun Java System Message Queue software supports the following JMS connection features:

Both these features use the imqAddressList configuration, which is populated with the hosts and ports of the JMS hosts defined in the Sun Java System Application Server. The imqAddressList is updated whenever a JMS host configuration changes.

Connection Pooling

The Sun Java System Application Server pools JMS connections automatically.

When the addresslist-behavior JMS service attribute is set to its default value of random, each ManagedConnection (physical connection) created from the ManagedConnectionFactory selects its primary broker in a random way from the imqAddressList.

When a JMS connection pool is created, there is one ManagedConnectionFactory instance associated with it. If you configure the imqAddressList as a ManagedConnectionFactory property, the imqAddressList configuration in the ManagedConnectionFactory takes precedence over the one defined in the Sun Java System Application Server.

Connection Failover

To specify whether the Application Server tries to reconnect to the primary broker if the connection is lost, set the reconnect-enabled attribute in the JMS service. To specify the number of retries and the time between retries, set the reconnect-attempts and reconnect-interval-in-seconds attributes, respectively.

If reconnection is enabled and the primary broker goes down, the Sun Java System Application Server tries to reconnect to another broker in the imqAddressList. The imqAddressList is updated whenever a JMS host configuration changes. The logic for scanning is decided by two JMS service attributes, addresslist-behavior and addresslist-iterations.

You can override these settings using JMS connection factory settings. For details, see the Sun Java System Application Server Administration Guide.

The Sun Java System Message Queue software transparently transfers the load to another broker when the failover occurs. JMS semantics are maintained during failover.

Transactions and Non-Persistent Messages

During transaction recovery, non-persistent messages might be lost. If the broker fails between the transaction manager’s prepare and commit operations, any non-persistent message in the transaction is lost and cannot be delivered. A message that is not saved to a persistent store is not available for transaction recovery.

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:

install_dir/domains/domain1/imq/var/instances/imqbroker

Version 7 of the Application Server stored this data in the following location:

install_dir/imq/var/instances/domain1_server

When executing Sun Java System Message Queue scripts such as install_dir/imq/bin/imqusermgr, 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.

For more information about SOAP, see the Apache SOAP web site:

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

Sending SOAP Messages Using the JMS API

Use the MessageTransformer utility to convert a SOAP message into a JMS message. Then send the JMS message containing the SOAP payload as if it were a normal JMS message.

  1. 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.

    2. import com.sun.messaging.xml.MessageTransformer;

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

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

  3. 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.

    4. *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();

  4. Convert the SOAP message to a JMS message by calling the MessageTransformer.SOAPMessageintoJMSMessage() method.

    5. Message m = MessageTransformer.SOAPMessageIntoJMSMessage (soapMessage, session );

  5. Publish the JMS message.

    6. publisher.publish(m);

  6. Close the JMS connection.

    7. tc.close();

Receiving SOAP Messages Using the JMS API

The JMS message containing the SOAP payload is received as if it were a normal JMS message. Use the MessageTransformer utility to convert the JMS message back into a SOAP message.

  1. 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.

    2. import com.sun.messaging.xml.MessageTransformer;

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

    3. 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();

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

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

  4. Retrieve the content of the SOAP message.


Previous      Contents      Index      Next     

Part No: 819-0079.   Copyright 2004 Sun Microsystems, Inc. All rights reserved.