Introduction to Oracle Messaging Cloud Service

Messaging has been a long-standing workhorse for system to system integration. The uncool kid on the integration technologies playground, messaging has been overshadowed, first by SOAP/WSDL and then by REST-based web services. A variety of factors contribute to this situation:

• Messaging doesn't naturally use network ports that are typically open already (i.e., those for web traffic), necessitating persuading security and network people to open up ports, etc., the moment traffic needs to cross security boundaries.
• Each messaging server is different, so you need to deploy a Java library from the relevant vendor to see the JMS API standard be realized.
• Bridging between different JMS implementations can be messy.
• JMS doesn't typically play well with web clients.

These points may all contribute to why Oracle Messaging Cloud Service (OMCS) barely gets mentioned, as compared to Integration Cloud Service, Process Cloud Service, and other Oracle PaaS offerings. Yet in creating OMCS, Oracle has given our messaging workhorse some new features that let that uncool kid throw some pretty cool moves in the era of the cloud. This article will look at the OMCS web API that sits over that messaging engine, and will also look at the cool moves OMCS can throw that give messaging a 21st century shine.

It would be easy to just say OMCS is JMS with a REST skin, and while this maybe crudely correct, it really underplays some of the service's strengths. But let's start with that new REST skin, as it alone offers some great enablers.

The REST API largely mirrors the JMS life cycle in terms of the sequence of steps for transmitting or receiving a message, as illustrated in Figure 1.

Figure 1

As the API is REST-based, it becomes very easy to use command line tools such as cURL to interact with the messaging platform for a range of different tasks, from creating test scripts to push or pull test data through an integration or even an end-to-end process. You can also hook OMCS to your monitoring tool of preference and use scripts to gather operational state information using cURL, or even hook REST calls into the monitoring tool.

The REST interface documentation for OMCS is among the best today for the new Oracle iPaaS solutions. There are still some gaps, however, so we'll walk through a series of commands to illustrate the ease with which we can perform messaging tasks. (This will also help to show how easy it would be to engage OMCS in lightweight environments such as front end clients, or to provide an effective communication backbone to microservices).

For reasons of security we have blurred out credentials and information that would make a server uniquely identifiable.

Figure 2

The cURL command issued first is to establish a connection. As you can see, the command starts with -u followed by <username>:<password>. We then provide an HTTP header attribute for X-OC-ID-TOKEN-STATUS, which disables the Cross-Site Request Forgery (CSRF) attack mitigation. Switching off CSRF can be applied because we are driving communication from a single location and don't need the overhead of establishing additional token details and token validation. The parameters  -c and -b both point to a cookie file, required because the messaging session information is tied to the HTTP(S) session. Without the cookie, the next REST call would not be linked to our connection and would therefore fail. The last parameter we use throughout the examples is -write-out %{http_code}, which ensures that the HTTP response codes and associated messages are displayed. This is important because some of the REST interfaces return only an HTTP(S) response code. These parameters are consistently used throughout all the calls we make.

The next part is the URI to invoke. The URI string up to the v1 will always remain the same for your calls with the region and domain name included. In the remaining part of the URI we are creating (hence PUT) a connection we subsequently refer to as myConnection. The parameter tells OMCS to start the connection immediately. As you can see, the response includes the code 20; this is the previously mentioned http_code. The 2xx codes all relate to successful actions, and 201 specifically means "created."

We have now established a connection, so the next step is to create the session object, which uses the following REST call:

Figure 3

As you can see, this time the URI path goes to sessions, and identifies mySession with a parameter naming the connection to be used. We then see another 201 response, indicating that the session has been created successfully.

With a session established, we can now create a queue with the following command:

Figure 4

We have a response code that points to the successful queue creation, and we can see all the queues that are available. Following the design principles of REST, performing a GET operation on queues should provide information on all queuesÑwhich is exactly what we have, as a result of the second cURL statement in the screen shot.

So, through 3 lines of cURL scripting we have connected and created a queue, with a fourth line to check what queues exist. OMCS isn't restricted to queues, but can also handle topics both temporary and durable.

