Skip navigation
  • Von: Phil Wilkins
  • 10/15/2018

Introduction to Oracle Messaging Cloud Service

Messaging has been a long-standing work horse for system to system integration. It is undoubtedly the uncool kid in the playground of integration technologies, and for a long time has been overshadowed by first SOAP/WSDL and then REST based web services. Yet in creating Oracle Messaging Cloud Service (OMCS ), Oracle have given our messaging work horse some new features that means our uncool kid can now throw some pretty cool moves in the era of the cloud. 

This article first appeared in the bimonthly ORAWORLD e-magazine, an EOUC publication with exciting stories from the Oracle world, technological background articles and insights into other user groups worldwide.

 

There are many factors that contribute to messaging being perceived as the uncool kid in the playground of integration technologies, but I would suggest that the primary factors are …

  • in part because it 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,
  • because each messaging server is different, so you need to deploy a java library from the relevant vendor to see the JMS API standard to be realised,
  • bridging between different JMS implementations can be a bit messy,
  • and JMS doesn’t typically play too well with web clients.

These points may all contribute to why OMCS barely gets mentioned compared to ICS, PCS and other Oracle PaaS offerings. Yet in creating OMCS, Oracle have given our messaging work horse some pretty cool new features. In these articles, we are going to look at OMCS web API that sits over that messaging engine and look at the cool moves OMCS can throw that gives Messaging a 21st century shine.

The REST API

It would be easy to just say OMCS is JMS with a REST skin, and whilst this may be crudely correct, it really underplays some of its 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 the diagram shows.

As the API is REST based it becomes very easy to use command line tools such 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, but also hooking OMCS to your monitoring tool of preference and using scripts to gather operational state information using cURL or even the ability to hook REST calls into the monitoring tool.

The REST interface documentation for OMCS is among the best today for the new Oracle iPaaS solutions, although there are still some gaps, so we’ll walk through a series of commands to illustrate the ease by which we can perform messaging tasks (as this also helps to show how easy it would be to engage OMCS in lightweight environments such as front-end clients or 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.

Getting a Connection

So, the cURL command issued first is to establish a connection. As you can see in this image, the command starts with -u followed by the <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. The switching off CSRF can be applied as we are driving communication from a single location and don’t need the overhead of establishing addition token details and token validation. The parameters -c and -b both point to a cookie file. This is needed as 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 therefore fail. The last parameter we use throughout the examples is –write-out %{http_code}. This ensures that the HTTP response codes and associated messages are displayed. That is important as some of the REST interfaces only return 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 being included. In the remaining part of the URI we are creating (hence PUT) a connection we can subsequently refer to as myConnection and the parameter tell OMCS to start the connection immediately. You can see the response provided includes the code 201 – this is the http_code we mentioned. The 2xx codes all relate to successful actions and 201 specifically means created.

Establishing a Session

With that we now have a connection established, so the next step is to create the session object, which uses the following REST call, see image.

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.

Create a Queue

We have a response code that points to the successful queue creation. But we can look to 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 screenshot.

With 3 lines of cURL script we have connected and created a queue, and a fourth line to check what queues exist. OMCS isn’t restricted to just queues but can also handle topics both temporary and durable.

Adding Messages

With the queue established it is simply an extra REST call to define a message producer (which we’ve called MyProducer) and attached the producer to a specific queue using the session and destination parameters (the 1st 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 a HTTP POST. This does bring us to one of the constraints of OMCS, which is that the message size is limited to 512kb. But , that  should not be a problem, even the large fully populated canonical XML schemas used by AIA, OAGIS, ARTs etc. will struggle to push that limit. However, if you’re trying to pass media content around this is going to be limiting.  But I would suggest in that kind of situation, media would be going directly to storage and messages are communicated pointing to file location.

 

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, then you get an empty message body.

Queue Consumption

We left the last part having populated a queue. Let’s continue forward by instantiating a consumer. This works 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 in the parameters. See image.

With the consumer, named q1Consumer (the 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. See image.

Each response returns the message in the body of the response. Note that the HTTP response code comes immediately after the output of the message content as there is no line break between the response output and cURL instruction to output the HTTP response code.

Game Changer – Push Listeners

Whilst this has illustrated that working with the messaging server has been very easy with the REST interface, the clever feature of OMCS, is the ability to define listeners that will receive messages as REST end points. This kind of listener is known as a Push Listener as OMCS actively calls the named REST endpoint. This means that we can connect a legacy application using JMS with a contemporary REST web service.

With the push listener framework comes a level of extra security (we will talk about that in a moment). As with posting the message content, providing the message body that provides the configuration information for the push listener is most easily provided by giving cURL a file. The following is a simple example where we are defining a listener called myListener which will be watching for messages on the myFirstQueue. Once received it then invokes a web target identified by the URL and the HTTP method to be used (a choice of PUT and POST is available):

<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 are not defining any error actions if the REST service call fails. If we connect to a topic, then more information needs to be provided relating to whether the connection is durable etc.

Proving the Push Listener

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 client is a legitimate client. This is done by the first call to the REST URI simply contains a header attributes (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 cannot be identified as being the source of a denial of service attack, as the receiver needs to actively confirm the challenge. Let’s look at the cURL call to establish the message push listener in figure 8.

For the logic to handle the security challenge described, we have made use of the trial version of the webscript.io service which allows us to easily define a REST endpoint and using the service’s scripting language (which looks a lot like JavaScript, but is based on LUA). The script looks like 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.  Whilst 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 can be viewed in Webscript and is purely the confirmation call with the verification and challenge as in figure 10.

The response we produced is, to simply include into the body the challenge, as shown in figure 11.

After this call the REST service call is for the messages we send, as shown in figure 12.

Conclusion

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.