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.
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, andDELETE. 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
GEToperation 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 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 4.1 .
Table 4.1. 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.
The following servlets—which are automatically deployed in the message broker Web console—implement RESTful access to the Fuse message queues:
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 onlocalhost: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 isdemoby default.message—routes this URL to themessageservlet.DestinationPath—specifies the compound name of a queue or topic in the message broker. For example, theFOO.BARqueue 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 4.2 shows the URL options recognized by the
message servlet:
Table 4.2. 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 4.3 .
Table 4.3. 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 .
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 4.4 shows the URL options recognized by the
queueBrowse servlet:
Table 4.4. URL Options Recognized by the QueueBrowse Servlet
| URL Option | Description |
|---|---|
view |
Specifies the format for viewing the queue/topic. The following views are supported:
|
feedType |
In combination with the setting,
|
contentType | Override the MIME content type of the view. |
maxMessages | The maximum number of messages to render. |
Example 4.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 4.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 4.5 describes the form properties that are recognized by the message servlet.
Table 4.5. Form Properties Recognized by Message Servlet
| Form Property | Description |
|---|---|
| Form action |
The |
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. |
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
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
 |  |  |
 |