With the queue established, it is simply an extra REST call to define a message producer (which we've called MyProducer), attach this producer to a specific queue using the session and destination parameters (the first call in the example below), and then to start adding messages onto the queue via the producer. For ease of readability, with cURL we have done this by telling cURL that the REST body is the contents of a file -T <filename>. In fact, for this little demo we did that with three simple but different payloads, as shown below. As adding messages is considered an amendment to the producer, you can see the call is an HTTP POST. This does bring us to one of the constraints of OMCS: the message size is limited to 512kb. This should not be a problem, as even the large, fully populated canonical XML schemas used by AIA, OAGIS, ARTs, etc., will struggle to push that limit. But if you're trying to pass media content around, this is going to be limiting. In that kind of situation, I suggest that media go directly to storage and messages be communicated pointing to file location.

Figure 5

We could browse through the queue if we wanted, which acts very much like moving a cursor over a database, returning the next message each time you call on the browse, and returning HTTP 200. If you reach the end of the queue, you get an empty message body.

Rather than browse, let's consume the messages. This requires a consumer to be instantiated, pretty much in the same way as the producer, using the parameters to identify the destination to consume from and the session to link to.

Figure 6

With the consumer, named q1Consumer (name is the last part of the URI as before). If you wanted, as with JMS it is possible to apply filters to the consumer, but here we're just taking messages with any header attribute filtering. We can then use the consumer to retrieve the messages. Note that with each call, we provide a timeout of 1 second (1000 milliseconds) as you don't want to get locked up waiting for a response.

  <listener>
    <version>1.0</version>
    <name>myListener</name>
    <source>
      <type>queue</type>
      <name>myFirstQueue</name>
    </source>
    <target>
      <uri>http://targetURL/OMCS</uri>
      <method>PUT</method>
    </target>
  </listener> 

This example is very simple as we aren't defining any error actions if the REST service call fails, failure behaviour actions, etc. If we connect to a topic, more information must be provided relating to whether the connection is durable, etc.

When creating a push listener, some additional information needs to be provided as OMCS implements a simple verification mechanism to confirm the REST service is expecting the calls, and that the client is a legitimate client. This is done by the first call to the REST URI, which simply contains a header attribute (X-OC-MPL-CHALLENGE) and (optionally) an additional parameter in the call to establish the listener, which is then passed as an additional header value called X-OC-MPL-VERIFICATION.  On the first REST call the response must contain in the body the value provided by X-OC-MPL-CHALLENGE. This verification step exists so that an Oracle service can't be identified as the source of a denial of service attack, as the receiver must actively confirm the challenge. Let's look at the cURL call to establish the message push listener.

Figure 8

To release the logic to handle the security challenge described, we have used the trial version of the webscript.io service, which allows us to easily define a REST endpoint and used the service's scripting language (which looks a lot like JavaScript, but is based on LUA) to create the response. Let's look at the script:

Figure 9

Note that if we called the Webscript from cURL directly it receives the header attribute as provided (in our case all capitals), but when sent through OMCS it is received by Webscript in camel case. While we could do some fancy header attribute string manipulation to simplify the condition, we have elected to just check for both formats. As you can see, when the challenge header attribute is identified, it is returned (which forms the response body). Without returning anything, we default to returning an empty response with an HTTP code of 200.

The initial call that can be viewed in Webscript is purely the confirmation call with the verification and challenge as follows:

Figure 10

The response we produced is to simply include the challenge into the body, as shown next:

Figure 11

After this call, the REST service call is for the messages we send, as shown:

Figure 12

As you can see, establishing the push listener is very simple. There is a little bit of work to address the challenge mechanism, but it is easy to do. In the real world you might look to an API Gateway or perhaps realise a simple proxy with something like Container Cloud Service to help handle the challenge.

As previously mentioned, we can be far more sophisticated with the configuration. But OMCS provides a great platform to bridge messaging and web-based integration solutions, particularly when a hybrid or cloud of clouds environment might exist.

About the Author

Oracle ACE Associate Phil Wilkins is a Senior Consultant at Capgemini, where he iPaaS, middleware and Oracle technologies. He is co-author of Implementing Oracle Integration Cloud Service (2017, Packt) and frequently contributes content to OTN, UKOUG Oracle Scene, and other publications.

This article represents the expertise, findings, and opinion of the author. It has been published by Oracle in this space as part of a larger effort to encourage the exchange of such information within this Community, and to promote evaluation and commentary by peers. This article has not been reviewed by the relevant Oracle product team for compliance with Oracle's standards and practices, and its publication should not be interpreted as an endorsement by Oracle of the statements expressed therein.