|Apache Struts 2 Documentation > Home > Guides > Plugin Developers Guide > REST Plugin|
|This plugin is only available with Struts 2.1.1 or later|
The REST Plugin simplifies REST-style resources to be consumed by both human and machine clients. The goals are to 100% follow Ruby on Rails-style REST URL conventions and enable XML-free resource development. It builds on the Convention Plugin to support automatic configuration of both actions and results.
This Restful action mapper enforces Ruby-On-Rails Rest-style mappings. If the method is not specified (via '!' or 'method:' prefix), the method is "guessed" at using ReST-style conventions that examine the URL and the HTTP method. Special care has been given to ensure this mapper works correctly with the codebehind plugin so that XML configuration is unnecessary.
This mapper supports the following parameters:
struts.mapper.idParameterName- If set, this value will be the name of the parameter under which the id is stored. The id will then be removed from the action name. Whether or not the method is specified, the mapper will try to truncate the identifier from the url and store it as a parameter.
struts.mapper.indexMethodName- The method name to call for a GET request with no id parameter. Defaults to 'index'.
struts.mapper.getMethodName- The method name to call for a GET request with an id parameter. Defaults to 'show'.
struts.mapper.postMethodName- The method name to call for a POST request with no id parameter. Defaults to 'create'.
struts.mapper.putMethodName- The method name to call for a PUT request with an id parameter. Defaults to 'update'.
struts.mapper.deleteMethodName- The method name to call for a DELETE request with an id parameter. Defaults to 'destroy'.
struts.mapper.editMethodName- The method name to call for a GET request with an id parameter and the 'edit' view specified. Defaults to 'edit'.
struts.mapper.newMethodName- The method name to call for a GET request with no id parameter and the 'new' view specified. Defaults to 'editNew'.
The following URL's will invoke its methods:
GET: /movies => method="index"
GET: /movies/Thrillers => method="show", id="Thrillers"
GET: /movies/Thrillers;edit => method="edit", id="Thrillers"
GET: /movies/Thrillers/edit => method="edit", id="Thrillers"
GET: /movies/new => method="editNew"
POST: /movies => method="create"
PUT: /movies/Thrillers => method="update", id="Thrillers"
DELETE: /movies/Thrillers => method="destroy", id="Thrillers"
To simulate the HTTP methods PUT and DELETE, since they aren't supported by HTML, the HTTP parameter "_method" will be used.
Or, expressed as a table:
In addition to being a REST-style URL mapper, this plugin provides built-in support for multiple content types, switchable through the URL extension. In this way, a single resource can be exposed as multiple content types without any extra work.
For example, by exposing an "orders" resource, clients can immediately access it via:
The REST plugin automatically handles serialization to, and deserialization from, each format.
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:
In this example, the ModelDriven interface is used to ensure that only my model, the Order object in this case, is returned to the client, otherwise, the whole OrdersController object would be serialized.
You may wonder why the show() method returns a HttpHeaders object and the update() method returns the expected result code String. The REST Plugin adds support for action methods that return HttpHeaders objects as a way for the action to have more control over the response. In this example, we wanted to ensure the response included the ETag header and a last modified date so that the information will be cached properly by the client. The HttpHeaders object is a convenient way to control the response in a type-safe way.
Also, notice we aren't returning the usual "success" result code in either method. This allows us to use the special features of the Codebehind Plugin to intuitively select the result template to process when this resource is accessed with the .xhtml extension. In this case, we can provide a customized XHTML view of the resource by creating /orders-show.jsp and /orders-update.jsp for the respective methods.
If you need to handle extensions that aren't supported by the default handlers, you can create your own ContentTypeHandler implementation and define it in your struts.xml:
If the built-in content type handlers don't do what you need, you can override the handling of any extension by providing an alternate handler. First, define your own ContentTypeHandler and declare with its own alias. For example:
Then, tell the REST Plugin to override the handler for the desired extension with yours. In struts.properties, it would look like this:
Instruct Struts to use the REST action mapper:
Because the REST plugin uses the Convention plugin, some settings need to be set in struts.xml:
and for this example:
The plugin ships with a struts2-rest-showcase application that demonstrates a simple REST web program.
The behavior of the showcase is different with standard development, a controller will be mapped a method that related to HTTP (PUT, DELETE).
See this diagram to make you easily understand, how the REST work.
|struts.rest.handlerOverride.EXTENSION||The alias for the ContentTypeHandler implementation that handles the EXTENSION value||N/A||Any declared alias for a ContentTypeHandler implementation|
|struts.rest.defaultExtension||The default extension to use when none is explicitly specified in the request||xml||Any extension|
|struts.rest.validationFailureStatusCode||The HTTP status code to return on validation failure||400||Any HTTP status code as an integer|
|struts.rest.namespace||Optional parameter to specify namespace for REST services||/||eg. /rest|
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 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.
From Struts 2.1.1+