Plugin is a way to extends functionality of {@link RestExpress} by adding pre/post/finally processor, serialization provider, declaring routes, etc..

Plugin interface:

public interface Plugin extends Comparable<Plugin> {

	/**
	 * Called to initialize this {@link Plugin}. Within this method,
	 * pre/post-processors can be created, as well as routes injected.
	 * 
	 * Take care if you need other {@link Plugin} that they can be not yet
	 * initialized. In this last case, do your initialization inside
	 * {@link #bind(RestExpress)}.
	 * 
	 * @param server
	 *            {@link RestExpress} instance
	 */
	public void initialize(RestExpress server);

	/**
	 * 
	 * Called during bind of {@link RestExpress}, after all resources have been
	 * allocated and/or initialized.
	 * 
	 * Within this method, this {@link Plugin} can access such details as route
	 * metadata, etc.
	 * 
	 * 
	 * @param server
	 *            the fully-bound RestExpress server.
	 */
	public void bind(RestExpress server);

	/**
	 * Called during RestExpress.shutdown() to release resources held by this
	 * {@link Plugin}.
	 */
	public void destroy(RestExpress server);

	/**
	 * High priority means that {@link Plugin} will be initialized later
	 * 
	 * @return priority level for loading order.
	 */
	public int priority();
}

This plugin adds caching-related headers to GET and HEAD responses.

For GET and HEAD requests, adds a Date: <timestamp> header, if not already present. This enables clients to determine age of a representation for caching purposes. Where <timestamp> is in RFC1123 full date format.

Note that while HEAD requests are provided with a Date header via this plugin. Most external caches forward HEAD requests to the origin server as a GET request and cache the result.

If the route has a Parameters.Cache.MAX_AGE parameter, whose value is the max-age in seconds then the following are added:

• Cache-Control: max-age=<seconds>
• Expires: now + max-age

If the route has a Flags.Cache.NO_CACHE flag, then the following headers are set on the response:

• Cache-Control: no-cache
• Pragma: no-cache

The MAX_AGE parameter takes precidence, in that, if present, the NO_CACHE flag is ignored.

If the response body is non-null, adds an ETag header. ETag is computed from the body object's hash code combined with the hash code of the resulting format (content-type).

NOTE: To fully support basic caching capability, also implement a LastModifiedHeaderPostprocessor() that inspects the date on your domain or presentation model and sets the 'Last-Modified' header.

Example Usage:

RestExpressService server = new RestExpressService();
...
new CacheControlPlugin()
    .register(server);
server.addPostprocessor(new LastModifiedHeaderProcessor());

An example LastModifiedHeaderPostprocessor:

public class LastModifiedHeaderPostprocessor
implements Postprocessor
{
	
    @Override
    public void process(MessageContext context) {
        if (!context.getRequest().isMethodGet())
            return;
        Response response = context.getResponse();
        if (!response.hasEntity())
            return;

        if (!response.hasHeader(HttpHeader.LAST_MODIFIED)) {
            Object body = response.getEntity();
            if (TimeStamped.class.isAssignableFrom(body.getClass())) {
                response.addHeader(HttpHeader.LAST_MODIFIED,
                        HttpDateTimeFormat.RFC_1123.format(((TimeStamped) body).updateAt()));
            }
        }

    }
}

Adds several routes within your service suite to facilitate auto-discovery of what's available.

Routes added are:

• /routes/metadata.{format} - to retrieve all metadata for all routes.
• /routes/{routeName}/metadata.{format} - to retrieve metadata for a named route.
• /routes - placeholder in HTML format to see all information in a classical browser

The plugin allows flags and parameters, just like the regular Route DSL to set flags and parameters on the routes created by the plugin so appropriate values are available in preprocessors, etc. For instance, if you want to turn off authentication or authorization for the metadata routes.

This plugins is present by default in restexpress-server.

Usage

Simply create a new plugin and register it with the RestExpress server, setting options as necessary, using method chaining if desired.

For example:

RestExpressService server = new RestExpressService()...

new RoutesPlugin()
	.flag("public-route")					// optional. Set a flag on the request for this route.
	.parameter("name", "value")				// optional. Set a parameter on the request for this route.
	.register(server);