...
The REST Plugin
Excerpt |
---|
simplifies REST-style resources to be consumed by both human and machine clients |
...
- Fully implements Ruby on Rails REST-style URLs
- Supports XML-free development, without requiring annotations
- Built-in serialization and deserialization support for XML and JSON
- Automatic error handling
- Type-safe configuration of the HTTP response
- Automatic conditional GET support
Usage
As with the Codebehind Plugin, the first step is to tell the plugin where to find your resource action classes. Modify the configuration of your Struts 2 filter in web.xml
and add the 'actionPackages' init-param like so:
Wiki Markup |
---|
{snippet:url=struts2/apps/rest-showcase/src/main/webapp/WEB-INF/web.xml|id=filter|lang=xml} |
To set other Struts properties, add other init-params. For example to set devMode
to true, add:
Code Block | ||
---|---|---|
| ||
<!-- ... -->
<init-param>
<param-name>struts.devMode</param-name>
<param-value>true</param-value>
</init-param>
</filter>
|
Next, create Create Java objects ending in "Controller" in the configured package. The "Controller" suffix is used to distinguish REST action resources from regular Struts 2 actions, although it is completely optional and they are functionally the same. Now, add in methods to handle the various requests. For example, the following resource action will support /orders/34
GET and PUT requests:
Code Block | ||
---|---|---|
| ||
package org.apache.struts2.rest.example;
@Namespace("")
public class OrdersController implements ModelDriven<Order> {
private OrderManager orderManager;
private String id;
private Order model;
// Handles /orders/{id} GET requests
public HttpHeaders show() {
model = orderManager.findOrder(id);
return new DefaultHttpHeaders("show")
.withETag(model.getUniqueStamp())
.lastModified(model.getLastModified());
}
// Handles /orders/{id} PUT requests
public String update() {
orderManager.updateOrder(model);
return "update";
}
// getters and setters
}
|
...
Code Block |
---|
struts.rest.handlerOverride.xml=myXml |
struts.xml
Because the REST plugin uses the Convention plugin, some settings need to be set in struts.xml:
Code Block | ||||
---|---|---|---|---|
| ||||
<constant name="struts.convention.action.suffix" value="Controller"/>
<constant name="struts.convention.action.mapAllMatches" value="true"/>
<constant name="struts.convention.default.parent.package" value="rest-default"/>
|
Example
The plugin ships with a struts2-rest-showcase
application that demonstrates a simple REST web program.
...
The following settings can be customized. See the developer guide.
For more configuration options see the Convention Plugin Documentation
Setting | Description | Default | Possible Values | |||
---|---|---|---|---|---|---|
| The alias for the | N/A | Any declared alias for a | |||
| The default extension to use when none is explicitly specified in the request | | Any extension | |||
| The HTTP status code to return on validation failure | | Any HTTP status code as an integer | Whether to disable the scanning of the classpath for controllers or not | | true or false |
Installation
This plugin can be installed by copying the plugin jar into your application's /WEB-INF/lib
directory. The REST plugin is dependent on the Codebehind Convention Plugin, so if aren't using a build system that supports transitive dependencies like Maven 2, you will need to add that plugin as well.
...