Struts2 Rest Webservice

Mandi Zinn — Tue, 08 Sep 2009 14:10:52 +0000

I started out trying to create a rest webservice for a project I’m working on with Mersoft. After a little bit of research, I discovered Apache has a rest plugin that enables Struts 2 to perform as a rest webservice.

I followed the documentation at http://struts.apache.org/2.x/docs/rest-plugin.html and created my rest webservice. However, I came across a couple of issues that I could not find any documentation as to how to address. The first of these issues is that the documentation says that the rest plugin supports xml, json, and xhtml. I downloaded the rest example’s source jar and tore it apart, but there was nothing to address the xhtml. Next I installed the pre-compiled war and to my amazement, the xhtml worked. After I tore apart the war, I discovered what is required for the xhtml (I have that documented here)

The second issue I came across was that I didn’t like how the xml was being displayed (instead of using just the object name as the xml tag, it included the package name). How to customize the xml display is documented here.

The last struggle I had was that I wanted to use Spring to inject classes into my controllers. I searched online and found other developers asking how to do this, but could find nothing on how to actually do this. How to use Spring for the controllers is documented here.

I am writing this blog to document what I did to create a rest webservice and to share what I did to resolve the issues I had.

Creating a Rest Webservice

To create a rest webservice, Apache created a rest plugin that works with Struts 2. This plugin was written with the intent of being used with the struts 2 convention plugin.

These are the only dependencies needing to be added to a Struts2 project:


   org.apache.struts
   struts2-rest-plugin
   ${struts.version}


   org.apache.struts
   struts2-convention-plugin
   ${struts.version}

The web.xml must use the StrutsPrepareAndExecuteFilter for the struts 2 convention plugin (this Filter can also be used with other struts 2 applications as long as the application doesn’t need another filter that has to access the action’s context information). The web.xml should look like the following:



   
      action2
      org.apache.struts2.dispatcher.ng.filter.StrutsPrepareAndExecuteFilter
   

   
      action2
      /*

With the convention plugin, the only thing required in struts.xml is any changes in configuration needed for the convention plugin. If the web service is written without the convention plugin, you would just have to define each controller in the struts.xml (the same way an action is defined). The convention plugin just makes this defining process unnecessary.

The objects being passed through the rest webservice need to be defined. These are just POJOs. Here’s an example:

package com.mersoft.web.model;

public class TestObject {

   private String id;
   private String someString;
   private long someLong;
   private String anotherString;

   public String getId() {
      return id;
   }
   public void setId(String id) {
      this.id = id;
   }
   public String getSomeString() {
      return someString;
   }
   public void setSomeString(String someString) {
      this.someString = someString;
   }
   public long getSomeLong() {
      return someLong;
   }
   public void setSomeLong(long someLong) {
      this.someLong = someLong;
   }
   public String getAnotherString() {
      return anotherString;
   }
   public void setAnotherString(String anotherString) {
      this.anotherString = anotherString;
   }
}

The rest webservice uses “controllers” for data manipulation. The controllers must implement ModelDriven. In my example below I added the Validateable interface and the ValidationAwareSupport extension. This allows the controller to be validated prior to any executions.

NOTE: The Controller name must not use camel casing. (i.e. use TestinstanceController instead of TestInstanceController).

package com.mersoft.web.controller;

import org.apache.struts2.rest.DefaultHttpHeaders;
import org.apache.struts2.rest.HttpHeaders;

import com.mersoft.web.model.TestObject;
import com.opensymphony.xwork2.ModelDriven;
import com.opensymphony.xwork2.Validateable;
import com.opensymphony.xwork2.ValidationAwareSupport;

public class TestController extends ValidationAwareSupport implements ModelDriven, Validateable{
   /**
   *
   */
   private static final long serialVersionUID = -1045170916847707617L;

   private TestObject testObject = new TestObject();

   private String id;

   public TestController() {
      super();
   }

   public TestObject getModel() {
      //TODO: populate test object
      return testObject;
   }

   // GET /test/1
   public HttpHeaders show() {
      return new DefaultHttpHeaders("show");
   }

   // GET /test
   public HttpHeaders index() {
      return new DefaultHttpHeaders("index");
   }

   // POST /test
   public HttpHeaders create() throws Exception {
      //TODO: creation action here

      return new DefaultHttpHeaders("success");
   }

   //PUT /test/1
   public String update() throws Exception {
      //TODO: update action here
      return "success";
   }

   // DELETE /test/1
   public String destroy() {
      //TODO: delete action here
      return "success";
   }

   public void validate() {
      // TODO add validation here

   }

   public String getId() {
      return id;
   }

   public void setId(String id) {
      this.id = id;
   }

}

To access the webservice, you just need to make the request. (Look above at the type of request and the parameters that need to be passed to access each method.)

For xml requests, add .xml to the end of the url (i.e. Making a GET request to {application base}/test.xml will access the index method and return an xml response).
For json requests, add .json to the end of the url (i.e. Making a GET request to {application base}/test.json will access the index method and return a json response).

