Creating SOAP Services on the Apache Cocoon Framework by benbenzhou


More Info
									  Creating SOAP Services on the Apache Cocoon
The Apache Cocoon Framework excels at processing and manipulating XML documents.
Thus it is an easy and ideal platform to use and create SOAP services. All the necessary
components already exist in the standard Cocoon release except for one. This article
introduces the XmlHttpTransformer component that allows mid-pipeline Cocoon
elements to operate as SOAP clients retrieving information from external services. Two
simple examples are presented with source code available. In addition the suitability of
the SOAP conventions is question and a generic alternative (i.e. XmlHttp) is suggested.

Apache Cocoon
Apache Cocoon, part of the Apache XML Project and soon to become a top-level project,
is a highly flexible web publishing framework facilitating solutions built up from
reusable components. Although reusability is an oft-touted quality of software
frameworks, Cocoon stands out because of its XML component orientation to software
solutions. As long as a component accepts and emits XML, it can be integrated into the
framework. For a more detailed introduction see my previous article (Getting Started
With Cocoon 2), or other articles listed in reference section.

Cocoon can naturally build web services based on its standard building blocks. However,
to access and utilize such services from Cocoon in a flexible manner necessitated the
creation of a new component called XmlHttpTransformer. Given this new component, in
conjunction with existing components, the full functional complement of creating and
utilizing web services from an “XML Directed Architecture” perspective is realized.

Example Service: SOAP Stock Quote
This example has been done a zillion times. You have all seen it: request the price of a
current stock given its ticker symbol. Here we shall implement this service with five
simple Cocoon components, all directed by XML files. It shall all be accomplished with
no procedural code being written, and it will be written to emulate the SOAP protocol
header and body.
Figure 1 above shows the design of our simple Apache Cocoon Framework Stock Server.
If you are unfamiliar with the basic building blocks of Apache Cocoon see “Getting
Started With Apache Cocoon.” We will assume that the stock price information is
located in a relational database. After all, it has to come from somewhere, and this basic
approach is valid with any persistence mechanism. To achieve the goal of creating a
SOAP stock quote service, only three interesting components are needed:

   1. An XSLT SQL Formatter. This is achieved with an XSL transformer and
      associated stylesheet (i.e. “sql.xsl”) expressed in a manner to pick out the stock
      symbol text from the incoming SOAP message, and then formulate a SQL query
      statement in the appropriate Cocoon SQL Transformer
   2. The second component is the SQL Transformer component itself. It will process
      the SQL query created above and return the results in XML to the next
   3. Finally, the stock price value shall be picked out of the SQL Transformer output,
      and then formatted back into a SOAP return message by means of a second XSL
      transformer and associated stylesheet “soap.xsl.”

The beginning and ending components (Cocoon generator and serializer) really handle
the protocol translation between the outer environment (i.e. XML over HTTP), and the
inner environment (Cocoon’s XML Sax Event stream). The major functional difference
between the two, other than the former is intended to operating in a distributed
environment, is that XML over HTTP is RPC-like as it has a bi-directional, or better
stated “round-trip” behavior, where the XML SAX Event stream is more a unidirectional

Simple? Easy? You bet! In this solution, there exists three “source files” (i.e. the
equivalent of “source code”). They are the two XSL stylesheet “sources” and a Cocoon
“site map” file that describes the component topology as shown in figure 1. Download
package (25Kbytes) to examine these files in detail.

The XML document emitted from the Cocoon Generator component is the SOAP request
as show below:
      <ns1:getQuote xmlns:ns1="urn:xmethods-delayed-quotes">
        <symbol xsi:type="xsd:string">IBM</symbol>

After transformation by a simple XSL stylesheet, the XML document sent to the SQL
Transformer will be:
      SELECT price FROM stock_demo WHERE name = 'IBM'

The XML document emitted from the SQL Transformer will be:

And the final SOAP response document will be:
      <n:getQuoteResponse xmlns:n="urn:xmethods-delayed-quotes">
        <Result xsi:type="xsd:float">86.92</Result>

This example demonstrates the principle of “Xml Directed Software:” Solutions realized
by directing generic procedural algorithms with application specific XML “source code”.

The Apache Cocoon XmlHttpTransformer
While the creation of a Web Service in the first example is achieved using only standard
available Cocoon components, the client side example necessitates the need for a new
component. The component XmlHttpTransformer was created for this purpose by the
author. The component is considered in “alpha” phase, tested against release 2.0.3, and is
free to download and use from If there is sufficient interest
I will integrate it into the Apache Cocoon project probably with release 2.1. In the mean
time, I will accept enhancement requests to quickly evolve this component to meet the
greater public need.

Example Client: Multi Currency Subsystem
In this example, a client type XmlHttp subsystem shall be demonstrated. What is meant
by a Cocoon Subsystem? A portion of a larger Cocoon application solution that accepts
in an XML document and emits out an XML document. Formulating exactly which
services (i.e. input to this subsystem) are to be requested is determined by the preceding
component stages (see resource articles for examples of simple complete solutions).
Processing the results, such as translating the results into a presentation language (i.e.
HTML), is achieved in subsequent component stages. This example will focus on just
retrieval of information from remote web services.
Specifically we shall create what acts like the SOAP stock service utilized in the earlier
example, but in this case returns the price in some specified foreign currency. The
interior core executes TWO SOAP queries over the Internet: a request for the stock price
in US dollars, and a request for the desired currency conversion rate.

