Fuse Message Broker - Connectivity Guide

Protocol Details

What is REST?

Representational State Transfer (REST) is a software architecture designed for distributed systems, like the World Wide Web. For details of the REST architecture and the philosophy underlying it, see the REST Wikipedia article.

One of the key concepts of a RESTful architecture is that the interaction between different network nodes should take on a very simple form. In particular, the number of operations in a RESTful protocol must be kept small: for example, the REST protocol in Fuse requires just three operations.

Outline of a REST interaction

In general, a REST interaction consists of the following elements:

Operation—belongs to a restricted, well-known set of operations—for example, in the HTTP protocol, the main operations are GET, POST, PUT, and DELETE. The advantage of this approach is that, in contrast to RPC architectures, there is no need to define interfaces for a RESTful protocol. The operations are all known in advance.
URI—identifies the resource that the operation acts on. For example, a HTTP GET operation acts on the URI by fetching data from the resource identified by the URI.
Data (if required)—needed for operations that send data to the remote resource.

HTTP as a RESTful protocol

HTTP is a good example of a protocol demonstrating RESTful design principles. In fact, proponents of REST argue that it is precisely the RESTful qualities of HTTP that enabled the rapid expansion of the World Wide Web. In keeping with REST principles, HTTP has a restricted operation set, consisting of only eight operations: GET, POST, PUT, DELETE, OPTIONS, HEAD, TRACE, and CONNECT.

For the purpose of implementing a RESTful protocol, the first four HTTP operations—GET, POST, PUT, and DELETE—are the most important. The semantics of these operations are described briefly in Table 9 .

Table 9. HTTP RESTful Operations

Operation	Description
`GET`	Fetch the remote resource identified by the URI.
`POST`	Add/append/insert data to the remote resource identified by the URI.
`PUT`	Replace the remote resource identified by the URI with the data from this operation.
`DELETE`	Delete the remote resource identified by the URI.

This simple set of operations—analogous to the classic CRUD (Create, Replace, Update, and Delete) operations for a database—turns out to be remarkably powerful and flexible.

REST protocol servlets

The following servlets—which are automatically deployed in the message broker Web console—implement RESTful access to the Fuse message queues:

message servlet

The RESTful Web service implemented by the Fuse message servlet enables you to enqueue and dequeue messages over HTTP. You can, therefore, use the message servlet to implement message producers and message consumers as Web forms.

To interact with the Fuse message servlet, construct a URL of the following form:

http://Host:Port/WebContext/message/DestinationPath?Opt1=Val1&Opt2=Val2...

Where the URL is constructed from the following parts:

Host:Port—the host and port of the servlet engine. For example, in the default message broker configuration, a HTTP port is opened on localhost:8161.
WebContext—in a Web application, it is usual to group related components (servlets and so on) under a particular Web context, WebContext. For example, for the REST demonstration servlets, the Web context is demo by default.
message—routes this URL to the message servlet.
DestinationPath—specifies the compound name of a queue or topic in the message broker. For example, the FOO.BAR queue has the destination path, FOO/BAR.
?Opt1=Val1&Opt2=Val2—you can add some options in order to qualify how the URL is processed.

For example, the following URL can be used to fetch a message from the FOO.BAR queue, where the Web console has the default configuration:

http://localhost:8161/demo/message/FOO/BAR?type=queue&timeout=5000

Table 10 shows the URL options recognized by the message servlet:

Table 10. URL Options Recognized by the Message Servlet

URL Option	Description
`type`	Can be either `queue` or `topic`.
`timeout`	When consuming a message from a queue, specifies the length of time (in units of milliseconds) the client is prepared to wait.

Three HTTP operations—GET, POST, and DELETE—are recognized by the message servlet. The semantics of these operations are described briefly in Table 11 .

Table 11. Message Servlet RESTful HTTP Operations

Operation	Description
`GET`	Consume a single message from the destination (queue or topic) specified by the URL.
`POST`	Send a single message to the destination (queue or topic) specified by the URL.
`DELETE`	Consume a single message from the destination (queue or topic) specified by the URL. This operation has the same effect as `GET`.

For details of the form properties recognized by the message servlet (for POSTing a message), see Example of posting a message .

