Learner Series: Build/Consume HTTP REST Services in SOA 11g (with example)

Today REST (Representational State Transfer) has become a norm for building services on the web. REST brings along its own merits & demerits - choice of REST vs SOAP/WSDL, when and where is an architectural decision. So, how does Oracle SOA BPEL support HTTP based RESTful web services.

For all HTTP based interactions, Oracle SOA 11g provides an out-of-box HTTP Binding adapter.

This post will illustrate the following;

a) Expose a SOA 11g BPEL process as a HTTP REST service
b) Consume/Invoke a HTTP REST service from a SOA 11g BPEL process [We will consume service that we will build as part of (a)]

As part of this exercise, we will build a REST service that will take customer name & id as input and greets the customer.

Before dunking into building the SOA composites, let's quickly take a look at the XML schema that will form the REST service contract.

Exposing SOA 11g BPEL Process as HTTP REST service:

Step 1: Create a SOA Project with empty composite and name it "HttpGetRestService"

Step 2: Drag and Drop a HTTP Binding adapter on the "Exposed Services" swimlane in the SOA composite (SCA)

Step 3: Choose Next in the Welcome page of the wizard

Step 4: Enter service name

 Step 5: Choose "Define from operation and schema (specified later)" option

Step 6: Choose the following options and click Next