Figure 2 above shows the simplified interior block diagram of this subsystem. Again, the
building blocks and content flow are very simple. Specifically, the behavior and results
of each stage are:

The first XSL Transformer accepts in a very simple XML document specifying the stock
symbol to be looked-up and the particular currency type to be exchanged into. A typical
input document to this transformer could be:

The XSL stylesheet source labeled “client.xsl” contains static information like the URI’s
of the various servers to be accessed, and the expected request format. Thus, the input
file into the XmlHttpTransformer component will look something like:
       <demo xmlns:xht="">
                 <ns1:getQuote xmlns:ns1="urn:xmethods-delayed-quotes">
                   <symbol xsi:type="xsd:string">IBM</symbol>
                 <ns1:getRate xmlns:ns1="urn:xmethods-CurrencyExchange">
                   <country1 xsi:type="xsd:string">United
                   <country2 xsi:type="xsd:string">Japan</country2>

The XmlHttpTransformer component processes these requests and replaces the request
XML elements (i.e. all nested by <xht:messages>..) with the responses returned from the
respective web services. In this case, two examples web services from the site are used. The output of this stage will look something like:
       <demo xmlns:xht="">
                  <Result xsi:type="xsd:float">86.92</Result>
                  <Result xsi:type="xsd:float">122.52</Result>

Finally, the returned response envelope formats are stripped off and the two results
combined, multiplied together for this example, into a single numeric value of the stock
price in the foreign currency, in this case the value of IBM stock in yen, as show below:
Again this example demonstrates the principle of “Xml Directed Software:” Solutions
achieved by directing generic procedural algorithms with application specific XML
“source code”.

XmlHttp: The Generic Equivalent of SOAP
In writing this article, associated software examples, and reviewing numerous on-line
articles and discussions, it became apparent that there is some question to the
appropriateness of the SOAP standard. There is no question about how fundamental and
key the transport of XML documents over HTTP is and shall remain in the future.
However, the more I delved into it, the tougher it became to clearly conceptualize the
appropriate role of SOAP. And I’m not alone. Paul Prescod explores alternatives in the
article “REST and the Real World,” Rich Salz with article “Processing SOAP Headers”
stretches to find usefulness in the SOAP headers, Edd Dumbill in “Whither Web
Services” writes a plethora of colorful perspectives on the whole web services wad of
standards, and finally Bellman questions the entire emerging ensemble of SOAP related
standards (WSDL, UDDI, etc…) in “Web Services - a waste of words.”

Thus this author proposes the generic concept and name “XmlHttp” to mean RCP like
transportation of XML over HTTP. No particular validation standard is specified, no
other transport mechanism such as FTP or SNMP is supported, no standard header
required, and finally error messages will either be the web service specific XML
constructs being accessed or generic HTTP error codes.

The examples in this article demonstrated how SOAP conforming services can be
accessed and emulated by simply adding and removing the SOAP header by way of XSL
transformers. Using the same building blocks it is just as easy to use and create services
that adhere to wide range of emerging alternatives as mentioned earlier.

An example web service and associated client emulating SOAP protocols implemented
using Apache Cocoon has been demonstrated. In particular, these examples show that is
it possible to implement such solutions with the entire application domain solution
captured in various XML documents (i.e. in these examples XSL stylesheets with content
directing components such as SQLTransformer and XmlHttpTransfomer). The only new
procedural software written (i.e. XmlHttpTransfomer) is generic in nature, reusable, and
independent of any particular application domain. This is a clear example of “Xml
Directed Software.”

Where to go and What to Do
The web site offers a wide range of web services that can be
experimented with. The second example in this article demonstrates usage of two of
these services.

Source code for the two examples and the XmlHttpTransformer component can be
obtained and download at:
If you are new to Apache Cocoon, first obtain and bring operational the default Cocoon
web application (i.e. collection of samples) on your favorite web server, then migrate to
the sitemap and components provided in the XmlHttp download.

   The Apache Cocoon, presently a sub-project of the Apache XML but soon to become
    a top level project:
   Getting Started With Cocoon 2: An introductory article:
   Apache Cocoon Made Easy with an interesting XMD Database example:
   A Short History of Apache Cocoon:
   Cocoon Flash Guides:
   Cocoon supporting documentation and information:

Sidebar 1: XML Direct Software / XML Directed
Apache Cocoon and the examples presented here clearly exhibit the characteristic I call
"XML Direct Software." Specifically, Cocoon is an XML-based framework for
aggregating and assembling SAX-based components into a web application. The
components are generic in nature without any hard-coded domain-specific content.
Instead, the domain-specific content, such as business logic, presentation logic, etc
resides in associated "directing" XML files and sources.

Apache Cocoon is thus an instance of the larger philosophy of XML Directed Software
and XML Directed Architectures. By no means is this philosophy bound to only web
services. This author postulates that XML Directed Architectures will become dominant,
and will supersede Object-Oriented Architectures in the software community due to their
natural higher-level perspective, natural reuse of software, and technology agnostic
perspective, during the first decade of the 21st century.

Sidebar 2: Apache Cocoon Notation
This article uses the following Apache Cocoon Graphical Notation:
Sidebar 3: Apache Cocoon Consulting
Apache Cocoon consulting and support services can be obtained at:

To top