Oracle Messaging Cloud Service: Handling Messaging Transactions with HTTP

Purpose

This tutorial shows how to use Messaging Transactions with the Oracle Messaging Cloud Service via the REST interface, using the cURL command line tool. Through hands-on activities, you learn how to install the cURL tool, and practice issuing the commands to send and receive messages over the HTTP interface.

Time to Complete

Approximately 1 hour

Introduction

The Oracle Messaging Cloud Service provides a platform that enables data communication between processes within Oracle Cloud as well as outside of Oracle Cloud.

The Oracle Messaging Cloud Service provides several mechanisms to ensure reliable delivery of data. One such mechanism is Transacted Sessions which enables groups of sent and received messages to be grouped into a single atomic operation. If one send or receive in the group fails, all sends and receives in the group can be "undone".

Software Requirements

• It is assumed you have already procured an Oracle Messaging Cloud Service.
• A tool to access the REST interface. (This tutorial uses cURL, which is a free command line tool that runs on various operating systems.)
• One of the supported browsers listed in the following table:

Browser	Version
Internet Explorer	10 (Desktop), 9, 8
Firefox	Latest two production releases
Chrome	Current and previous Chrome versions at time of certification
Safari	6 or later
Safari Mobile	IOS 6 native Safari, certified on iPad 3
Android browser	4.0 or later

Prerequisites

Before starting this tutorial, you should:

• Have experience or familiarity with messaging queues for data communications
• Have experience or familiarity with the REST interfaces
• Have familiarity with Oracle Cloud services
• Have an installation of the cURL command-line tool on a 64-bit operating system that is enabled for the secure sockets layer (SSL). The authentication aspects of the Messaging Cloud Service require an SSL-enabled environment.
  If you do not already have cURL installed, click here for installation instructions.

About the Oracle Messaging Cloud Service

Oracle Messaging Cloud Service is a part of the Platform as a Service (PaaS) offerings. It provides a messaging platform for processes to communicate reliably with each other, enabling application developers to share information across multiple machines and even data centers.

By providing the messaging platform as a service in the cloud, Oracle Messaging Cloud Service gives developers an easier and more reliable method to build complex, distributed systems of heterogeneous applications that may have fundamentally different underlying characteristics such as programming platform, system uptime, and network latency. In addition, businesses using Oracle Messaging Cloud Service do not require any special, dedicated hardware, and the service can be accessed by applications from anywhere over the Internet.
 
Oracle Messaging Cloud Service is heavily influenced by the Java Message Service (JMS) API specification, which is a standard messaging interface for sending and receiving messages between enterprise Java applications. Oracle Messaging Cloud Service provides a Java library that implements and extends the JMS 1.1 interface. Any application platform that understands HTTP can also use Oracle Messaging Cloud Service through the REST interface. This means developers can use a single communication API to build reliable and robust communication between intra-cloud and extra-cloud applications.

Architecture Overview

Oracle Messaging Cloud Service architecture is highly available and fault-tolerant. It provides a secure messaging solution for applications that require reliable asynchronous communication. The applications can be within Oracle Cloud as well as outside of Oracle Cloud.
 
The following diagram presents an architectural overview of Oracle Messaging Cloud Service:

Consider a typical workflow for using the Oracle Messaging Cloud Service.

1. Creating users and assigning them access roles
2. Receiving a message from one destination on your application
3. Processing the received information locally, on the application
4. From your application, sending another message to a destination as a result of the local processing

Consider this common scenario: A client receives a message from one destination. The client does some processing on the information from the message. The client then sends a message to another destination as a return of the processing of the first message.

In this scenario what would happen if the machine where the client was doing the processing unexpectedly crashed? The second message would not be sent, but the first message had already been received. This could potentially lead to the loss of information.

Transactions allow multiple send and receive operations to be grouped together. At any point during the transaction, all previous send and receive operations within that transaction can be rolled back (that is, undone).

In the scenario above, if we started a transaction before receiving the first message, and the machine doing the processing crashed, the received message can be returned to the original destination and no information would be lost.

In this tutorial we are going to demonstrate how transactions can be used through the Messaging Service's REST API.

To make things simpler, the anti-CSRF token is disabled in the code samples provided in this tutorial. The X-OC-ID-TOKEN-STATUS header is disabled.

 First, you need to create two queues, one to receive messages from, and another to send messages to. Perform the following step to create the queues:

1. In the curl command line tool, type the following text (swapping your Oracle Cloud Messaging Service credentials) and click Enter.

We need sample messages on the first queue so that we can later receive them within a transaction.

1. Create a connection:

2. Create a session:

3. Create a producer:

4. Send two unique messages to the first queue:

5. Close the setup connection and its ephemeral resources:

Now we need to create a transacted session in which to receive and send messages. The transaction will allow us to group multiple send and receive operations into a single operation. This transaction is important to ensure that messages do not get lost, when customer applications have multiple coordinated interactions with the Oracle Messaging Cloud Service.

