mq5.0-source.src.share.java.webapps.ums.protocol.protocol.html Maven / Gradle / Ivy
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
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
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.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.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