org.restlet.resource
Class Resource

java.lang.Object
  extended by org.restlet.resource.Resource

public class Resource
extends Object

Intended conceptual target of a hypertext reference. "Any information that can be named can be a resource: a document or image, a temporal service (e.g. "today's weather in Los Angeles"), a collection of other resources, a non-virtual object (e.g. a person), and so on. In other words, any concept that might be the target of an author's hypertext reference must fit within the definition of a resource. The only thing that is required to be static for a resource is the semantics of the mapping, since the semantics is what distinguishes one resource from another." Roy T. Fielding

Another definition adapted from the URI standard (RFC 3986): a resource is the conceptual mapping to a representation (also known as entity) or set of representations, not necessarily the representation which corresponds to that mapping at any particular instance in time. Thus, a resource can remain constant even when its content (the representations to which it currently corresponds) changes over time, provided that the conceptual mapping is not changed in the process. In addition, a resource is always identified by a URI.

Typically created by Finders, Resource instances are the final handlers of calls received by server connectors. Unlike the other handlers in the processing chain, a Resource is generally not shared between calls and doesn't have to be thread-safe. This is the point where the RESTful view of your Web application can be integrated with your domain objects. Those domain objects can be implemented using any technology, relational databases, object databases, transactional components like EJB, etc. You just have to extend this class to override the REST methods you want to support like post(), put() or delete(). The common GET method is supported by the modifiable "variants" list property and the getRepresentation(Variant) method. This allows an easy and cheap declaration of the available variants in the constructor for example, then the on-demand creation of costly representations via the getRepresentation(Variant) method.

At a lower level, you have a handle*(Request,Response) method for each REST method that is supported by the Resource, where the '*' is replaced by the method name. The Finder handler for example, will be able to dynamically dispatch a call to the appropriate handle*() method. Most common REST methods like GET, POST, PUT and DELETE have default implementations that pre-handle calls to do content negotiation for example, based on the higher-level methods that we discussed previously. For example if you want to support a MOVE method, just add an handleMove(Request,Response) method and it will be detected automatically by a Finder handler.

Finally, you need to declare which REST methods are allowed by your Resource by overiding the matching allow*() method. By default, allowGet() returns true, but all other allow*() methods will return false. Therefore, if you want to support the DELETE method, just override allowDelete() and return true. Again, a previous Finder handler will be able to detect this method and know whether or not your Resource should be invoked. It is also used by the handleOptions() method to return the list of allowed methods.

Author:
Jerome Louvel (contact@noelios.com), Thierry Boileau (thboileau@gmail.com)
See Also:
Source dissertation, Tutorial: Reaching target Resources, Representation, Finder

Constructor Summary
Resource()
          Default constructor.
Resource(Context context, Request request, Response response)
          Constructor.
 
Method Summary
 boolean allowDelete()
          Indicates if it is allowed to delete the resource.
 boolean allowGet()
          Indicates if it is allowed to get the variants.
 boolean allowPost()
          Indicates if it is allowed to post to the resource.
 boolean allowPut()
          Indicates if it is allowed to put to the resource.
 void delete()
          Asks the resource to delete itself and all its representations.
 Reference generateRef(String uriTemplate)
          Generates a reference based on a template URI.
 Context getContext()
          Returns the context.
 Logger getLogger()
          Returns the logger to use.
 Representation getPreferredRepresentation()
          Returns the preferred representation according to the client preferences specified in the associated request.
 Variant getPreferredVariant()
          Returns the preferred variant according to the client preferences specified in the associated request.
 Representation getRepresentation(Variant variant)
          Returns a full representation for a given variant previously returned via the getVariants() method.
 Request getRequest()
          Returns the request.
 Response getResponse()
          Returns the response.
 List<Variant> getVariants()
          Returns the modifiable list of variants.
 void handleDelete()
          Handles a DELETE call invoking the 'delete' method of the target resource (as provided by the 'findTarget' method).
 void handleGet()
          Handles a GET call by automatically returning the best entity available from the target resource (as provided by the 'findTarget' method).
 void handleHead()
          Handles a HEAD call, using a logic similar to the handleGet method.
 void handleOptions()
          Handles an OPTIONS call introspecting the target resource (as provided by the 'findTarget' method).
 void handlePost()
          Handles a POST call invoking the 'post' method of the target resource (as provided by the 'findTarget' method).
 void handlePut()
          Handles a PUT call invoking the 'put' method of the target resource (as provided by the 'findTarget' method).
 void init(Context context, Request request, Response response)
          Initialize the resource with its context.
 boolean isNegotiateContent()
          Indicates if the best content is automatically negotiated.
 void post(Representation entity)
          Posts a representation to the resource.
 void put(Representation entity)
          Puts a representation in the resource.
 void setContext(Context context)
          Sets the parent context.
 void setNegotiateContent(boolean negotiateContent)
          Indicates if the best content is automatically negotiated.
 void setRequest(Request request)
          Sets the request to handle.
 void setResponse(Response response)
          Sets the response to update.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

Resource

public Resource()
Default constructor. Note that the init() method must be invoked right after the creation of the resource.


Resource

public Resource(Context context,
                Request request,
                Response response)
Constructor. This constructor will invoke the init() method by default.

Parameters:
context - The parent context.
request - The request to handle.
response - The response to return.
Method Detail

allowDelete

public boolean allowDelete()
Indicates if it is allowed to delete the resource. The default value is false.

Returns:
True if the method is allowed.

allowGet

public boolean allowGet()
Indicates if it is allowed to get the variants. The default value is true.

Returns:
True if the method is allowed.

allowPost

public boolean allowPost()
Indicates if it is allowed to post to the resource. The default value is false.

Returns:
True if the method is allowed.

allowPut

public boolean allowPut()
Indicates if it is allowed to put to the resource. The default value is false.

Returns:
True if the method is allowed.

delete

public void delete()
Asks the resource to delete itself and all its representations.


generateRef

public Reference generateRef(String uriTemplate)
Generates a reference based on a template URI. Note that you can leverage all the variables defined in the Template class as they will be resolved using the resource's request and response properties.

Parameters:
uriTemplate - The URI template to use for generation.
Returns:
The generated reference.

getContext

public Context getContext()
Returns the context.

Returns:
The context.

getLogger

public Logger getLogger()
Returns the logger to use.

Returns:
The logger to use.

getPreferredRepresentation

public Representation getPreferredRepresentation()
Returns the preferred representation according to the client preferences specified in the associated request.

Returns:
The preferred representation.

getPreferredVariant

public Variant getPreferredVariant()
Returns the preferred variant according to the client preferences specified in the associated request.

Returns:
The preferred variant.

getRepresentation

public Representation getRepresentation(Variant variant)
Returns a full representation for a given variant previously returned via the getVariants() method. The default implementation directly returns the variant in case the variants are already full representations. In all other cases, you will need to override this method in order to provide your own implementation.

This method is very useful for content negotiation when it is too costly to initilize all the potential representations. It allows a resource to simply expose the available variants via the getVariants() method and to actually server the one selected via this method.

Parameters:
variant - The variant whose full representation must be returned.
Returns:
The full representation for the variant.
See Also:
getVariants()

getRequest

public Request getRequest()
Returns the request.

Returns:
the request.

getResponse

public Response getResponse()
Returns the response.

Returns:
the response.

getVariants

public List<Variant> getVariants()
Returns the modifiable list of variants. A variant can be a purely descriptive representation, with no actual content that can be served. It can also be a full representation in case a resource has only one variant or if the initialization cost is very low.

Note that the order in which the variants are inserted in the list matters. For example, if the client has no preference defined, or if the acceptable variants have the same quality level for the client, the first acceptable variant in the list will be returned.

It is recommended to not override this method and to simply use it at construction time to initialize the list of available variants. Overriding it will force you to reconstruct the list for each call which is expensive.

Returns:
The list of variants.
See Also:
getRepresentation(Variant)

handleDelete

public void handleDelete()
Handles a DELETE call invoking the 'delete' method of the target resource (as provided by the 'findTarget' method).


handleGet

public void handleGet()
Handles a GET call by automatically returning the best entity available from the target resource (as provided by the 'findTarget' method). The content negotiation is based on the client's preferences available in the handled call and can be turned off using the "negotiateContent" property. If it is disabled and multiple variants are available for the target resource, then a 300 (Multiple Choices) status will be returned with the list of variants URI if available.


handleHead

public void handleHead()
Handles a HEAD call, using a logic similar to the handleGet method.


handleOptions

public void handleOptions()
Handles an OPTIONS call introspecting the target resource (as provided by the 'findTarget' method).


handlePost

public void handlePost()
Handles a POST call invoking the 'post' method of the target resource (as provided by the 'findTarget' method).


handlePut

public void handlePut()
Handles a PUT call invoking the 'put' method of the target resource (as provided by the 'findTarget' method).


init

public void init(Context context,
                 Request request,
                 Response response)
Initialize the resource with its context. If you override this method, make sure that you don't forget to call super.init() first, otherwise your Resource won't behave properly.

Parameters:
context - The parent context.
request - The request to handle.
response - The response to return.

isNegotiateContent

public boolean isNegotiateContent()
Indicates if the best content is automatically negotiated. Default value is true.

Returns:
True if the best content is automatically negotiated.

post

public void post(Representation entity)
Posts a representation to the resource.

Parameters:
entity - The posted entity.

put

public void put(Representation entity)
Puts a representation in the resource.

Parameters:
entity - A new or updated representation.

setContext

public void setContext(Context context)
Sets the parent context.

Parameters:
context - The parent context.

setNegotiateContent

public void setNegotiateContent(boolean negotiateContent)
Indicates if the best content is automatically negotiated. Default value is true.

Parameters:
negotiateContent - True if the best content is automatically negotiated.

setRequest

public void setRequest(Request request)
Sets the request to handle.

Parameters:
request - The request to handle.

setResponse

public void setResponse(Response response)
Sets the response to update.

Parameters:
response - The response to update.


Copyright © 2005-2007 Noelios Technologies.