1. Create a new connection:
   

   curl -v -c mycookies.txt -b mycookies.txt --user "john.doe@example.com:Welcome123!" -X PUT https://messaging.us2.oraclecloud.com/messagingtrial3930-usoracletrial00484/api/v1/connections/myTransactedConnection -H "X-OC-ID-TOKEN-STATUS: disabled"

> PUT /messagingtrial3930-usoracletrial00484/api/v1/connections/myTransactedConnection HTTP/1.1
> Authorization: Basic abcdefghijklmnopqrstuvwxyz1234567890abcdefghijkl
> User-Agent: curl/7.21.4 (universal-apple-darwin11.0) libcurl/7.21.4 OpenSSL/0.9.8y zlib/1.2.5
> Host: messaging.us2.oraclecloud.com
> Accept: */*
> Cookie: JSESSIONID=YyMQTZDVXyvCZ060qlmBBYdlX2Fd5Wh02191qTpMlnTW3VxGtgTt!162217309
> X-OC-ID-TOKEN-STATUS: disabled

< HTTP/1.1 201 Created
< Date: Wed, 30 Jul 2014 14:39:20 GMT
< Server: Oracle-Application-Server-11g
< Cache-Control: no-cache;no-store;must-revalidate;max-age=0
< Location: http://messaging.us2.oraclecloud.com/messagingtrial3930-usoracletrial00484/api/v1/connections/myTransactedConnection
< Content-Length: 0
< X-Powered-By: Servlet/2.5 JSP/2.1
< Vary: Accept-Encoding
< Content-Type: text/plain
< Content-Language: en

   
2. Create a new transacted session for the newly created connection:
   curl -v -c mycookies.txt -b mycookies.txt --user "john.doe@example.com:Welcome123!" -X PUT https://messaging.us2.oraclecloud.com/messagingtrial3930-usoracletrial00484/api/v1/sessions/myTransactedSession -H "X-OC-TRANSACTED: true" -H "X-OC-CONNECTION: myTransactedConnection" -H "X-OC-ID-TOKEN-STATUS: disabled"

> PUT /messagingtrial3930-usoracletrial00484/api/v1/sessions/myTransactedSession HTTP/1.1
> Authorization: Basic abcdefghijklmnopqrstuvwxyz1234567890abcdefghijkl
> User-Agent: curl/7.21.4 (universal-apple-darwin11.0) libcurl/7.21.4 OpenSSL/0.9.8y zlib/1.2.5
> Host: messaging.us2.oraclecloud.com
> Accept: */*
> Cookie: JSESSIONID=YyMQTZDVXyvCZ060qlmBBYdlX2Fd5Wh02191qTpMlnTW3VxGtgTt!162217309
> X-OC-TRANSACTED: true
> X-OC-CONNECTION: myTransactedConnection
> X-OC-ID-TOKEN-STATUS: disabled

< HTTP/1.1 201 Created
< Date: Wed, 30 Jul 2014 14:39:29 GMT
< Server: Oracle-Application-Server-11g
< Cache-Control: no-cache;no-store;must-revalidate;max-age=0
< Location: http://messaging.us2.oraclecloud.com/messagingtrial3930-usoracletrial00484/api/v1/sessions/myTransactedSession
< Content-Length: 0
< X-Powered-By: Servlet/2.5 JSP/2.1
< Vary: Accept-Encoding
< Content-Type: text/plain
< Content-Language: en

   

Now that we have created a transacted messaging session, we need to create a consumer within that transacted messaging session to receive messages.

1. Create a consumer:

   curl -v -c mycookies.txt -b mycookies.txt --user "john.doe@example.com:Welcome123!" -X PUT https://messaging.us2.oraclecloud.com/messagingtrial3930-usoracletrial00484/api/v1/consumers/myTransactedConsumer -H "X-OC-SESSION: myTransactedSession" -H "X-OC-DESTINATION: /queues/obeFirstQueue" -H "X-OC-ID-TOKEN-STATUS: disabled"

