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:
<dependency>
<groupId>org.apache.struts</groupId>
<artifactId>struts2-rest-plugin</artifactId>
<version>${struts.version}</version>
</dependency>
<dependency>
<groupId>org.apache.struts</groupId>
<artifactId>struts2-convention-plugin</artifactId>
<version>${struts.version}</version>
</dependency>
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:
<web-app id="WebApp_9" version="2.4"
xmlns="http://java.sun.com/xml/ns/j2ee"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee http://java.sun.com/xml/ns/j2ee/web-app_2_4.xsd">
<filter>
<filter-name>action2</filter-name>
<filter-class>org.apache.struts2.dispatcher.ng.filter.StrutsPrepareAndExecuteFilter</filter-class>
</filter>
<filter-mapping>
<filter-name>action2</filter-name>
<url-pattern>/*</url-pattern>
</filter-mapping>
</web-app>
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.
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE struts PUBLIC "-//Apache Software Foundation//DTD Struts Configuration 2.0//EN"
"http://struts.apache.org/dtds/struts-2.0.dtd">
<struts>
<!-- The struts rest plugin allows you to define the paths used for the webservice.
If you have groupings of controllers and you want users to access the controllers based on the groupings, you can do this in the following way:
1. create a package for each grouping (i.e. com.mersoft.test.group1, com.mersoft.test.group2)
2. set the struts.convention.package.locators as the last package name before the groupings (i.e. "test")
3. access the rest webservice by {application base}/{group name}/{controller name} (i.e. {application base}/group1/controller1, {application base}/group2/controller2)
If you want all controllers accessed from the application base:
1. put all the controllers in the same package (i.e. com.mersoft.controller).
2. set the struts.convention.package.locators as the last package name (i.e. "controller")
3. access the rest webservice by {application base}/{controller name} (i.e. {application base}/controller1)
-->
<constant name="struts.convention.package.locators" value="[PACKAGE TO LOOK FOR CONTROLLERS]"/> <!-- The convention plugin defaults this to "action,actions,struts,struts2" -->
<constant name="struts.convention.action.suffix" value="Controller"/> <!-- The convention plugin defaults this to "Action" -->
<constant name="struts.convention.action.mapAllMatches" value="true"/> <!-- The convention plugin defaults this to "false" -->
<constant name="struts.convention.default.parent.package" value="rest-default"/> <!-- The convention plugin defaults this to "convention-default". The "rest-default" is defined by the struts2 rest plugin -->
</struts>
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<T>. In my example below I added the Validateable interface and the ValidationAwareSupport extension. This allows the controller to be validated prior to any executions.
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<TestObject>, 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 <constant name=”struts.convention.result.path” value=”/WEB-INF/{jsp directory}”/> 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:
<dependency>
<groupId>com.thoughtworks.xstream</groupId>
<artifactId>xstream</artifactId>
<version>1.3.1</version>
</dependency>
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:
<bean type="org.apache.struts2.rest.handler.ContentTypeHandler" name="myXml" />
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:
<dependency>
<groupId>org.apache.struts</groupId>
<artifactId>struts2-spring-plugin</artifactId>
<version>${struts.version}</version>
</dependency>
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:
<context-param>
<param-name>contextConfigLocation</param-name>
<param-value>
classpath:/applicationContext-resources.xml
classpath:/applicationContext-dao.xml
classpath*:/applicationContext.xml
</param-value>
</context-param>
<listener>
<listener-class>org.springframework.web.context.ContextLoaderListener</listener-class>
</listener>
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.
<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:aop="http://www.springframework.org/schema/aop"
xmlns:tx="http://www.springframework.org/schema/tx"
xsi:schemaLocation="
http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-2.5.xsd">
<bean id="com.mersoft.web.controller.TestController" >
<constructor-arg ref="testManager" />
</bean>
</beans>
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.