Adding custom methods

The rest webservice plugin is designed to be flexible. If there’s actions you don’t want the user to be able to perform, you simply omit it from the controller. If there’s a special action that is not part of the standard actions, you just add the custom action to your controller:

   public String test() {
      return "test";
   }

To access the above action, make a GET request to {application base}/test/1/test.xml.

Accessing the webservice via xhtml

Out of the box, the rest webservice supports xhtml, however you must create the jsp pages the webservice must display to the user.

By default, the convention plugin expects these files in WEB-INF/content/ (this can be changed by adding to struts.xml) . The file names must be {controller name}-{request name}.jsp. For example, for the jsp corresponding to the show action in TestController, the file name should be test-show.jsp.

NOTE: To display objects returned by the getModel() method, you just need to reference the object name within the model. (i.e. to display someString from the TestObject, you can reference it as ${someString} in the jsp)

For requests needing to be sent as a PUT or a DELETE, you can attach “?_method={REQUEST TYPE} to the end of the action method in the form and send the request as a post.

Customizing xml response

To make the xml cleaner, I wanted to display just the object name without the package the object is in. After doing a little bit of research, I discovered that the struts-rest plugin uses XStream. The latest version of XStream allows annotations to customize the xml. Since the struts-rest plugin doesn’t use the latest XStream, I created my own ContentTypeHandler using the latest XStream.

Be sure to add the XStream dependency to the classpath:


   com.thoughtworks.xstream
   xstream
   1.3.1

The ContentTypeHandler I created is very similar to that of the rest plugin’s XML content handler. The main difference is that I told XStream to process annotations.

NOTE: This must implement org.apache.struts2.rest.handler.ContentTypeHandler to work with the struts rest plugin.

package com.mersoft.rest.handler;

import java.io.IOException;
import java.io.Reader;
import java.io.Writer;

import org.apache.struts2.rest.handler.ContentTypeHandler;

import com.thoughtworks.xstream.XStream;

/**
* Handles XML content
*/
public class XStreamHandler implements ContentTypeHandler {

   public String fromObject(Object obj, String resultCode, Writer out) throws IOException {
      if (obj != null) {
         XStream xstream = new XStream();
         xstream.processAnnotations(obj.getClass());
         xstream.toXML(obj, out);
      }
      return null;
   }

   public void toObject(Reader in, Object target) {
      XStream xstream = new XStream();
      xstream.processAnnotations(target.getClass());
      xstream.fromXML(in, target);
   }

   public String getContentType() {
      return "application/xml";
   }

   public String getExtension() {
      return "xml";
   }
}

To use the new content handler, I had to add the following line to my struts.xml:

To tell the rest plugin to use my new content handler, I simply have to add the bean name to a struts.properties file:

struts.rest.handlerOverride.xml=myXml

Now I can use the XStream annotations. Here’s an example of how to use the annotations with the TestObject:

package com.mersoft.web.model;
import com.thoughtworks.xstream.annotations.XStreamAlias;
import com.thoughtworks.xstream.annotations.XStreamOmitField;

@XStreamAlias("test")
public class TestObject {

   private String id;
   private String someString;

   @XStreamOmitField
   private long someLong;

   private String anotherString;
   ...

For more on XStream’s annotations see http://xstream.codehaus.org/annotations-tutorial.html

Using Spring Dependency Injection on the Controllers

With the rest webservice I was creating, I wanted to spring inject my managers into my controllers. After searching on the web, I couldn’t find any answers on how to do this. Analyzing what I have accomplished so far, I realized that the controllers were no more than specialized actions. My biggest obstacle was discovering how to use the struts2 spring plugin with the struts2 convention plugin. The struts2 spring plugin pulls the “class” name from the struts.xml file. If the “class” name matches a bean definition, then the spring plugin pulls the bean. If it does not match a bean definition, then it pulls the class. After discovering this, it was pretty clear as to how to get this to work with the struts convention plugin.

First, I added the struts2 spring plugin dependency:


   org.apache.struts
   struts2-spring-plugin
   ${struts.version}

As the standard struts2 spring plugin requires, we must configure it in web.xml by setting up the context path and including the context listener:

   
      contextConfigLocation
      
         classpath:/applicationContext-resources.xml
         classpath:/applicationContext-dao.xml
         classpath*:/applicationContext.xml
      
   

   
      org.springframework.web.context.ContextLoaderListener

The only thing left was to set up the applicationContext.xml. In order for the spring plugin to pull the beans based on this configuration, the bean id must match the bean class.

NOTE: This will call the TestController constructor with the constructor containing the “testManager” class (i.e.: public TestController(TestManager testManager))

For more information on the struts2 spring plugin, you can see http://struts.apache.org/2.0.8/docs/spring-plugin.html

With this last issue resolved, I was able to do everything I wanted to do with my rest webservice. I hope this is helpful.

Mersoft Corporation Blog » xml parser

Struts2 Rest Webservice