> PUT /messagingtrial3930-usoracletrial00484/api/v1/consumers/myTransactedConsumer HTTP/1.1
> Authorization: Basic abcdefghijklmnopqrstuvwxyz1234567890abcdefghijkl
> User-Agent: curl/7.21.4 (universal-apple-darwin11.0) libcurl/7.21.4 OpenSSL/0.9.8y zlib/1.2.5
> Host: messaging.us2.oraclecloud.com
> Accept: */*
> Cookie: JSESSIONID=YyMQTZDVXyvCZ060qlmBBYdlX2Fd5Wh02191qTpMlnTW3VxGtgTt!162217309
> X-OC-SESSION: myTransactedSession
> X-OC-DESTINATION: /queues/obeFirstQueue
> X-OC-ID-TOKEN-STATUS: disabled

< HTTP/1.1 201 Created
< Date: Wed, 30 Jul 2014 14:39:39 GMT
< Server: Oracle-Application-Server-11g
< Cache-Control: no-cache;no-store;must-revalidate;max-age=0
< Location: http://messaging.us2.oraclecloud.com/messagingtrial3930-usoracletrial00484/api/v1/consumers/myTransactedConsumer
< Content-Length: 0
< X-Powered-By: Servlet/2.5 JSP/2.1
< Vary: Accept-Encoding
< Content-Type: text/plain
< Content-Language: en
   

Just as we created a consumer within our transacted messaging session to receive messages, we now need to create a producer within the transacted messaging session to send messages.

1. Create a producer:

   curl -v -c mycookies.txt -b mycookies.txt --user "john.doe@example.com:Welcome123!" -X PUT https://messaging.us2.oraclecloud.com/messagingtrial3930-usoracletrial00484/api/v1/producers/myTransactedProducer -H "X-OC-SESSION: myTransactedSession" -H "X-OC-DESTINATION: /queues/obeSecondQueue" -H "X-OC-ID-TOKEN-STATUS: disabled"

> PUT /messagingtrial3930-usoracletrial00484/api/v1/producers/myTransactedProducer HTTP/1.1
> Authorization: Basic abcdefghijklmnopqrstuvwxyz1234567890abcdefghijkl
> User-Agent: curl/7.21.4 (universal-apple-darwin11.0) libcurl/7.21.4 OpenSSL/0.9.8y zlib/1.2.5
> Host: messaging.us2.oraclecloud.com
> Accept: */*
> Cookie: JSESSIONID=YyMQTZDVXyvCZ060qlmBBYdlX2Fd5Wh02191qTpMlnTW3VxGtgTt!162217309
> X-OC-SESSION: myTransactedSession
> X-OC-DESTINATION: /queues/obeSecondQueue
> X-OC-ID-TOKEN-STATUS: disabled

< HTTP/1.1 201 Created
< Date: Wed, 30 Jul 2014 14:39:50 GMT
< Server: Oracle-Application-Server-11g
< Cache-Control: no-cache;no-store;must-revalidate;max-age=0
< Location: http://messaging.us2.oraclecloud.com/messagingtrial3930-usoracletrial00484/api/v1/producers/myTransactedProducer
< Content-Length: 0
< X-Powered-By: Servlet/2.5 JSP/2.1
< Vary: Accept-Encoding
< Content-Type: text/plain
< Content-Language: en
   

Let us receive the first message within our new messaging transaction.

1. Start the connection:

   curl -v -c mycookies.txt -b mycookies.txt --user "john.doe@example.com:Welcome123!" -X POST https://messaging.us2.oraclecloud.com/messagingtrial3930-usoracletrial00484/api/v1/connections/myTransactedConnection -H "X-OC-ACTION: start" -H "X-OC-ID-TOKEN-STATUS: disabled"

> POST /messagingtrial3930-usoracletrial00484/api/v1/connections/myTransactedConnection HTTP/1.1
> Authorization: Basic abcdefghijklmnopqrstuvwxyz1234567890abcdefghijkl
> User-Agent: curl/7.21.4 (universal-apple-darwin11.0) libcurl/7.21.4 OpenSSL/0.9.8y zlib/1.2.5
> Host: messaging.us2.oraclecloud.com
> Accept: */*
> Cookie: JSESSIONID=YyMQTZDVXyvCZ060qlmBBYdlX2Fd5Wh02191qTpMlnTW3VxGtgTt!162217309
> X-OC-ACTION: start
> X-OC-ID-TOKEN-STATUS: disabled

< HTTP/1.1 200 OK
< Date: Wed, 30 Jul 2014 14:40:00 GMT
< Server: Oracle-Application-Server-11g
< Cache-Control: no-cache;no-store;must-revalidate;max-age=0
< Location: http://messaging.us2.oraclecloud.com/messagingtrial3930-usoracletrial00484/api/v1/connections/myTransactedConnection
< Content-Length: 0
< X-Powered-By: Servlet/2.5 JSP/2.1
< Vary: Accept-Encoding
< Content-Type: text/plain
< Content-Language: en

   

2. Receive a message:

Notice that the body of the response has the string "Hello, World!". This is the body of the message we sent earlier. Now that we have the message information, our application can process it locally and then send the response to another queue. In our example we are reversing the order of the string

Hello, World! => !dlroW ,olleH


Now we need to send our locally processed information as a message to another queue.

1. Send a message through the producer:
   

   curl -v -c mycookies.txt -b mycookies.txt --user "john.doe@example.com:Welcome123!" -H "Content-Type: text/plain" -d "!dlroW ,olleH" -X POST https://messaging.us2.oraclecloud.com/messagingtrial3930-usoracletrial00484/api/v1/producers/myTransactedProducer/messages -H "X-OC-ID-TOKEN-STATUS: disabled"

> POST /messagingtrial3930-usoracletrial00484/api/v1/producers/myTransactedProducer/messages HTTP/1.1
> Authorization: Basic abcdefghijklmnopqrstuvwxyz1234567890abcdefghijkl
> User-Agent: curl/7.21.4 (universal-apple-darwin11.0) libcurl/7.21.4 OpenSSL/0.9.8y zlib/1.2.5
> Host: messaging.us2.oraclecloud.com
> Accept: */*
> Cookie: JSESSIONID=YyMQTZDVXyvCZ060qlmBBYdlX2Fd5Wh02191qTpMlnTW3VxGtgTt!162217309
> Content-Type: text/plain
> X-OC-ID-TOKEN-STATUS: disabled
> Content-Length: 13