queueBrowse servlet

The RESTful Web service implemented by the queueBrowse servlet enables you to monitor the contents and status of any queue or topic in the Web console. Effectively, the queueBrowse servlet is a simple management tool.

To interact with the Fuse queueBrowse servlet, construct a URL of the following form:

http://Host:Port/WebContext/queueBrowse/DestinationPath?Opt1=Val1&Opt2=Val2...

The queueBrowse URL has a similar structure to the message URL (see message servlet ), except that the queueBrowse URL is built from WebContext/queueBrowse instead of WebContext/message.

For example, the following URL can be used to browse the FOO.BAR queue, where the Web console has the default configuration:

http://localhost:8161/demo/queueBrowse/FOO/BAR

Table 12 shows the URL options recognized by the queueBrowse servlet:

Table 12. URL Options Recognized by the QueueBrowse Servlet

URL Option	Description
`view`	Specifies the format for viewing the queue/topic. The following views are supported: `simple`—(default) displays a compact summary of the queue in XML format, where each message is shown as a `message` element with ID. `xml`—displays a detailed summary of the queue in XML format, where each message is shown in full. `rss`—displays a compact summary of the queue in the form of an RSS 1.0, 2.0 or Atom 0.3 feed. You can configure the type of feed using `feedType`.
`feedType`	In combination with the setting, `view=rss`, you can use this option to specify one of the following feeds: `rss_1.0` `rss_2.0` `atom_0.3`
`contentType`	Override the MIME content type of the view.
`maxMessages`	The maximum number of messages to render.

Example of posting a message

Example 1 shows an example of the Web form used to send a message to the FOO.BAR queue in the Web console, as demonstrated in Send a message .

Example 1. Web Form for Sending a Message to a Queue or Topic

<html>
<head>
  <title>Send a JMS Message</title>
  <link rel="stylesheet" href="style.css" type="text/css">
</head>
<body>
<h1>Send a JMS Message</h1>
<form action="message/FOO/BAR" method="post">
  <p>
    <label for="destination">Destination name</label>
    <input type="text" name="destination"/>
  </p>
  <p>
    <label for="type">Destination Type: </label>
    <select name="type">
      <option selected value="queue">Queue</option>
      <option type" value="topic">Topic</option>
   </select>
  </p>
  <p>
    <textarea name="body" rows="30" cols="80">
Enter some text here for the message body...
    </textarea>
  </p>
  <p>
    <input type="submit" value="Send"/>
    <input type="reset"/>
  </p>
</form>
</body>
</html>

Table 13 describes the form properties that are recognized by the message servlet.

Table 13. Form Properties Recognized by Message Servlet

Form Property	Description
Form action	The `action` attribute of the `<form>` tag has the format, `message/``DestinationPath`, where `DestinationPath` is the compound name of the queue or topic, using forward slash, `/`, as the delimiter (for example, `FOO/BAR`).
`destination`	The compound name of the destination queue or topic, using a period, `.`, as the delimiter (for example, `FOO.BAR`). If this property is specified in the form, it overrides the value of the `DestinationPath` in the form action.
`type`	Destination type, equals `queue` or `topic`.
`body`	Message body.

Example of getting a message

To consume a message from a topic or queue, send a HTTP GET operation (for example, by following a hypertext link) using the URL format described in message servlet . For example, to consume a message from the FOO.BAR queue, navigate to the following URL:

http://localhost:8161/demo/message/FOO/BAR?timeout=10000&type=queue

Examples of browsing a queue

To browse a queue using the queueBrowse servlet, simply navigate to an URL of the appropriate form, as described in queueBrowse servlet .

For example, to browse the FOO.BAR queue in XML format:

http://localhost:8161/demo/queueBrowse/FOO/BAR?view=xml

To browse the FOO.BAR queue as an Atom 1.0 feed:

http://localhost:8161/demo/queueBrowse/FOO/BAR?view=rss&feedType=atom_1.0

To browse the FOO.BAR queue as an RSS 1.0 feed:

http://localhost:8161/demo/queueBrowse/FOO/BAR?view=rss&feedType=rss_1.0

Comments powered by Disqus