Message Buffer PlainHttp Sample

Message Buffers are small, temporary message caches that enable “Web programming model” scenarios. Such situations arise when you cannot use an AppFabric 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 .NET Services 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.

- PUT: Creates a new resource or updates an existing resource.
- POST: Updates an existing resource.
- DELETE: Deletes an existing resource.
- GET: Retrieves a representation of a resource.

In Windows Azure platform AppFabric, POST is used to send credentials to the AppFabric 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

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