< HTTP/1.1 201 Created
< Date: Wed, 30 Jul 2014 14:40:18 GMT
< Server: Oracle-Application-Server-11g
< Cache-Control: no-cache;no-store;must-revalidate;max-age=0
< Location: http://messaging.us2.oraclecloud.com/messagingtrial3930-usoracletrial00484/api/v1/producers/myTransactedProducer/messages
< Content-Length: 0
< X-OC-MESSAGE-ID: ID:us2oc1-mcs-wls-b-001.messaging.oc1.usdc2.oraclecloud.com-28599-1405328775777-77:2:1:1:1
< X-OC-DELIVERY-MODE: persistent
< X-OC-TIMESTAMP: 1406731227267
< X-OC-EXPIRATION: 1407940827267
< X-OC-DESTINATION: /queues/obeSecondQueue
< X-OC-PRIORITY: 4
< X-Powered-By: Servlet/2.5 JSP/2.1
< Vary: Accept-Encoding
< Content-Type: text/plain
< Content-Language: en
   

So far, we have done the following:

1. Received a message from one queue
2. Processed the content of the message we received locally
3. Sent the processed results to another queue

At this point, however, steps 1 and 3 are only provisional since we are operating within a transacted session. To make these steps permanent we need to commit the transacted session.

1. Commit the transaction:

   curl -v -c mycookies.txt -b mycookies.txt --user "john.doe@example.com:Welcome123!" -X POST https://messaging.us2.oraclecloud.com/messagingtrial3930-usoracletrial00484/api/v1/sessions/myTransactedSession/state -H "X-OC-ACTION: commit" -H "X-OC-ID-TOKEN-STATUS: disabled"

> POST /messagingtrial3930-usoracletrial00484/api/v1/sessions/myTransactedSession/state HTTP/1.1
> Authorization: Basic abcdefghijklmnopqrstuvwxyz1234567890abcdefghijkl
> User-Agent: curl/7.21.4 (universal-apple-darwin11.0) libcurl/7.21.4 OpenSSL/0.9.8y zlib/1.2.5
> Host: messaging.us2.oraclecloud.com
> Accept: */*
> Cookie: JSESSIONID=YyMQTZDVXyvCZ060qlmBBYdlX2Fd5Wh02191qTpMlnTW3VxGtgTt!162217309
> X-OC-ACTION: commit
> X-OC-ID-TOKEN-STATUS: disabled

< HTTP/1.1 200 OK
< Date: Wed, 30 Jul 2014 14:40:37 GMT
< Server: Oracle-Application-Server-11g
< Cache-Control: no-cache;no-store;must-revalidate;max-age=0
< Location: http://messaging.us2.oraclecloud.com/messagingtrial3930-usoracletrial00484/api/v1/sessions/myTransactedSession/state
< Content-Length: 0
< X-Powered-By: Servlet/2.5 JSP/2.1
< Vary: Accept-Encoding
< Content-Type: text/plain
< Content-Language: en
   
   Our send and receive are now permanent.
   Let us now look at what would happen if a failure occurred after we received the message during local processing.
   
   

Receive another message from the first queue. Note the unique ID of the message in the X-OC-MESSAGE-ID HTTP Response header.

1. Recieve a message:

   curl -v -c mycookies.txt -b mycookies.txt --user "john.doe@example.com:Welcome123!" -X POST https://messaging.us2.oraclecloud.com/messagingtrial3930-usoracletrial00484/api/v1/consumers/myTransactedConsumer/messages -H "X-OC-TIMEOUT: 1000" -H "X-OC-ID-TOKEN-STATUS: disabled"

> POST /messagingtrial3930-usoracletrial00484/api/v1/consumers/myTransactedConsumer/messages HTTP/1.1
> Authorization: Basic abcdefghijklmnopqrstuvwxyz1234567890abcdefghijkl
> User-Agent: curl/7.21.4 (universal-apple-darwin11.0) libcurl/7.21.4 OpenSSL/0.9.8y zlib/1.2.5
> Host: messaging.us2.oraclecloud.com
> Accept: */*
> Cookie: JSESSIONID=YyMQTZDVXyvCZ060qlmBBYdlX2Fd5Wh02191qTpMlnTW3VxGtgTt!162217309
> X-OC-TIMEOUT: 1000
> X-OC-ID-TOKEN-STATUS: disabled

