A Rich Web Service API for Your Favorite Framework, Part 4: Wicket

The intent of this how-to series is to demonstrate the development of a rich Web service API on a variety of popular development frameworks. Part 4 (this tutorial) targets Apache Wicket.

We're going to be using Enunciate to supply a rich Web service API to the familiar wicket examples application included in the Wicket distribution bundle. Among the Wicket examples, you'll find a "contacts" application that is used to list a set of contact information. The contact data is provided by the org.apache.wicket.spring.common.ContactDao interface. By the end of the tutorial the example application will include the following:

• REST endpoints. The contact REST endpoints will supply resources in both XML and JSON data formats.
• SOAP endpoints. The contact API will be exposed via SOAP and defined by a well-defined and consolidated WSDL.
• Full API Documentation. The contact Web service API will be fully-documented.
• Client-side code. The application will provide client-side Java code that will be able to access the Web service API remotely.

Enunciate makes it drop-dead easy to develop this kind of Web service API: a few minor tweaks to the build file, a configuration file, and some metadata on the service interface.

Step 1: Set up the Environment

First make sure you have Maven installed, since that's the build tool we'll be using to run the example application. Then download the Wicket distribution bundle and unpack it. This tutorial was written based on version 1.3.4 (the latest stable release version at the time of writing).

You'll find the wicket example application in the src/jdk-1.5/wicket-examples directory of the unpacked distribution. We'll refer to this directory as $EXAMPLES_HOME. It should be ready for deployment. Open up a command console at $EXAMPLES_HOME, then:

mvn jetty:run-exploded

You should be able to open up a browser to http://localhost:8080/wicket-examples to see the examples application in all it's glory. You can see the contact example by navigating to http://localhost:8080/wicket-examples/spring.

We next need to integrate Enunciate with our project. We can do this by adding a dependency on Enunciate to our pom.xml file. There are also a few version conflicts between Enunciate and the Wicket project that need to be resolved by an explicit declaration. The first is Spring (update to version 2.5.5) and the other is ASM (update to version 3.1).

pom.xml

<dependencies>
  <dependency>
    <groupId>org.springframework</groupId>
    <artifactId>spring</artifactId>
    <version>2.5.5</version>
  </dependency>
  <dependency>
    <groupId>asm</groupId>
    <artifactId>asm</artifactId>
    <version>3.1</version>
  </dependency>
  <dependency>
    <groupId>org.codehaus.enunciate</groupId>
    <artifactId>enunciate-rt</artifactId>
    <version>1.8.1</version>
  </dependency>
  ...
</dependencies>

And we also add the maven-enunciate-plugin to the list of plugins in our pom.xml file:

pom.xml

...
<plugins>
  ...
  <plugin>
    <groupId>org.codehaus.enunciate</groupId>
    <artifactId>maven-enunciate-plugin</artifactId>
    <version>1.8.1</version>
    <executions>
      <execution>
        <goals>
          <goal>assemble</goal>
        </goals>
      </execution>
    </executions>
  </plugin>
  ...
</plugins>
...

It should also be noted that the contacts example is used to demonstrate Wicket integration with Spring, but this is irrelevant to the selection of the Web service API. The contacts example was selected because it provides a service interface, org.apache.wicket.spring.common.ContactDao, that can be conveniently exposed as a Web service. Enunciate leverages the capabilities of Spring to deploy and manage the Web service API, but this should be transparent to the development process.

Now let's add a Web service API.

Step 2: Enunciate Configuration

Here is an Enunciate configuration file that Enunciate uses to expose the Web service API for the contacts service. Drop that in $EXAMPLES_HOME (next to the pom.xml file). Let's briefly go over the basic parts of this file.

The <api-classes> element simply tells Enunciate what classes are to be used to define the Web service API. By default, Enunciate assumes all classes in the project are a part of the Web service API, but the examples application has a lot of other classes that are used to drive the UI and were never meant to define a Web service API, so we have to tell Enunciate that only three classes in the org.apache.wicket.spring.common package are used to define our Web service API:

...
<api-classes>
  <include pattern="org.apache.wicket.spring.common.Contact"/>
  <include pattern="org.apache.wicket.spring.common.ContactDao"/>
  <include pattern="org.apache.wicket.spring.common.ContactDaoImpl"/>
</api-classes>
...

The balance of the configuration file is used to define behavior in a specific Enunciate module. Enunciate generates the documentation of our Web service API from the JavaDocs of our API classes. By configuring the docs module, we tell Enunciate to put the documentation in the /api directory of the application and assign the documentation a title.

Enunciate assembles the Web service API in the form of a Spring application, and it needs to be merged with the examples application. We do this by merging the Enunciate-generated web.xml file with the examples web.xml file and by "importing" the bean definitions of the contacts application with the bean definitions of the Enunciate application. In order to do this reliably, we need to move the web.xml file in to $EXAMPLES_HOME (next to the pom.xml file) so that file that Enunciate generates doesn't get stomped on.

...
<modules>
  <docs docsDir="api" title="Petclinic API"/>
  <spring-app>
    <war mergeWebXML="web.xml"/>
    <springImport uri="classpath:applicationContext.xml"/>
  </spring-app>
