Expoze

1. Overview
2. Downloads
3. User documentation
4. Developer documentation
5. Javadocs

1. Overview

The Expoze framework facilitates exposure of methods on beans managed by the Spring framework IOC container as RESTful message-based web services. Methods are exposed through simple XML configuration, while customized response messages can be defined through reusable Velocity templates, typically in XML or JSON format.

2. Downloads

The latest Expoze framework release is version 1.0.6 and can be downloaded in several formats:

Expoze Framework - Binaries
Expoze Sources - Sources
Expoze Dependencies - Third-party binary dependencies

Expoze framework is built with Maven and is located in its central repository. It can be configured as a dependency in the project object model like this:

<dependency>
  <groupId>org.amplecode</groupId>
  <artifactId>expoze</artifactId>
  <version>1.0.4</version>
</dependency>

3. User documentation

The Expoze framework contains mainly functionality for server side development, but also supports client side development.

3.1 Server side

3.1.1 Usage

The core class in the Expoze framework is the SpringWebServiceServletDispatcher, which handles incoming HTTP requests, invokes the appropriate methods and generates the responses. Incoming requests can be mapped to the SpringWebServiceServletDispatcher through the deployment descriptor file (web.xml) like this:

<servlet>
  <servlet-name>SpringWebService</servlet-name>
  <servlet-class>org.amplecode.expoze.dispatcher.SpringWebServiceServletDispatcher</servlet-class>
</servlet>
  
<servlet-mapping>
  <servlet-name>SpringWebService</servlet-name>
  <url-pattern>*.service</url-pattern>
</servlet-mapping>

This will tell your web-application to let the Expoze framework handle all incoming requests ending with .service. The request pattern can obviously be set to anything you like. Typically you would like to configure Spring in a similar fashion. You can read more about this in the Spring reference.

<context-param>
  <param-name>contextConfigLocation</param-name>
  <param-value>classpath*:/META-INF/beans.xml</param-value>
</context-param>
  
<listener>
  <listener-class>org.springframework.web.context.ContextLoaderListener</listener-class>
</listener>

The methods to expose are configured in a file called dispatcher.xml. This file must be present on the classpath of your application. The complete XML schema definition can be found here. The XMLNS looks like this:

<expoze xmlns="http://www.amplecode.org/schema/expoze"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xsi:schemaLocation="http://www.amplecode.org/schema/expoze expoze-1.0.xsd">

A typical dispatcher configuration looks like this:

<expoze> <!-- XMLNS omitted -->
  <requests>

    <request>
      <name>getPerson</name>
      <type>document</type>
      <bean>org.amplecode.person.PersonService</bean>
      <method>getPerson</method>
      <parameters>
        <parameter>
          <type>int</type>
          <name>id</name>
        </parameter>
      </parameters>
      <template>personXml.vm</template>
      <responses>
        <response>
          <format>xml</format>
        </response>
        <response>
          <format>json</format>
          <template>personJson.vm</template>
          <contentType>application/json</contentType>
        </response>
      </responses>
    </request>

    <!-- More requests here -->
 
  </requests>
</expoze>

• The name element is the request name. Assuming the mentioned deployment descriptor this will correspond to a request http://server.com/getPerson.service.
• The type element is optional and defaults to document. Valid options are document, chart, and file. More on this in the response type section.
• The bean element corresponds to the bean identifier of the target service in the Spring IOC container.
• The method element corresponds to the method on the target service.
• The parameters section defines the parameters on the method, where parameter type and and parameter name must be specified. Both class names (like java.lang.Integer) and primitive types (like int) are accepted.
• The template element defines the name of the Velocity template which is responsible for forming the response. This template will be used when no format parameter is included in the request.
• The contentType element is optional, and defaults to text/xml. This is useful when other responses like HTML are required. The content type will be used when no format parameter is included in the request.
• The responses section is optional and enables you to define different response output identified by a format. The format is passed to the server as a HTTP parameter called "format", eg like http://server.com/getPerson.service?format=json.

The important thing to understand is that all request elements can be overridden in a response definition. For instance, you can tell Expoze that a request with format json should override the default settings for template and contentType defined in the request root element. Other elements defined for the request, like bean and method, will take effect. If no format is specified in the HTTP request or no response is defined for the specified format, Expoze will fall back to the elements defined for the root request.

3.1.2 Response types

Document response type implies that the object returned from the invoked method will be merged with a Velocity template and written to the response. The object returned from the exposed method will get the value "object" in the Velocity context. A typical Velocity template will look like this:

<?xml version="1.0" encoding="UTF-8"?>
<person>
  <id>$object.id</ud>
  <name>$encoder.xmlEncode( $object.name )</name>
  <address>$encoder.xmlEncode( $object.address )</address>
</name>

Notice the call to the built-in encoder object in Expoze. You can read more about the Velocity syntax in the Velocity reference.

Chart response type represents the built-in support for JFreeChart and is available only for methods that returns an object of type JFreeChart. The chart will be written as a PNG to the response with content type image/png. No special configuration is needed and the template and contentType configuration elements can be omitted.

File response type is available only for methods for which the first parameter is of type OutputStream. The defined method will be given access to the OutputStream from the HttpServletResponse and allowed to perform it's work. In other words, whatever content the defined method writes to the OutputStream will be sent directly to the browser. The template configuration element can be omitted.

3.2 Client side

The Expoze framework supports client side application development through the abstract classes EndpointSupport and ObjectMapper. The client side support is confined to XML response messages. The ObjectMapper class should be extended by a concrete class for all domain objects involved in the web service. A typical implementation looks like this:

public class PersonMapper
  extends ObjectMapper<Person>
{
  @Override
  public String getElementName()
  {
    return "person";
  }

  @Override
  public String getCollectionName()
  {
    return "persons";
  }

  @Override
  public Person getObject( XMLReader reader )
  {
    Map<String, String> values = reader.getElements( "person" );

    Person person = new Person();
    person.setName( values.get( "name" ) );
    person.setAddress( values.get( "address" ) );

    return person;
  }
}

The getElementName method should return the XML element name of the implementing class. The getCollectionName method should return the XML collection name of the implementing class. The getObject method should return an object of the type of the implementing class.

The EndpointSupport class provides a getXmlReader method which returns an XMLReader with an underlying input stream which will connect to a web service on the URL given as input argument. The XMLReader originates from the StaxWax framework, which is used behind the scenes. This makes implementing an endpoint straight-forward:

public class ExpozePersonEndpoint
  extends EndpointSupport implements PersonEndpoint
{
  private final static String BASE_URL = "http://localhost:8080/webservice";

  public Person getPerson( int id )
  {
    XMLReader reader = getXmlReader( BASE_URL, "getPerson.service?id=" + id );

    return new PersonMapper().getObject( reader );
  }

  public Collection<Person> getAllPersons()
  {
    XMLReader reader = getXmlReader( BASE_URL, "getAllPersons.service" );

    return new PersonMapper().getObjects( reader );
  }
}

An XMLReader is retrieved from the EndpointSupport parent class, which takes the base URL of the web service and the web service method name as arguments respectively. A Person object or collection of Person objects are retrieved from the PersonMapper previously described. The PersonEndpoint interface is omitted in this example.

3.3 Sample application

A complete sample Expoze application is available here. The application is built with Maven and will be packaged as a WAR-file. The WAR-file should run on a servlet container. Unit tests testing the client are included.

4. Developer documentation

The Expoze framework is released under the BSD open source license and can be modified by anyone.

The following class diagram describes the components in the Expoze framework:

5. Javadocs

View the API/Javadocs.