< HTTP/1.1 200 OK
< Date: Wed, 30 Jul 2014 14:40:48 GMT
< Server: Oracle-Application-Server-11g
< Cache-Control: no-cache;no-store;must-revalidate;max-age=0
< Location: http://messaging.us2.oraclecloud.com/messagingtrial3930-usoracletrial00484/api/v1/consumers/myTransactedConsumer/messages
< X-OC-PRIORITY: 4
< X-OC-DELIVERY-MODE: persistent
< X-OC-TIMESTAMP: 1406731135790
< X-OC-EXPIRATION: 1407940735790
< X-OC-MESSAGE-TYPE: HTTP
< X-OC-DESTINATION: /queues/obeFirstQueue
< X-OC-MESSAGE-ID: ID:us2oc1-mcs-wls-b-001.messaging.oc1.usdc2.oraclecloud.com-28599-1405328775777-77:1:1:1:2
< X-Powered-By: Servlet/2.5 JSP/2.1
< X-OC-REDELIVERED: false
< Vary: Accept-Encoding
< Transfer-Encoding: chunked
< Content-Type: text/plain
< Content-Language: en

Foo Bar Baz
   

Now we must simulate a complete failure of the client machine that is receiving and sending messages.

If we weren't operating within a transacted messaging session, this would be a problem because our application requires every received message to be processed and then have the processed results sent to another queue.
If we weren't operating within a transacted messaging session, the received message would have been permanently removed from the first queue during the receive operation and the content of that message would be lost when the client machine crashed.

Since we are using a transacted messaging session, the message that we received in the previous step will be returned to the queue when the connection of the messaging session expires.
 
To simulate this in the tutorial, you have two options:

1. Wait for the connection to expire. The connection will expire when its messaging context's Maximum Inactivity Interval (MII) passes (by default, 5 minutes).
2. Explicitly delete the session.

Both options will have the same outcome. If you choose option #2, delete the connection:

1. Delete the connection:

   curl -v -c mycookies.txt -b mycookies.txt --user "john.doe@example.com:Welcome123!" -X DELETE https://messaging.us2.oraclecloud.com/messagingtrial3930-usoracletrial00484/api/v1/connections/myTransactedConnection -H "X-OC-ID-TOKEN-STATUS: disabled"

> DELETE /messagingtrial3930-usoracletrial00484/api/v1/connections/myTransactedConnection HTTP/1.1
> Authorization: Basic abcdefghijklmnopqrstuvwxyz1234567890abcdefghijkl
> User-Agent: curl/7.21.4 (universal-apple-darwin11.0) libcurl/7.21.4 OpenSSL/0.9.8y zlib/1.2.5
> Host: messaging.us2.oraclecloud.com
> Accept: */*
> Cookie: JSESSIONID=YyMQTZDVXyvCZ060qlmBBYdlX2Fd5Wh02191qTpMlnTW3VxGtgTt!162217309
> X-OC-ID-TOKEN-STATUS: disabled

< HTTP/1.1 204 No Content
< Date: Wed, 30 Jul 2014 14:40:58 GMT
< Server: Oracle-Application-Server-11g
< Cache-Control: no-cache;no-store;must-revalidate;max-age=0
< Location: http://messaging.us2.oraclecloud.com/messagingtrial3930-usoracletrial00484/api/v1/connections/myTransactedConnection
< Content-Length: 0
< X-Powered-By: Servlet/2.5 JSP/2.1
< Vary: Accept-Encoding
< Content-Type: text/plain
< Content-Language: en
   

When a connection is closed or expires, all of its dependent server-side objects (Sessions, Consumers, Producers) also close or expire. To continue, we need to recreate them.

1. Create a new connection:

   curl -v -c mycookies.txt -b mycookies.txt --user "john.doe@example.com:Welcome123!" -X PUT https://messaging.us2.oraclecloud.com/messagingtrial3930-usoracletrial00484/api/v1/connections/myTransactedConnection -H "X-OC-ID-TOKEN-STATUS: disabled"

> PUT /messagingtrial3930-usoracletrial00484/api/v1/connections/myTransactedConnection HTTP/1.1
> Authorization: Basic abcdefghijklmnopqrstuvwxyz1234567890abcdefghijkl
> User-Agent: curl/7.21.4 (universal-apple-darwin11.0) libcurl/7.21.4 OpenSSL/0.9.8y zlib/1.2.5
> Host: messaging.us2.oraclecloud.com
> Accept: */*
> Cookie: JSESSIONID=YyMQTZDVXyvCZ060qlmBBYdlX2Fd5Wh02191qTpMlnTW3VxGtgTt!162217309
> X-OC-ID-TOKEN-STATUS: disabled

< HTTP/1.1 201 Created
< Date: Wed, 30 Jul 2014 14:41:09 GMT
< Server: Oracle-Application-Server-11g
< Cache-Control: no-cache;no-store;must-revalidate;max-age=0
< Location: http://messaging.us2.oraclecloud.com/messagingtrial3930-usoracletrial00484/api/v1/connections/myTransactedConnection
< Content-Length: 0
< X-Powered-By: Servlet/2.5 JSP/2.1
< Vary: Accept-Encoding
< Content-Type: text/plain
< Content-Language: en

   