Type: Service [You will choose "Reference" if you need to consume a HTTP REST service]
Operation Type: Request-Response [For 2-way communication. Choose One-way if the service doesn't return a response]
Operation Name: Defaults to Request-Response [You can change it as you please]
Verb: GET [This specifies the HTTP method. You have 2 options GET/POST]
Payload Type: url-encoded [For HTTP GET method, SOA 11g support only payload type of url-encoded (name-value pairs). For HTTP POST, you get 2 options url-encoded and XML]

Step 7: In the Messages dialog, select the GreetCustomer.xsd, <CustomerInput> and <Response> XML elements for "Request Message Schema" & "Response Message Schema" respectively.

Step 8: In the summary page, click "Finish" to complete service

Now, drag and drop a BPEL Process on the "Components" section.

Name the process as "GreetCustomerProcess" and choose to define service later.

You can now proceed to build the BPEL process as you please. As part of this sample, I have concatenated the customer name input with "Welcome" prefix so that the service returns the greeting as response.

Finally, deploy this project to your SOA server.

On deployment you can notice that the service is exposed both as a WSDL based webservice and HTTP based REST service. This will enable clients to interface through either standards.

You can test this service either via Enterprise Manager (EM) console - test mode or via normal browser.

For testing your SOA 11g based HTTP service refer to my blog entry here

Consuming a HTTP REST service in SOA 11g BPEL process:

Step 1: Create a SOA Project with empty composite and name it "InvokeHttpGetService"

Step 2: Drag and Drop a HTTP Binding adapter on to the "External References" swimlane in the SOA composite (SCA)

Step 3: Choose Next in the Welcome page of the wizard

Step 4: Enter service name

 Step 5: Choose "Define from operation and schema (specified later)" option

Step 6: Choose the following options and click Next

Type: Reference [Since we are consuming a HTTP REST service]
Operation Type: Request-Response [Default selection for references]
Operation Name: Request-Response [Default]
Verb: GET [This specifies the HTTP method. You have 2 options GET/POST]
Payload Type: url-encoded [Default]
Endpoint: Provide the HTTP URL for the REST service to be invoked. In this case, you can obtain the HTTP URL from enterprise manager console.

Step 7: In the Messages dialog, select the GreetCustomer.xsd, <CustomerInput> and <Response> XML elements for "Request Message Schema" & "Response Message Schema" respectively.

Step 8: In the summary screen, click Finish to complete the service adapter

Now, drag and drop a BPEL Process on to the Components section of your SOA composite. Provide a name to the process, accept other defaults and click OK

Wire the BPEL process with the HTTP Binding adapter in the SOA composite.

Inside the BPEL process, just map the input payload element to the <Name> element of the greeting rest service and deploy to SOA server.

You can now test and check both SOA services in action. One will expose itself as a REST service and the other will invoke it.

Source code can be downloaded here

Let me know your thoughts in comments section.

Testing SOA 11g based HTTP REST services (Resolving Invalid Query String Error)

When a SOA 11g service is exposed as a HTTP service (using HTTP Binding adapter), it can be easily tested through Enterprise Manager (EM) console. Refer here to find out more on how to build/consume/trigger HTTP based REST services in SOA 11g.

However, the purpose of exposing the service accessible via HTTP standard is to ensure it can be directly consumed over a browser.

Typically for a HTTP-GET service, parameters (if any) to the service are passed as query strings (name-value pairs).

From the EM console, HTTP Endpoint for the deployed service can be obtained.

But just invoking the service endpoint via browser along with query string throws the following exception;
 "Invalid Query String"

To resolve this issue, pass the "operationName" query string (mandatory parameter) along.

For eg., if your current endpoint looks like:

http://localhost:7001/soa-infra/services/default/HttpGetRestService/HttpGet?name=Sathya

Modify this to:

http://localhost:7001/soa-infra/services/default/HttpGetRestService/HttpGet?name=Sathya&operationName=Request-Response

Here operation name value is the operation name that was specified during the HTTP Binding adapter creation. By default operation name defaults to "Request-Response".

Learner Series: Oracle BPEL Receive & Pick Activity With Example

This post is part of the Oracle SOA BPEL learner series.

I have been getting lots of requests to write on basic SOA BPEL use-cases from my blog readers who are starting up on SOA initiatives. One such request that often comes across is the basic difference  between the usage of a pick and receive constructs in a BPEL process.

I have created a working BPEL use-case which contains both pick & receive activities in one SOA project.

A quick introduction to BPEL Pick & Receive Constructs;

Receive Activity: This is the first activity in most of the BPEL processes. As the name indicates, this construct receives information/message from a partner link.

Pick Activity: This activity is very similar to the receive construct. But unlike the receive activity which gets triggered only when a partner link invokes it, the Pick activity has 2 choices (On Message & On Alarm) - It waits for a message from a partner link or triggers another set of activities on timeout.

Use-Case: (Hypothetical but conveys the message)

A BPEL process (ReceivePick) gets a "Customer Name" as input, calls another BPEL process (CustomerCreditScoreWS) to get the customer's credit score. The CustomerCreditScoreWS process validates if the customer name starts with "A" and returns a credit rating immediately; else the process waits for 10 seconds before returning a blank response. The ReceivePick BPEL process waits for a message (credit score) from the CustomerCreditScoreWS process. If it gets a response (On Message: credit score), the process completes by returning a "Success" message; otherwise in the event of not getting a response for 8 seconds (On Alarm: 8 seconds) the process waits and terminates by returning a "Failure".

Receive-Pick BPEL Constructs at a glance

You can download the source code for this sample here

SOA 11g File Adapter Pre & Post Processing Technique

File Adapter is one of the most feature rich & powerful technology adapter that is available with Oracle SOA Suite. In this article, I will be explaining how to perform pre-processing of a file when it is being read by the File Adapter in SOA suite with a use-case.

In an enterprise scenario a file process operation is not as simple as we would like it to be. Often there are situations where files of different formats that might be required to be processed selectively. Also, the files could be packaged & encrypted in one common format. How do we handle this scenario?

In Oracle SOA Suite, the File Adapter based on JCA 1.5 architecture provides feasibility to perform pre/post processing of file that are being processed (read or write). This feature is known as the "Pipeline & Valve" concept of the File Adapter. As you can see from the diagram below, the file adapter polls a specific folder from the file system - The file stream then passes through the pipeline (which holds a sequence of custom defined valves). A pipeline can have 'n' number of valves which will be processed in the order specified. The valves are nothing but content processors where a Java call be made.

The scenario that we are going to consider in this post is a toned down version of a real-time business use-case but sufficient enough to drive home the pre/post processing capabilities of the file adapter.

Use-Case:

A bunch of applications publish files of various different formats to a common folder which should be processed. However, only files of certain formats must be picked up for processing and the rest left to be processed by a different system.

This is a classic case where the SOA suite file adapter's pre-processing technique could be put to use in determining the file format before processing a file.

Step 1: Building the custom valve to determine mime type of the file

Let us first start by creating the valve (Java class) which will determine the file format. All valves must implement either the Valve interface or StagedValve interface. Optionally, to make it easier, the custom valve class can also extend AbstractValve or AbstractStagedValve classes.

In this case, I have created a MimeValidationValve Java class which extends AbstractValve. Only files which have the following mime types are allowed.

text/plain
application/pdf
application/msword

This is configurable in the properties file. I have made use of Apache Tika open source toolkit which is very powerful in extracting metadata information of the files polled. Read more on Apache Tika here.

One important point to note here is that you will need to add the bpm-infra.jar library to the Java project in order to compile the valve class. This library is available under  <Middleware_Home>/Oracle_soa1/soa/modules/oracle.soa.fabric_11.1.1

Project Properties -> Libraries & Classpath -> Add Jar/Directory

You can download the valve Java project here

Step 2: Building the SOA application to process files

You can download the SOA project here. This project has a 'Read' file adapter to poll for files from the file system, a 'Write' file adapter to write files back to file system and a BPEL process connecting these adapters.

Step 3: Creating the Pipeline XML file

Recall that a pipeline can have one or more valves which will be processed in the order specified. The pipeline XML file will hold references to the various different valves that must be invoked by the file adapter before the translation phase or handing it over to the SOA runtime.

Let us now go back to the SOA project and create the pipeline XML file. Let us review the FilePipeLine.xml under the DGFileProcessor SOA application.


<?xml version="1.0" encoding="windows-1252" ?>
<pipeline xmlns="http://www.oracle.com/adapter/pipeline">
  <valves>
    <valve>mimetype.MimeValidationValve</valve>
  </valves>
</pipeline>

Note that any number of valves can be added to the pipeline by just adding the <valve> elements.

Step 4: Plumbing the Pipeline with the appropriate file adapter

Now that we have the valves created and the pipeline/valve configurations done, the final piece that remains to be done is to let the file adapter trigger pipeline processing. To do this, open the corresponding file adapter's jca file and add the following property.

<property name="PipelineFile" value="FilePipeLine.xml"/>

That completes the solution for the use-case.