There will be times when a client is better served by providing a service with a JSON over HTTP interface, rather than the more common SOAP over HTTP. By re-using the Java code that we built in the Converting between XML and JSON recipe, we'll expose a JSON interface, while working with XML internally to take the best advantage of OSB's strengths.
We'll assume that you have an OSB configuration project in OEPE, and that you have the Jackson and XMLBeans JAR files referred to in the Converting between XML and JSON recipe, as well as the JAR files produced by that recipe.
- Select the Oracle Service Bus perspective in Eclipse. Right-click on the OSB configuration project, and select New | Oracle Service Bus Project. In the dialog box, enter a name for the project (JSONCreditCardService) and click on Finish.
- Right-click on the InvokeJSONCreditCardService OSB project in the Project Explorer, and select New | Folder from the context menu.
Enter the name
jarsfor the folder in the New Folder dialog, and click on Finish. - Now, import the following JAR files from the CreditCardServiceMessages project into the
jarsfolder:dist/CreditCardServiceMessages_1.0.jardist/CreditCardServiceMessagesXmlBeans_1.0.jarlib/jackson-core-asl-1.9.7.jarlib/jackson-mapper-asl-1.9.7.jar
- We now need to inform OSB of the dependencies between the jars. Double-click on the jackson-mapping-asl-1.9.7.jar in the Project Explorer.
In the Modify Jar Dependencies dialog, select the jackson-core-asl-1.9.7.jar file from the Available jars pane on the left, and click on the Add > button to move it to the Jar references pane. Click on OK.
- Do the same for the CreditCardServiceMessages_1.0.jar file, but click on the Add All >> button to indicate that it depends on all of the other JAR files in the project.
There will be warnings about classes from the
org.joda.timepackage not being available. This is an optional dependency in the Jackson Mapper, and will not be a problem. - Right-click on the OSB project JSONCreditCardService and select New | Proxy Service from the context menu. In the New Oracle Service Bus Proxy Service dialog box, enter the name
JSONCreditCardService_1.0for the proxy service and click on Finish. - On the General tab, configure the Service Type to be Messaging Service.
- On the Messaging tab, configure the Request Message Type and Response Message Type to be Text.
- On the Transport tab, leave the Protocol set to http, replacing the Endpoint URI with the value /ckbk/svc/JSONCreditCard, and select the Yes radio-button for the Get All Headers option.
- The HTTP Transport, Message Handling, and Security tabs can be left with their default values.
- Next, we will create a conditional branch for the HTTP method. On the Message Flow tab, insert a Conditional Branch activity into the message flow, and assign it a name (
HTTPMethodBranch). For this branch, we will select a path based on the incoming HTTP method – we'll only supportPOSTfor this service. - Click on the Conditional Branch subtab in the Properties pane and then click on the
<XPath>value to open the XPath Expression Editor. Expand the inbound variable in the Variable Structures tab, as shown in the following screenshot:
- Drag the http-method into the Expression field to create the following expression, and then click on OK:
./ctx:transport/ctx:request/http:http-method
- Next, enter
inboundin the In Variable text field. The conditional branch should be configured as follows:
- Next, create a POST branch for the JSON POST request. Click on the branch branch1. In the Properties pane, enter
POSTin the Label field, and'POST'in the Value field.
- Add a Pipeline Pair to the POST branch, and assign it the name
PostPipelinePair. - Add a Stage to the Request Pipeline in the
PostPipelinePair, and assign it the nameProcessPutRequest. - Add a Java Callout to the
ProcessPOSTRequeststage. In the Properties pane, click on the Browse button to select the method to be invoked.This will open the Select an Archive Resource dialog box. Select the
CreditCardServiceMessages_1.0.jarfile in theJSONCreditCardServiceproject and click on the OK button. In the Select a Java Method dialog box, select the methoddebitCreditCardJsonToXml(java.lang.String)and click on OK.
- In the JavaCallout subtab of the Properties pane, click on the
<Expression>value to specify the input parameter to the Java method. Specify the XPath expression as$body/text(). The content of the body variable is the received JSON string. - In the Result Value field of the JavaCallout panel, enter
requestXml; the return value of the Java method will be assigned to this variable.
Click on the ProcessPutRequest stage in the Message Flow view, and select the Namespaces tab in the Properties pane. Add the three namespace mappings, as shown in the following table:
Prefix
URI
acchttp://rubiconred.com/ckbk/xsd/accountcmnhttp://rubiconred.com/ckbk/xsd/commonebmhttp://rubiconred.com/ckbk/ebm/CreditCardThe result will be as follows:
- Add an Assign activity to the ProcessPutRequest stage, after the Java Callout activity. Set the Expression to
data($requestXml//cmn:cardNumber), and the Variable tocreditCardNumber. - We have now converted the received JSON request to XML and used XPath to extract the credit card number. We will now construct an XML response, and convert it to JSON for returning to the client.
Insert a Stage named ProcessPostResponse into the Response Pipeline of the
PostPipelinePair, and add the same namespace definitions as we previously added to the ProcessPutRequest stage. - Add an Assign activity to the ProcessPostResponse stage. Set the Expression to the following:
<ebm:debitCreditCardResponse xmlns:ebm="http://rubiconred.com/ckbk/ebm/CreditCard" xmlns:cmn="http://rubiconred.com/ckbk/xsd/common"> <cmn:cardNumber>{$creditCardNumber}</cmn:cardNumber> <cmn:cardAuthCode>0000</cmn:cardAuthCode> </ebm:debitCreditCardResponse>Set the Variable to
responseXml. - Add a Java Callout activity following the Assign activity, and select the Java Method in the same way as in the ProcessPutRequest stage, but select the method
debitCreditCardResponseXmlToJson(org.apache.xmlbeans.XmlObject).Set the Java Callout activity's input parameter Expression to
$responseXml, and the Result Value toresponseJson. - Add a Replace activity after the Java Callout. Set the Properties as follows:
- XPath:
. - In Variable:
body - Expression:
$responseJson
Select the Replace node contents option.
- XPath:
- Next, we need to set the Content Type to JSON for the proxy response. Drag a Transport Header activity into the ProcessPostResponse stage, after the Replace activity.
- In the Transport Headers pane of the Transport Header activity, set the Direction to
Inbound Response. Click on the Add Header button to add a new header to the Inbound Response.Set the HTTP header Content-Type to have the value
'application/json'; this is the standard MIME type for JSON data.
The completed Pipeline Pair looks like the following screenshot:
- Your JSON service is now ready to be deployed and tested.
Since JSON is just structured text, we can configure an OSB proxy service to accept and respond with JSON by using the Text messaging type. We then use the Jackson and XMLBeans libraries to convert between JSON and XML as required.
The Transport Header activity is used to set the Content-Type header in the response to application/json, in order to inform the client of the data format used for the response. It's good practice for non-SOAP HTTP interfaces to ensure that the HTTP method, status code, and headers are used correctly.
It's possible to build services with OSB that will accept input in multiple formats, by inspecting the received Content-Type header, which can be accessed at:
$inbound/ctx:transport/ctx:request/tp:headers/http:Content-Type/text()
The appropriate transformation of the request payload can then be applied into a common format. Similar techniques may be used to return the response in a format chosen by the caller. The caller could indicate its preferred response format by using the Accept header, or by using something like a suffix on the request URI, which is accessed at:
$inbound/ctx:transport/ctx:request/http:relative-URI/text()
When adding error handling to your JSON services, you will probably want to override the HTTP status code of your response, to best communicate the error back to the caller. This can be achieved using an Insert activity, configured as follows:
|
Parameter |
Value |
|---|---|
|
Expression |
|
|
Location |
as last child of |
|
XPath |
|
|
In Variable |
|
Where 404 in the previous table is the HTTP status code that will be returned in the response.