2. Create a transacted session:
   

   curl -v -c mycookies.txt -b mycookies.txt --user "john.doe@example.com:Welcome123!" -X PUT https://messaging.us2.oraclecloud.com/messagingtrial3930-usoracletrial00484/api/v1/sessions/myTransactedSession -H "X-OC-TRANSACTED: true" -H "X-OC-CONNECTION: myTransactedConnection" -H "X-OC-ID-TOKEN-STATUS: disabled"

> PUT /messagingtrial3930-usoracletrial00484/api/v1/sessions/myTransactedSession HTTP/1.1
> Authorization: Basic abcdefghijklmnopqrstuvwxyz1234567890abcdefghijkl
> User-Agent: curl/7.21.4 (universal-apple-darwin11.0) libcurl/7.21.4 OpenSSL/0.9.8y zlib/1.2.5
> Host: messaging.us2.oraclecloud.com
> Accept: */*
> Cookie: JSESSIONID=YyMQTZDVXyvCZ060qlmBBYdlX2Fd5Wh02191qTpMlnTW3VxGtgTt!162217309
> X-OC-TRANSACTED: true
> X-OC-CONNECTION: myTransactedConnection
> X-OC-ID-TOKEN-STATUS: disabled

< HTTP/1.1 201 Created
< Date: Wed, 30 Jul 2014 14:41:16 GMT
< Server: Oracle-Application-Server-11g
< Cache-Control: no-cache;no-store;must-revalidate;max-age=0
< Location: http://messaging.us2.oraclecloud.com/messagingtrial3930-usoracletrial00484/api/v1/sessions/myTransactedSession
< Content-Length: 0
< X-Powered-By: Servlet/2.5 JSP/2.1
< Vary: Accept-Encoding
< Content-Type: text/plain
< Content-Language: en
   

Then create a new consumer on the new transacted messaging session.

1. Create a consumer:

   curl -v -c mycookies.txt -b mycookies.txt --user "john.doe@example.com:Welcome123!" -X PUT https://messaging.us2.oraclecloud.com/messagingtrial3930-usoracletrial00484/api/v1/consumers/myTransactedConsumer -H "X-OC-DESTINATION: /queues/obeFirstQueue" -H "X-OC-SESSION: myTransactedSession" -H "X-OC-ID-TOKEN-STATUS: disabled"

> PUT /messagingtrial3930-usoracletrial00484/api/v1/consumers/myTransactedConsumer HTTP/1.1
> Authorization: Basic abcdefghijklmnopqrstuvwxyz1234567890abcdefghijkl
> User-Agent: curl/7.21.4 (universal-apple-darwin11.0) libcurl/7.21.4 OpenSSL/0.9.8y zlib/1.2.5
> Host: messaging.us2.oraclecloud.com
> Accept: */*
> Cookie: JSESSIONID=YyMQTZDVXyvCZ060qlmBBYdlX2Fd5Wh02191qTpMlnTW3VxGtgTt!162217309
> X-OC-DESTINATION: /queues/obeFirstQueue
> X-OC-SESSION: myTransactedSession
> X-OC-ID-TOKEN-STATUS: disabled

< HTTP/1.1 201 Created
< Date: Wed, 30 Jul 2014 14:41:24 GMT
< Server: Oracle-Application-Server-11g
< Cache-Control: no-cache;no-store;must-revalidate;max-age=0
< Location: http://messaging.us2.oraclecloud.com/messagingtrial3930-usoracletrial00484/api/v1/consumers/myTransactedConsumer
< Content-Length: 0
< X-Powered-By: Servlet/2.5 JSP/2.1
< Vary: Accept-Encoding
< Content-Type: text/plain
< Content-Language: en
   

Then create a new producer in the new transacted messaging session.

1. Create a producer:

   curl -v -c mycookies.txt -b mycookies.txt --user "john.doe@example.com:Welcome123!" -X PUT https://messaging.us2.oraclecloud.com/messagingtrial3930-usoracletrial00484/api/v1/producers/myTransactedProducer -H "X-OC-SESSION: myTransactedSession" -H "X-OC-DESTINATION: /queues/obeSecondQueue" -H "X-OC-ID-TOKEN-STATUS: disabled"

