Message Buffers are small, temporary message caches that enable “Web programming model” scenarios. Such situations arise when you cannot use an Service Bus binding to create a message consumer. This scenario can arise if your consumer is written in Java, or if it is running on a non-Windows computer or on a mobile device. In this scenario, the message consumer uses Http calls to poll for messages, and the message buffer provides a place where messages sit for a short time until the polling request picks them up.

This sample demonstrates how to program the message buffer using its REST protocol. The message buffer protocol is an HTTP REST-based API that is designed to follow common REST principles. As such, you can easily leverage the protocol from any client without requiring the Windows Azure SDK. The protocol relies on the ACS HTTP authentication model to help enforce access control on the message buffer. Specifically, it uses the Simple Web Token (SWT) mechanism to retrieve a token using HTTP, then embeds it in an HTTP request as a header. This token includes claims that are used to determine whether or not an operation should be allowed.

Each message buffer has a unique URI in the Service Bus namespace. This URI is the "root" for a set of resources that represent the message buffer "instance." Each resource, in turn, has a unique URI and can be acted upon by a set of HTTP verbs. The URIs are organized in a way that helps convey the logical relationships between the different types of resources.

The verbs which act upon resources are modeled upon the standard HTTP verbs.

In Windows Azure, POST is used to send credentials to the Access Control service to retrieve a WRAP token, and to send a message to the message buffer. PUT is used to create a new message buffer or to update the policy of an existing message buffer.

The following section lists common operations that can be performed on the message buffers using the REST protocol.

Request a WRAP token from ACS

To interact with the Message Buffer, you must get a token from the appropriate Service Bus issuer.

Resource URI

https://{service-namespace}-sb.accesscontrol.windows.net/

HTTP Verb

POST

Request Headers

None

Request Body (encrypted)

wrap_name={issuer name}&wrap_password={issuer key}&applies_to=http://{service-namespace}.servicebus.windows.net/{message-buffer-name}

Response Body

wrap_access_token={token}&wrap_access_token_expires_in={token-expiry-time}

Create a new Message Buffer or update an existing one's policy

Resource URI

https://{service-namespace}.servicebus.windows.net/{message-buffer-name} (http is valid too)

HTTP Verb

PUT

Request Headers

Authorization: WRAP access_token="{token}"

Content-Type: application/atom+xml;type=entry;charset=utf-8

Request Body

{policy-xml} (Please refer the "Message Buffer policy schema" section in this document)

Response Body

{policy-xml} (policy properties will be assigned their default values if their values in the request are absent or invalid)

Delete a Message Buffer

Resource URI

https://{service-namespace}.servicebus.windows.net/{message-buffer-name}

HTTP Verb

DELETE

Request Headers

Authorization: WRAP access_token="{token}"

Request Body

(Empty)

Response Body

(Empty)

Get a Message Buffer's policy

Resource URI

https://{service-namespace}.servicebus.windows.net/{message-buffer-name}

HTTP Verb

GET

Request Headers

Authorization: WRAP access_token="{token}"

Request Body

(Empty)

Response Body

{policy-xml}

 

Send a message to the Message Buffer

Resource URI

https://{service-namespace}.servicebus.windows.net/{message-buffer-name}/messages

HTTP Verb

POST

Request Headers

Authorization: WRAP access_token="{token}"

Content-Type: application/atom+xml;type=entry;charset=utf-8

Request Body

{message-payload}

Response Body

(Empty)

Retrieve a message in the Message Buffer (destructive read)

Resource URI

https://{service-namespace}.servicebus.windows.net/{message-buffer-name}/messages/head?timeout={timeout-in-seconds}

HTTP Verb

DELETE

Request Headers

Authorization: WRAP access_token="{token}"

Request Body

(Empty)

Response Body

{message-payload}

Lock a message in the Message Buffer (non-destructive read)

Resource URI

https://{service-namespace}.servicebus.windows.net/{message-buffer-name}/messages/head?timeout={timeout-in-seconds}&lockduration={lockduration-in-secs}

HTTP Verb

POST

Request Headers

Authorization: WRAP access_token="{token}"

Request Body

(Empty)

Response Headers

X-MS-MESSAGE-LOCATION: https://{service-namespace}.servicebus.windows.net/{message-buffer-name}/messages/{message-id}

X-MS-LOCK-ID: {lock-id}

X-MS-LOCK-LOCATION: https://{service-namespace}.servicebus.windows.net/{message-buffer-name}/messages/{message-id}/{lock-id}

Response Body

{message-payload}

Unlock a locked message in the Message Buffer

Resource URI

https://{service-namespace}.servicebus.windows.net/{message-buffer-name}/messages/{message-id}/{lock-id}

HTTP Verb

DELETE

Request Headers

Authorization: WRAP access_token="{token}"

Request Body

(Empty)

Response Body

(Empty)

Delete a locked message from the Message Buffer

Resource URI

https://{service-namespace}.servicebus.windows.net/{message-buffer-name}/messages/{message-id}?lockid={lock-id}

HTTP Verb

DELETE

Request Headers

Authorization: WRAP access_token="{token}"

Request Body

(Empty)

Response Body

(Empty)

 Message Buffer policy XML schema

Xml 
<entry xmlns="http://www.w3.org/2005/Atom"><content type="text/xml">
<MessageBufferPolicy xmlns="http://schemas.microsoft.com/netservices/2009/05/servicebus/connect">
    <Authorization>{AuthorizationPolicy}</Authorization>
    <Discoverability>{DiscoverabilityPolicy}</Discoverability>
    <TransportProtection>{TransportProtectionPolicy}</TransportProtection>
    <ExpiresAfter>hh:mm:ss</ExpiresAfter>
    <MaxMessageCount>nnn</MaxMessageCount>
    <OverflowPolicy>{OverflowPolicy}</OverflowPolicy>
</MessageBufferPolicy>
</content>
</entry>

The various property values are as follows:

Authorization Policy

NotRequired, Required, RequiredToReceive, OR RequiredToSend

Discoverability Policy

Managers, ManagersListeners, ManagersListenersSenders, OR Public

Transport Protection Policy

None OR AllPaths

Expires After

hh:mm:ss

Max Message Count

nnn
Overflow Policy RejectIncomingMessage


Building and Running the Sample

After building the solution, do the following to run the application:

  1. From a command prompt, run the service application from bin\Debug\PlainHttp.exe.

  2. When prompted, enter the service namespace, issuer name and the issuer key.

  3. The sample will create a message buffer, retrieve a message from it and delete the message buffer.



Did you find this information useful? Please send your suggestions and comments about the documentation.