</modules>
...

mv src/main/webapp/WEB-INF/web.xml .

Step 3: Annotate the API Classes

SOAP Metadata

The service interface of our Web service API is defined by the org.apache.wicket.spring.common.ContactDao interface and its associated implementation, org.apache.wicket.spring.common.ContactDaoImpl. To expose a SOAP interface we just need to apply some JAX-WS metadata to these classes. Specifically, we apply the @javax.jws.WebService annotation to the ContactDao interface and the same annotation to the ContactDaoImpl class, specifying the interface that it implements according to the JAX-WS specification.

The Clinic interface defines a method, find(), that returns an Iterator, which is not a valid return type for JAX-WS. We'll just exclude it for now with the @javax.jws.WebMethod annotation and refactor it later to be a Collection or something.

ContactDao.java

@WebService
public interface ContactDao {
  /**
   * @return total number of contacts available
   */
  int count();

  /**
   * @param qp sorting and paging info
   * @return iterator over contacts
   */
  @WebMethod (
    exclude = true
  )
  Iterator find(QueryParam qp);

  /**
   * @param id contact id
   * @return contact with matching id
   */
  Contact get(long id);
}

ContactDaoImpl.java

@WebService (
  endpointInterface = "org.apache.wicket.spring.common.ContactDao"
)
public class ContactDaoImpl implements ContactDao
{
 ...
}

REST Metadata

Of course we also want to apply a REST interface to our API. This can be done by applying JAX-RS annotations to our service classes, but it's a bit more complicated because of the additional constraints of a REST API.

First of all, you have to map the service to a URI path by applying the @javax.ws.rs.Path annotation to the implementation class, ContactDaoImpl. We'll mount the clinic at the "/contacts" path.

Next, since you're limited to a constrained set of operations, you have to annotate specific methods that are to be included in the REST API. You must specify the HTTP method that is used to invoke the method and the subpath that is used to locate it. We'll keep it simple by exposing just the get() method via the GET operation using the javax.ws.rs.GET annotation and mounting the method at the "/contacts/contact/{id}" path using the javax.ws.rs.Path annotation. The "{id}" on the path will specify the id of the contact that we want to get. This means that the method parameter must be annotated with the @javax.ws.rs.PathParam annotation which is also used to specify the name of the path parameter.

Of course, you can expose other methods using other annotations, but we'll refer you to the JAX-RS documentation to learn how to do that. Note also that the method-level JAX-RS annotations can be applied to either the interface or the implementation class, but in this case, we'll apply them to the interface.

ContactDao.java

@WebService
public interface Clinic {

  ...

  /**
   * @param id
   *            contact id
   * @return contact with matching id
   */
  @GET
  @Path ("contact/{id}")
  Contact get(@PathParam("id") long id);

}

ContactDaoImpl.java

@Path ( "/contacts" )
@WebService (
  endpointInterface = "org.apache.wicket.spring.common.ContactDao"
)
public class ContactDaoImpl implements ContactDao
{
 ...
}

These classes can be downloaded here and here.

One more thing is required in order to expose a REST API. Since by default the REST endpoints will expose XML data, we have to provide root XML elements for the XML responses. To do this, we simply annotate the org.apache.wicket.spring.common.Contact class with @javax.xml.bind.annotation.XmlRootElement.

Contact.java

@XmlRootElement
public class Contact {
  ...
}

Step 4: Build and Deploy

Back on the command-line:

mvn clean jetty:run-exploded

Behold the Glory

Your application is fully-functional at http://localhost:8080/wicket-examples/.

Check out the documentation for your new Web service API at http://localhost:8080/wicket-examples/api/:

Everything is documented, scraped from the JavaDoc comments. Here's the documentation for the SOAP API:

And documentation for the REST API:

And you can download client-side libraries that Enunciate generated and can be used to invoke your Web service API:

What about your WSDL? http://localhost:8080/wicket-examples/api/ns1.wsdl

What about your XML-Schema? http://localhost:8080/wicket-examples/api/ns0.xsd

Want to see your API in action? Your SOAP endpoints are mounted at the /soap subcontext, and your REST endpoints are mounted at the /rest subcontext. To view a contact, just use the path we defined with JAX-RS annotations relative to the /rest subcontext. So to view the contact identified by id "1", we use http://localhost:8080/wicket-examples/rest/contacts/contact/1:

As a convenience, the same XML resource can also be found at http://localhost:8080/wicket-examples/xml/contacts/contact/1. And if you want to get that same resource as JSON, you can use http://localhost:8080/wicket-examples/json/contacts/contact/1.

And Beyond...

Well, that's how easy it is to add a Web service API to you Wicket application. But we've only barely scratched the surface of what Enunciate can do. What about any of this:

• Security (HTTP Auth, OAuth, form-based login, session management, etc.)
• GWT RPC endpoints and client-side JavaScript for accessing them.
• AMF endpoints and client-side ActionScript for accessing them.
• Streaming API for large requests.
• Etc.

At this point, it's only a matter of configuration....

If you've missed the other parts of the series, you can still catch them here at Javalobby:

• Spring
• JBoss Seam
• Struts