> PUT /messagingtrial3930-usoracletrial00484/api/v1/producers/myTransactedProducer HTTP/1.1
> Authorization: Basic abcdefghijklmnopqrstuvwxyz1234567890abcdefghijkl
> User-Agent: curl/7.21.4 (universal-apple-darwin11.0) libcurl/7.21.4 OpenSSL/0.9.8y zlib/1.2.5
> Host: messaging.us2.oraclecloud.com
> Accept: */*
> Cookie: JSESSIONID=YyMQTZDVXyvCZ060qlmBBYdlX2Fd5Wh02191qTpMlnTW3VxGtgTt!162217309
> X-OC-SESSION: myTransactedSession
> X-OC-DESTINATION: /queues/obeSecondQueue
> X-OC-ID-TOKEN-STATUS: disabled

< HTTP/1.1 201 Created
< Date: Wed, 30 Jul 2014 14:41:32 GMT
< Server: Oracle-Application-Server-11g
< Cache-Control: no-cache;no-store;must-revalidate;max-age=0
< Location: http://messaging.us2.oraclecloud.com/messagingtrial3930-usoracletrial00484/api/v1/producers/myTransactedProducer
< Content-Length: 0
< X-Powered-By: Servlet/2.5 JSP/2.1
< Vary: Accept-Encoding
< Content-Type: text/plain
< Content-Language: en
   

Receive another message from the first queue via the new consumer.

1. Start the connection:

   curl -v -c mycookies.txt -b mycookies.txt --user "john.doe@example.com:Welcome123!" -X POST https://messaging.us2.oraclecloud.com/messagingtrial3930-usoracletrial00484/api/v1/connections/myTransactedConnection -H "X-OC-ACTION: start" -H "X-OC-ID-TOKEN-STATUS: disabled"

> POST /messagingtrial3930-usoracletrial00484/api/v1/connections/myTransactedConnection HTTP/1.1
> Authorization: Basic abcdefghijklmnopqrstuvwxyz1234567890abcdefghijkl
> User-Agent: curl/7.21.4 (universal-apple-darwin11.0) libcurl/7.21.4 OpenSSL/0.9.8y zlib/1.2.5
> Host: messaging.us2.oraclecloud.com
> Accept: */*
> Cookie: JSESSIONID=YyMQTZDVXyvCZ060qlmBBYdlX2Fd5Wh02191qTpMlnTW3VxGtgTt!162217309
> X-OC-ACTION: start
> X-OC-ID-TOKEN-STATUS: disabled

< HTTP/1.1 200 OK
< Date: Wed, 30 Jul 2014 14:41:41 GMT
< Server: Oracle-Application-Server-11g
< Cache-Control: no-cache;no-store;must-revalidate;max-age=0
< Location: http://messaging.us2.oraclecloud.com/messagingtrial3930-usoracletrial00484/api/v1/connections/myTransactedConnection
< Content-Length: 0
< X-Powered-By: Servlet/2.5 JSP/2.1
< Vary: Accept-Encoding
< Content-Type: text/plain
< Content-Language: en

   

2. Recieve a message from the consumer:
   

   curl -v -c mycookies.txt -b mycookies.txt --user "john.doe@example.com:Welcome123!" -X POST https://messaging.us2.oraclecloud.com/messagingtrial3930-usoracletrial00484/api/v1/consumers/myTransactedConsumer/messages -H "X-OC-TIMEOUT: 1000" -H "X-OC-ID-TOKEN-STATUS: disabled"

> POST /messagingtrial3930-usoracletrial00484/api/v1/consumers/myTransactedConsumer/messages HTTP/1.1
> Authorization: Basic abcdefghijklmnopqrstuvwxyz1234567890abcdefghijkl
> User-Agent: curl/7.21.4 (universal-apple-darwin11.0) libcurl/7.21.4 OpenSSL/0.9.8y zlib/1.2.5
> Host: messaging.us2.oraclecloud.com
> Accept: */*
> Cookie: JSESSIONID=YyMQTZDVXyvCZ060qlmBBYdlX2Fd5Wh02191qTpMlnTW3VxGtgTt!162217309
> X-OC-TIMEOUT: 1000
> X-OC-ID-TOKEN-STATUS: disabled

< HTTP/1.1 200 OK
< Date: Wed, 30 Jul 2014 14:42:02 GMT
< Server: Oracle-Application-Server-11g
< Cache-Control: no-cache;no-store;must-revalidate;max-age=0
< Location: http://messaging.us2.oraclecloud.com/messagingtrial3930-usoracletrial00484/api/v1/consumers/myTransactedConsumer/messages
< X-OC-MESSAGE-TYPE: HTTP
< X-OC-PRIORITY: 4
< X-OC-DELIVERY-MODE: persistent
< X-OC-TIMESTAMP: 1406731135790
< X-OC-EXPIRATION: 1407940735790
< X-OC-GENERAL-INT-PROPERTY-4A4D535844656C6976657279436F756E74: 32
< X-OC-DESTINATION: /queues/obeFirstQueue
< X-OC-MESSAGE-ID: ID:us2oc1-mcs-wls-b-001.messaging.oc1.usdc2.oraclecloud.com-28599-1405328775777-77:1:1:1:2
< X-Powered-By: Servlet/2.5 JSP/2.1
< X-OC-REDELIVERED: true
< Vary: Accept-Encoding
< Transfer-Encoding: chunked
< Content-Type: text/plain
< Content-Language: en

Foo Bar Baz

   

   Note the value of the X-OC-MESSAGE-ID HTTP Response header. It should be the identical value from the receive operation before we simulated the crash of the client machine.
   
   Also note the value X-OC-REDELIVERED is true. This indicates to clients that the message was delivered at least once before, but was sent back to the destination because the messaging session it was delivered through did not succeed.
   

Again, to simulate local processing, we reverse the characters of the received message's body. Then send the processed results to the other queue.

1. Send a message to the producer:

   curl -v -c mycookies.txt -b mycookies.txt --user "john.doe@example.com:Welcome123!" -H "Content-Type: text/plain" -d "zaB raB ooF" -X POST https://messaging.us2.oraclecloud.com/messagingtrial3930-usoracletrial00484/api/v1/producers/myTransactedProducer/messages -H "X-OC-ID-TOKEN-STATUS: disabled"

> POST /messagingtrial3930-usoracletrial00484/api/v1/producers/myTransactedProducer/messages HTTP/1.1
> Authorization: Basic abcdefghijklmnopqrstuvwxyz1234567890abcdefghijkl
> User-Agent: curl/7.21.4 (universal-apple-darwin11.0) libcurl/7.21.4 OpenSSL/0.9.8y zlib/1.2.5
> Host: messaging.us2.oraclecloud.com
> Accept: */*
> Cookie: JSESSIONID=YyMQTZDVXyvCZ060qlmBBYdlX2Fd5Wh02191qTpMlnTW3VxGtgTt!162217309
> Content-Type: text/plain
> X-OC-ID-TOKEN-STATUS: disabled
> Content-Length: 11

