Wednesday, July 24, 2013

opentravel web service - simple example

I'm going to show you how easy it is to write a REST and SOAP web service for opentravel messages using open source software.

By leveraging open source software, most of the difficult code is already written. All you have to do is implement a java interface to service the web service calls.

You don't have to worry about messy xml handling, you work with java classes. The framework does the work for you.

For this example we'll assume that you are a local sightseeing company. Your customers want to be able to access real-time pricing and availability for all of our tours.

They use the opentravel 2013A Tour Activity Availability message pair using SOAP and REST over HTTP.

This means you need a web server, a SOAP processing module, and a schema parser, as well as your code. Luckily open source software does most this.

If you're impatient and you just want this demo up and running with a just a few commands, click here for the schema library rest example.

I've created a template for your sample project. To create your project from this template, start eclipse and select:

File -> New -> Project -> Maven Project
On the Archetype screen, select the archetype: opentravel-touractivity-ws-service-archetype. If the artifact doesn't appear, click the 'add archetype' button; GroupId:, ArtifactId: opentravel-touractivity-ws-service-archetype, Version: 1.1.1 (Not the version show in this image)

On the Project screen, enter your group, artifact name, and version.

You can enter anything you want here. You will need your project group, artifact, and version when you deploy your project.
Click finish to build your project.

This project has three files.

The pom files is the maven project file. You will need to update the parent version number to version 1.1.1. The start of your pom file should look like this:

The blueprint.xml file is the configuration file. This blueprint tells the system to register this service to handle opentravel touractivity messages.

The source file handles the actual messages. This code is expected to process request messages and return a response.

If you look at the source code, you will find the method:
public AvailRS avail(AvailRQ request)
I have included some sample code that returns availability and pricing for several fake tours. This is where you would access your inventory and pricing and populate the return message.
The cool part of using a java representation of the opentravel xml message is you can use all the eclipse programming shortcuts, such as auto-complete and documentation display. All the comments and xml snippets from the (complex) opentravel schema have been transferred to the java source code. Try to ctrl-click one of the request or response method names and you will be looking at the java source code model of the xml message.

To build the project, right-click the project name in the project explorer and select Run as -> Maven install

Now we are ready to deploy this code.

For this example, I'll use apache karaf and cxf. You can also use any one of the enhanced esb servers such as Talend or Fuse. In fact, this code uses only open specifications, so you should be able to run it with minor configuration changes on almost any java app server.

Download karaf, unzip, and run it:

tar zxvf apache-karaf-2.3.2.tar.gz
cd apache-karaf-2.3.2
First, install apache cxf and a few support bundles.
features:addurl mvn:org.apache.cxf.karaf/apache-cxf/2.7.6/xml/features
features:install cxf cxf-databinding-jibx http obr
Now start the RESTful server and the SOAP server. These servers are configured to send incoming messages to a service registered to handle touractivity messages. (The blueprint.xml file does this) Type these command into the servicemix console.
obr:start -d
obr:start -d

# Enter the actual group/artifact/version of your project here:

Give it a moment to start, then try out the rest service by clicking this link:

You can test the SOAP service using soapui. The wsdl location is http://localhost:8092/soap/touractivity?wsdl.Try sending this soap message:

      <ns:ota_touractivityavailrq target="Production" timestamp="2012-04-19T05:16:51.353Z" version="1.0" xmlns:ns="">
            <ns:basicinfo touractivityid="CITYSS">
               <ns:starttime gt="" lt="" ns:starttime="">
            <ns:participantcount quantity="1">

Your response should look something like this: