WARNING: you are not looking at the live version but at an older version.

Resource API refactoring

Requirements

Enhancement request

Related discussions

References

Analysis

Synthesis

  1. Client-side resources
  2. Server-side resources
  3. Dispatching of uniform method to matching Java method
  4. Extension methods (WebDAV, PATCH, etc.)
  5. Detection of available variants
  6. Dispatching to representation producing method based on selected variant
  7. Mapping between ResourceException and reponse status
  8. Automatic conversion between representations and objects (beans/pojos, common technical classes such as a DOM Document)
  9. Automatic validation of representations received
  10. Automatic validation of parameters received
  11. Client-side Restlet post-processing (eg. filters, routers, pre-authentication, cookie management, etc.)
  12. Server-side Restlet pre-processing (eg. filters, routers)
  13. WADL resources (client and server side)
  14. Atom resources (client and server side)
  15. RoR active resources (client and server side)
  16. .Net data services resources (client and server side)
  17. Database resources
  18. Support IoC frameworks (Spring and Guice)
  19. Support GWT

Design

  • Unified API in Restlet 1.2 between Restlet 1.1 Resource class and JAX-RS 1.0 annotations to provide the best of both worlds
  • Use subclassing for resources foundation
  • Limited use of annotations to simplify variants declaration and method dispatching
  • Each resource should be able to optionally wrap another resource (for WADL enrichment for example)
  • Think about using additional annotations in the WADL extension to describe a resource (either JAX-RS API or Restlet API resources)

Architecture

diagrams

Class diagram

Here is a tentative class design:

Resource design

Annotations

We could also define a set of method level annotations:

Annotation

Parameters

Description

Delete

Annotate methods that remove resources.

Get

value() : String[]

Annotate methods that represent a variant of a resource

Options

value() : String[]

Annotate methods that accept representations.

Post

value() : String[]

Annotate methods that accept representations.

Put

value() : String[]

Annotate methods that store representations.

Sample code

Here is how a sample resource would look like with the refactored API. Note that both extension names and full MIME type would be supported. Extensions can be updated via the MetadataService.

import java.io.InputStream;

import org.restlet.ext.atom.Feed;
import org.restlet.resource.Delete;
import org.restlet.resource.Get;
import org.restlet.resource.Post;
import org.restlet.resource.Put;
import org.restlet.resource.Representation;
import org.restlet.resource.ServerResource;
import org.w3c.dom.Document;

public class TestResource extends ServerResource {

    @Get("atom")
    public Feed toAtom() {
        // ...
        return null;
    }

    @Get("application/custom+xml")
    public Representation toXml() {
        // ...
        return null;
    }

    @Post("xml")
    public Representation accept(Document entity) {
        // ...
        return null;
    }

    @Put("atom")
    public void storeAtom(Feed feed) {
        // ...
    }

    @Put("application/custom+xml")
    public void storeXml(InputStream stream) {
        // ...
    }

    @Delete
    public void removeAll() {
        // ...
    }

}

What is nice is that we would keep the high-level terminology that we have in Restlet 1.1 (accept, store, etc.) but make it available in a more flexible and declarative way.   The new ServerResource would only have lower-level methods, but with a more flexible signature than in Restlet 1.1:

  • void handle()
  • get() : Representation
  • get(Variant) : Representation
  • head() : Representation
  • options() : Representation
  • options(Variant) : Representation
  • post(Representation) : Representation
  • put(Representation) : Representation
  • delete() : Representation

Implementation

Comments (0)