The API for the proposed Universal Message Service (UMS) provides access to Message Queue messaging from any http-enabled device. The UMS protocol supports the sending and receiving of messages by both Java and non-Java clients (C clients, .NET clients, Python clients, Ajax clients, and so forth).

Two styles of messaging are supported by UMS:

- Simple Messaging. Can be used to send and receive text messages not encoded in XML format. UMS clients use a Simple Messaging API to send/receive XML or non-XML messages.

- XML Messaging. Can be used to send and receive XML messages only. Messages must be in SOAP message packaging format. UMS clients use an XML Messaging API to send/receive XML documents and attachments.

The UMS provides six messaging services, each requested by an http request message of the corresponding service type. Each request message must specify only one service type. The general request/response protocol for the Simple Messaging API and XML Messaging API are defined in the sections below. The detailed protocols for the six services, with examples, are documented at the following links:

login
send
receive
commit
rollback
close

1. Simple Messaging API

The http/https request/response protocol is used to request UMS services.

1.1 Service Requests

The http POST method must be used for each simple request message sent to the UMS.

For simple messaging, each request message is represented with the following syntax:

http://host:port/<ums-context-root>/simple?query_string

where <ums-context-root> is the deployment context root for the UMS service. The examples used in this document has the deployment context root configured to /ums .

where query_string is a series of field/value pairs (field=value) that specify the service type (such as send), JMS messaging domain (such as queue), JMS destination name, and so forth. The field/value pairs in a query string are separated by an ampersand (“&”). For more information about query string syntax, see http://en.wikipedia.org/wiki/Query_string.

Query String Field Name	Default Field Value	Description
sid	(not defined)	Session ID. Application obtains an sid from a "login" service request.
destination	(not defined)	JMS destination name.
domain	queue	JMS domain.
service	(not defined)	Value is one of the following: "login", "send", "receive", "close", "commit", "rollback".
user	guest	User name to authenticate to JMS server.
password	guest	Password to authenticate to JMS server.
timeout	7000 (milli secs)	"Receive" request timeout if no messages are available.
transacted	false	Used with "login" request to indicate the session is transacted. A transacted session is created if transacted=true. If set to true, a "commit" or "rollback" message must be sent to UMS to commit or rollback the session.

For example, for a Simple Messaging "send" service request, the text message to be sent is placed in the http request message body. Upon receiving the request, the UMS service obtains the text message from the http request message body, sets the message to a JMS TextMessage, delivers it to the destination specified in the http query string, and sends an http response to the application.

For a Simple Messaging "receive" service request, the UMS service consumes a JMS TextMessage from the destination specified in the http query string, places the text message in the http response message body, and sends the http response to the application.

1.2 Service Responses

The UMS http response message extension-headers contain a series of field/value pairs that indicate the states of the requested service. The extension-header field names and values are shown in the following table:

Simple Messaging http Response Message Extension-Header Field Names and Values

Response Message Field Name	Response Message Field Value	Description
ums.service	login_reply or send_reply or receive_reply or commit_reply or rollback_reply or close_reply	The name of the response message
ums.destination	JMS destination name associated with the service request	JMS destination name associated with the service request.
ums.domain	queue or topic	JMS domain associated with the service request.
ums.mom	openmq	The JMS service provider.
ums.status	200 indicates the request service was successful.	The http status code. For "receive" service request, 404 indicates no message is available.

The ums.status field (http status code) indicates the status of a service request. An http 200 (OK) response status code indicates successful completion of the requested service. All other response status codes indicate an error for the service request.

For example, an http 200 (OK) response status code for a "send" service request indicates that a message has been sent successfully. All other response status code indicates that the message might not have been sent successfully.

If no message is available for a "receive" service request within the timeout period (default 7 seconds), the http response message body is set to empty.

http status codes are defined here:
http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html

2. XML Messaging API.

The http/https request/response protocol is used to request UMS services.

2.1 Service Requests

The http POST method must be used for each xml request message sent to the UMS.

For XML messaging, the default URL service request is represented as follows.

http://host:port/<ums-context-root>/xml

where <ums-context-root> is the deployment context root for the UMS service. The examples used in this document has the deployment context root configured to /ums .

Each http POST request message sent to the UMS must conform to the following format:

- The XML message must be in the SOAP message format. All the XML element and attribute names defined in the document are name space qualified names. The value of the name space URI must be set to "https://mq.dev.java.net/ums".

- A MessageHeader element must be present and must be an immediate child element of the SOAP header element.

- A Service element must be present and must be an immediate child element of the MessageHeader element.

The MessageHeader element contains the following child elements.

xmlns:tns="https://mq.dev.java.net/ums"
<xsd:element name="MessageHeader">
       <xsd:complexType>
              <xsd:sequence>
                     <element ref="tns:Service" />
              </xsd:sequence>
              <attributeGroup ref="tns:headerExtensionGrp" />
       </xsd:complexType>
</xsd:element>

The Service element defines attributes that specify the UMS service, JMS messaging domain, JMS destination name, and so forth. The attributes of the Service element correspond to the field/value pairs defined in the query string of the Simple Messaging API:

<element name="Service">
        <complexType>
            <attribute name="sid" type="tns:non-empty-string" >
            <attribute name="destination" type="tns:non-empty-string" >
            <attribute name="domain" type="tns:domain.type" />
            <attribute name="service" type="tns:serviceAttr.type" use="required"/>
            <attribute name="user" type="tns:non-empty-string" >
            <attribute name="password" type="tns:non-empty-string" >
            <attribute name="timeout" type="xsd:long" />
            <attribute name="transacted" type="xsd:boolean" />
        </complexType>
    </element>

The schema of an XML service request conforms to the message.xsd XML schema. (Note, however, that the Service element for a service request does not include the "status" attribute.)

For example, for an XML Messaging "send" service request, the UMS service transforms the SOAP message into a JMS BytesMessage, delivers it to the destination specified in the destination attribute, and sends an http response to the application.

For a XML Messaging "receive" service request, the UMS service consumes a JMS message from the destination specified in the destination attribute, transforms it from a JMS BytesMessage into a SOAP message, and sends the http response to the application.

Any (text/binary) data may be attached as SOAP attachment(s) when using the XML Messaging API.

JMS applications may use com.sun.messaging.xml.MessageTransformer utility to transform between JMS and SOAP messages when connected to destinations used by UMS applications. For example, a stand-alone JMS application can send a SOAP message (using the MessageTransformer utility) to a JMS destination. An AJAX application can receive the message from the same destination in SOAP format through the UMS.

2.2 Service Responses

The service response messages are packaged in SOAP format. The attributes of the response messages are set in the Service element of the response SOAP message. These attributes correspond to field/value pairs of the response message extension-header of the Simple Messaging API.

The schema of the XML response message conforms to the message.xsd XML schema.

As in the case of the Simple Messaging API, the http status code indicates the status of a service request. An http 200 (OK) response status code indicates successful completion of the requested service. All other response status codes indicate an error for the service request.

References:

HTTP] Hypertext Transfer Protocol -- HTTP/1.1 (http://www.ietf.org/rfc/rfc2616.txt)
[HTTP Authentication: Basic and Digest Access Authentication] http://www.ietf.org/rfc/rfc2617.txt
[XML] Extensible Markup Language (XML) 1.0 (http://www.w3.org/TR/1998/REC-xml-19980210)
[SOAP] Simple Object Access Protocol (SOAP) Version 1.1 (http://www.w3.org/TR/SOAP/)
[SOAP Messages with Attachments] http://www.w3.org/TR/SOAP-attachments
[javax.xml.soap package] http://java.sun.com/javase/6/docs/api/index.html
[Servlet] http://java.sun.com/products/servlet/docs.html
[J2EE tutorial] http://java.sun.com/j2ee/1.4/docs/tutorial/doc/index.html