# UMS Protocol

The API for the 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 as well as from simple HTML Pages).

The UMS protocol has two parts: a set of functions that use the HTTP POST protocol and a set of functions that use the simpler HTTP GET protocol.

HTTP POST functions

These functions all involve the sending of a HTTP POST requests to the server. They support the following two types of messaging:

- Simple Messaging using HTTP POST. This 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 using HTTP POST. This 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 POST functions (both simple and XML) consist of 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

HTTP GET functions

These functions all involve the sending of HTTP GET requests to the server. These are simpler than the POST functions and can be invoked from simple HTMP pages or even typed directly into the address bar of a browser.

- Query and utility functions using HTTP GET. These consist of various additional functions which can be performed simply by entering a URL In a browser.

1. Simple Messaging using HTTP POST
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.

The query_string field names and values are shown in the following table:

Simple Messaging Query String Field Names and Values

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 using HTTP POST
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.

3. Query and utility functions using HTTP GET

3.1 Obtain broker information using HTTP GET (getBrokerInfo service)

This allows broker information to be obtained by simply typing a URL in the browser's address bar. The output is in XML format and would be displayed in the browser window.

The XML returned consists of a standard header element followed by a body element whose contents depend on the type of query being performed. The structure of the XML returned is defined in the UMS Broker Monitoring service: XML output specification

At present only one type of broker information query is available: getDestinations.

3.1.1 getDestinations

This allows information about the destinations in the broker to be obtained.

Usage:

    http://<host>:<port>/<ums_context>/simple?service=getBrokerInfo&cmd=getDestinations
    [&dest-elements=<elementName>[,<elementName>]*]
    [&user=<user>&password=<password>]

    The optional parameter dest-elements can be used to specify a comma-separated list of destination attributes to be returned. If omitted, all destination attributes are returned.

    The specified user must be a valid administration user for this function to work successfully.

For example:

http://localhost:8080/imqums/simple?service=getBrokerInfo&cmd=getDestinations
&user=admin&password=admin

    Returns all attributes of each destination.

`http://localhost:8080/imqums/simple?service=getBrokerInfo&cmd=getDestinations
&dest-elements=Name,Type,NumMsgs&user=admin&password=admin`

    Returns the attributes Name, Type and NumMsgs of each destination.

3.2 Obtain UMS configuration information using HTTP GET (getConfiguration service)

This allows information about the UMS configuration to be obtained.

Usage:

    http://<host>:<port>/<ums_context>/simple/?service=getConfiguration[&user=<user>&password=<password>]

    The specified user must be a valid administration user for this function to work successfully.

For example:

http://localhost:8080/imqums/simple?service=getConfiguration&user=admin&password=admin

Example output:

    <ums>
        <BrokerAddress>localhost:7676</BrokerAddress>
        <JMSAuthenticate>true</JMSAuthenticate>
        <CacheDuration>420000</CacheDuration>
        <SweepInterval>120000</SweepInterval>
        <ReceiveTimeout>7000</ReceiveTimeout>
        <MaxClientsPerConnection>100</MaxClientsPerConnection>
    </ums>

3.3 Configure UMS debug logging using HTTP GET (debug service)

This allows debug logging in the UMS server to be switched on and off. This logging is written to the application server log.

Usage:

`http://<host>:<port>/<ums_context>/simple?service=debug&debug=<true|false>``[&user=<user>&password=<password>]`

`The specified user must be a valid administration user for this function to work successfully.`

For example:

http://localhost:8080/imqums/simple?service=debug&debug=true&user=admin&password=admin

Example output:

    service=debug, debug=true

3.4 Ping a broker using HTTP GET (ping service)

This communicates with the broker to confirm that it is running.

Usage:

    http://<host>:<port>/<ums_context>/simple?service=ping[&user=<user>&password=<password>]

For example:

http://localhost:8080/imqums/simple?service=ping&user=admin&password=admin

Example output:

    Broker is alive, round trip = 78 milli secs.

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