< HTTP/1.1 201 Created
< Date: Wed, 30 Jul 2014 14:42:15 GMT
< Server: Oracle-Application-Server-11g
< Cache-Control: no-cache;no-store;must-revalidate;max-age=0
< Location: http://messaging.us2.oraclecloud.com/messagingtrial3930-usoracletrial00484/api/v1/producers/myTransactedProducer/messages
< Content-Length: 0
< X-OC-MESSAGE-ID: ID:us2oc1-mcs-wls-b-001.messaging.oc1.usdc2.oraclecloud.com-28599-1405328775777-77:3:1:1:1
< X-OC-DELIVERY-MODE: persistent
< X-OC-TIMESTAMP: 1406731344552
< X-OC-EXPIRATION: 1407940944552
< X-OC-DESTINATION: /queues/obeSecondQueue
< X-OC-PRIORITY: 4
< X-Powered-By: Servlet/2.5 JSP/2.1
< Vary: Accept-Encoding
< Content-Type: text/plain
< Content-Language: en
   

Now commit the transacted messaging session to make the previous send and receive operations permanent.

1. Commit the transacted session:

   curl -v -c mycookies.txt -b mycookies.txt --user "john.doe@example.com:Welcome123!" -X POST https://messaging.us2.oraclecloud.com/messagingtrial3930-usoracletrial00484/api/v1/sessions/myTransactedSession/state -H "X-OC-ACTION: commit" -H "X-OC-ID-TOKEN-STATUS: disabled"

> POST /messagingtrial3930-usoracletrial00484/api/v1/sessions/myTransactedSession/state HTTP/1.1
> Authorization: Basic abcdefghijklmnopqrstuvwxyz1234567890abcdefghijkl
> User-Agent: curl/7.21.4 (universal-apple-darwin11.0) libcurl/7.21.4 OpenSSL/0.9.8y zlib/1.2.5
> Host: messaging.us2.oraclecloud.com
> Accept: */*
> Cookie: JSESSIONID=YyMQTZDVXyvCZ060qlmBBYdlX2Fd5Wh02191qTpMlnTW3VxGtgTt!162217309
> X-OC-ACTION: commit
> X-OC-ID-TOKEN-STATUS: disabled

< HTTP/1.1 200 OK
< Date: Wed, 30 Jul 2014 14:42:24 GMT
< Server: Oracle-Application-Server-11g
< Cache-Control: no-cache;no-store;must-revalidate;max-age=0
< Location: http://messaging.us2.oraclecloud.com/messagingtrial3930-usoracletrial00484/api/v1/sessions/myTransactedSession/state
< Content-Length: 0
< X-Powered-By: Servlet/2.5 JSP/2.1
< Vary: Accept-Encoding
< Content-Type: text/plain
< Content-Language: en
   

In this tutorial, you learned to:

• Use the cURL command line tool to interact with the Oracle Messaging Cloud Service's REST API
• Perform the following operations against the Oracle Messaging Cloud Service's REST API
• Create a queue
• Create a connection
• Start a connection
• Create a transacted messaging session
  
• Create a consumer and a producer for the messaging session
• Send messages to the queue
  
• Receive a message from the queue
  
• Verify messages by comparing their X-OC-MESSAGE-ID HTTP Response header values
• Determine if a message has been delivered at least once before by evaluating the X-OC-REDELIVERED HTTP Response header
  
• Commit a transacted messaging session
  
• Delete a connection to simulate a crashed client

Resources

• To learn more about Oracle Messaging Cloud Service, visit the Oracle Cloud Messaging Service website.
• For training on the Oracle Cloud platform-as-a-service (PaaS) Services, visit the Oracle Learning Library.

Credits

• Lead UA Developers: Richard Green, Nisha Singh
• Key Contributors: Rehan Iftikhar, Mark Moussa, Nancy Greenberg, Shilpa Murthy, Gururaj BS