Download REST Adaptor Service Description

REST Adaptor Service Description
Author: Leon Rubin
E-Mail: [email protected]
The REST Adaptor Service allows hosting RESTful Web Services inside an ESB runtime (MQ)
container. REST is simple, powerful, and quickly growing in popularity. A quick look at this
technology reveals that RESTful services are very similar to traditional web applications because
they process HTTP requests and respond by generating dynamic content. Therefore, a well
designed domain of services will have a controller layer that converts HTTP parameters into
service input objects and delegates the processing to the business logic. We already have a few
great frameworks for building web application controllers. Struts (and its latest version Struts2)
are an example of such an MVC framework. While Struts2 is great, it can only run in a context
web/app server. The interesting part of this solution is that it enables Struts2 to execute in an
ESB runtime container as if it implemented all essential aspects of the J2EE Servlet specification
and process JMS messages as if they were HTTPServletRequests. Granted, ESB already
contains components to convert HTTP requests into JMS messages (HTTP Acceptors) but then
the developer is on their own processing a JMS message. This service allows developers to go
beyond pure protocol translation and put a proven MVC framework to work for processing those
messages and structuring their applications.
This idea was a result of a much less serious exercise: implementing a simple Web server using
ESB and use it to host a simple Web application. My original application consisted of two
custom Java services and an HTTP Acceptor: one service allowed serving static content from
the class path of the ESB (XQ) container; another parsed a web.xml file, loaded HttpServlets
from the class path, and allowed to turn ESB into a simple Servlet engine. The resulting Web
server was fully functional and allowed building and running a small Web-based GUI
application. There was even a simple session management mechanism using hidden form fields
that allowed clients to maintain state in HttpSessions. All that was sufficient, but without the
ability to run JSPs, all dynamic content had to be generated by Servlets which throws the
developer back to the stone age of web development. Also, creating HttpServlet for every action
was tedious, which inspired me to implement Struts2 support. While using ESB instead of
Tomcat is a cool idea, it probably violates a lot of best practices and is an example of using a
wrong tool for the job; however using struts to implement RESTful services and hosting them
inside the ESB is a viable and powerful technique. The original small and silly project evolved
into something that I hope you will find useful and elegant.
My submission consists of two projects (both are contained in the
RESTAdaptorFinal_02_14_2008.zip file and can be imported into a workbench by using the
Import… -> General/“Import Existing Projects into Workspace”:
 A Sonic ESB REST Adaptor project. This is the project that includes the Custom Java
Service presented for your evaluation. An HTTP Acceptor is required to convert all HTTP
requests to JMS messages. I included the instructions for setting up an acceptor and a URL
mapping in a separate document. All struts, spring, castor, and other jars are included in the
external directory of the project. I also included all the necessary XQ jars in the soniclib folder just for building purposes since your workbench may be installed in a different
directory so a Java Build Path reference to C:/ESB/7.5/lib/xq_core.jar may not
be valid on your machine. Also, I am assuming that the service will be simply uploaded by
double clicking on the RESTAdaptorServiceType.esbstyp and clicking the “Upload
the Java Service to the Sonic Domain and create a default instance” button. I am assuming
that the service will be in the dev_ESBTest runtime (MQ) container and in the
dev_ESBTest ESB (XQ) container. The service endpoint will be created automatically as
a result of the upload. That endpoint will use a topic and the default JMS connection
connected to the default management broker. In the real world, I would never use the
management broker and the default container but have a separate broker and runtime (MQ)
containers for applications, but for this example I will break this rule for simplicity sake.

An Online Bank Java Project. This is a small and simple application that demonstrates
how to develop services for the REST Adaptor. The result of this project is a JAR containing
the Struts action class and the struts configuration file. For simplicity, this JAR is extracted
to the same directory where all other JARs are stored in the REST Adaptor project. It is a
simple Java project and has no XQ dependencies. It implements a single use case for the
online banking application: transaction search. The inputs are the account number, from
date, and to date. This project uses the Struts2 validation feature and moves all input
validation from the action class code to a separate XML file. The output of the service is an
XML message containing all transactions that match the criteria (or an error report including
system and validation errors). The resulting XML is generated using the Castor Java/XML
binding framework.
Running the Sample Transaction Search Function
Open the OnlineBankTest.html in Internet Explorer. This is an HTML form with a couple of
links that simulate both the POST and the GET requests to the service.
1. Click the submit button.
The system should send the data to the REST service and return some XML
<?xml version="1.0" encoding="UTF-8" ?>
<transaction-search-result>
<transactions>
<number>1097</number>
<amount>45.77</amount>
<date>2008-02-14T12:14:21.274-05:00</date>
<description>INTEREST FROM 10/22/2007 THROUGH 11/22/2007</description>
</transactions>
<transactions>
<number>1098</number>
<amount>1225.79</amount>
<date>2008-02-14T12:14:21.274-05:00</date>
<description>AUTOMATED DEBIT ONLINE BROKER ACH IN</description>
</transactions>
<transactions>
<number>1099</number>
<amount>321.25</amount>
<date>2008-02-14T12:14:21.274-05:00</date>
<description>AUTOMATED DEBIT CREDIT CARD E-PAYMENT</description>
</transactions>
</transaction-search-result>
2. Click on the first link. It should send the same data to the service and result in the same
XML
3. Click on the second link. It should simulate a failure and send an error message back
<?xml version="1.0" encoding="UTF-8" ?>
<error-collection>
<errors>Failed to access transaction data com.onlinebank.util.exception.DAOException:
System Down</errors>
</error-collection>