org.restlet.resource
Class Resource

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

public class Resource
extends Handler

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.

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 acceptRepresentation(Representation) for POST processing, storeRepresentation(Representation) for PUT processing or removeRepresentations() for DELETE processing.

The common GET method is supported by the modifiable "variants" list property and the represent(Variant) method. This allows an easy and cheap declaration of the available variants, in the constructor for example. Then the creation of costly representations is delegated to the represent(Variant) method when actually needed.

Concurrency note: typically created by Routers, Resource instances are the final handlers of requests. Unlike the other processors in the Restlet chain, a Resource instance is not reused by several calls and is only invoked by one thread. Therefore, it doesn't have to be thread-safe.

Author:
Jerome Louvel, Thierry Boileau, Konstantin Laufer (laufer@cs.luc.edu)
See Also:
Source dissertation, Tutorial : Reaching target Resources, Representation, Finder

Constructor Summary
Resource()
          Special constructor used by IoC frameworks.
Resource(Context context, Request request, Response response)
          Normal constructor.
 
Method Summary
 void acceptRepresentation(Representation entity)
          Accepts and processes a representation posted to the resource.
 boolean allowDelete()
          Indicates if DELETE calls are allowed by checking the "modifiable" property.
 boolean allowGet()
          Indicates if GET calls are allowed by checking the "readable" property.
 boolean allowPost()
          Indicates if POST calls are allowed by checking the "modifiable" property.
 boolean allowPut()
          Indicates if PUT calls are allowed by checking the "modifiable" property.
 void delete()
          Deprecated. Use the removeRepresentations() method instead.
 Representation getPreferredRepresentation()
          Deprecated. Use the represent() method instead.
 Variant getPreferredVariant()
          Returns the preferred variant according to the client preferences specified in the request.
 Representation getRepresentation(Variant variant)
          Deprecated. Use the represent(Variant) method instead.
 java.util.List<Variant> getVariants()
          Returns the modifiable list of variants.
 void handleDelete()
          Handles a DELETE call by invoking the removeRepresentations() method.
 void handleGet()
          Handles a GET call by automatically returning the best representation available.
 void handlePost()
          Handles a POST call by invoking the acceptRepresentation(Representation) method.
 void handlePut()
          Handles a PUT call by invoking the storeRepresentation(Representation) method.
 void init(Context context, Request request, Response response)
          Initialize the resource with its context.
 boolean isAvailable()
          Indicates if the resource is actually available.
 boolean isModifiable()
          Indicates if the representations can be modified via the handlePost(), the handlePut() or the handleDelete() methods.
 boolean isNegotiateContent()
          Indicates if the best content is automatically negotiated.
 boolean isReadable()
          Indicates if the representations can be read via the handleGet() method.
 void post(Representation entity)
          Deprecated. Use the acceptRepresentation(Representation) method instead.
 void put(Representation entity)
          Deprecated. Use the storeRepresentation(Representation) method instead.
 void removeRepresentations()
          Removes all the representations of the resource and effectively the resource itself.
 Representation represent()
          Returns the preferred representation according to the client preferences specified in the request.
 Representation represent(Variant variant)
          Returns a full representation for a given variant previously returned via the getVariants() method.
 void setAvailable(boolean available)
          Indicates if the resource is actually available.
 void setModifiable(boolean modifiable)
          Indicates if the representations can be modified via the handlePost(), the handlePut() or the handleDelete() methods.
 void setNegotiateContent(boolean negotiateContent)
          Indicates if the returned representation is automatically negotiated.
 void setReadable(boolean readable)
          Indicates if the representations can be read via the handleGet() method.
 void setVariants(java.util.List<Variant> variants)
          Sets the modifiable list of variants.
 void storeRepresentation(Representation entity)
          Stores a representation put to the resource and replaces all existing representations of the resource.
 
Methods inherited from class org.restlet.Handler
allowHead, allowOptions, generateRef, getAllowedMethods, getApplication, getContext, getLogger, getMatrix, getQuery, getRequest, getResponse, handleHead, handleOptions, setContext, setRequest, setResponse, updateAllowedMethods
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

Resource

public Resource()
Special constructor used by IoC frameworks. Note that the init() method MUST be invoked right after the creation of the handler in order to keep a behavior consistent with the normal three arguments constructor.


Resource

public Resource(Context context,
                Request request,
                Response response)
Normal constructor. This constructor will invoke the parent constructor by default.

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

acceptRepresentation

public void acceptRepresentation(Representation entity)
                          throws ResourceException
Accepts and processes a representation posted to the resource. The default behavior is to set the response status to Status.SERVER_ERROR_INTERNAL.

This is the higher-level method that let you process POST requests.

Parameters:
entity - The posted entity.
Throws:
ResourceException

allowDelete

public boolean allowDelete()
Indicates if DELETE calls are allowed by checking the "modifiable" property.

Overrides:
allowDelete in class Handler
Returns:
True if the method is allowed.

allowGet

public boolean allowGet()
Indicates if GET calls are allowed by checking the "readable" property.

Overrides:
allowGet in class Handler
Returns:
True if the method is allowed.

allowPost

public boolean allowPost()
Indicates if POST calls are allowed by checking the "modifiable" property.

Overrides:
allowPost in class Handler
Returns:
True if the method is allowed.

allowPut

public boolean allowPut()
Indicates if PUT calls are allowed by checking the "modifiable" property.

Overrides:
allowPut in class Handler
Returns:
True if the method is allowed.

delete

@Deprecated
public void delete()
Deprecated. Use the removeRepresentations() method instead.

Asks the resource to delete itself and all its representations.The default behavior is to invoke the removeRepresentations() method.


getPreferredRepresentation

@Deprecated
public Representation getPreferredRepresentation()
Deprecated. Use the represent() method instead.

Returns the preferred representation according to the client preferences specified in the request.

Returns:
The preferred representation.
See Also:
getPreferredVariant()

getPreferredVariant

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

Returns:
The preferred variant.

getRepresentation

@Deprecated
public Representation getRepresentation(Variant variant)
Deprecated. Use the represent(Variant) method instead.

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()

getVariants

public java.util.List<Variant> getVariants()
Returns the modifiable list of variants. Creates a new instance if no one has been set. 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 may reconstruct the list for each call which can be expensive.

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

handleDelete

public void handleDelete()
Handles a DELETE call by invoking the removeRepresentations() method. It also automatically support conditional DELETEs.

Overrides:
handleDelete in class Handler

handleGet

public void handleGet()
Handles a GET call by automatically returning the best representation available. The content negotiation is automatically supported based on the client's preferences available in the request. This feature can be turned off using the "negotiateContent" property.

If the resource's "available" property is set to false, the method immediately returns with a Status.CLIENT_ERROR_NOT_FOUND status.

The negotiated representation is obtained by calling the getPreferredVariant(). If a variant is sucessfully selected, then the represent(Variant) method is called to get the actual representation corresponding to the metadata in the variant.

If no variant matching the client preferences is available, the response status is set to Status.CLIENT_ERROR_NOT_ACCEPTABLE and the list of available representations is returned in the response entity as a textual list of URIs (only if the variants have an identifier properly set).

If the content negotiation is turned off and only one variant is defined in the "variants" property, then its representation is returned by calling the represent(Variant) method. If several variants are available, then the list of available representations is returned in the response entity as a textual list of URIs (only if the variants have an identifier properly set).

If no variant is defined in the "variants" property, the response status is set to Status.CLIENT_ERROR_NOT_FOUND.
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. Conditional GETs are also automatically supported.

Overrides:
handleGet in class Handler

handlePost

public void handlePost()
Handles a POST call by invoking the acceptRepresentation(Representation) method. It also logs a trace if there is no entity posted.

Overrides:
handlePost in class Handler

handlePut

public void handlePut()
Handles a PUT call by invoking the storeRepresentation(Representation) method. It also handles conditional PUTs and forbids partial PUTs as they are not supported yet. Finally, it prevents PUT with no entity by setting the response status to Status.CLIENT_ERROR_BAD_REQUEST following the HTTP specifications.

Overrides:
handlePut in class Handler

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.

Overrides:
init in class Handler
Parameters:
context - The parent context.
request - The request to handle.
response - The response to return.

isAvailable

public boolean isAvailable()
Indicates if the resource is actually available. By default this property is true but it can be set to false if the resource doesn't exist at all or if it isn't visible to a specific client. The handleGet() method will set the response's status to Status.CLIENT_ERROR_NOT_FOUND if this property is false.

Returns:
True if the resource is available.

isModifiable

public boolean isModifiable()
Indicates if the representations can be modified via the handlePost(), the handlePut() or the handleDelete() methods.

Returns:
True if representations can be modified.

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.

isReadable

public boolean isReadable()
Indicates if the representations can be read via the handleGet() method.

Returns:
True if the representations can be read.

post

@Deprecated
public void post(Representation entity)
Deprecated. Use the acceptRepresentation(Representation) method instead.

Posts a representation to the resource. The default behavior is to invoke the acceptRepresentation(Representation) method.

Parameters:
entity - The representation posted.

put

@Deprecated
public void put(Representation entity)
Deprecated. Use the storeRepresentation(Representation) method instead.

Puts a representation in the resource. The default behavior is to invoke the storeRepresentation(Representation) method.

Parameters:
entity - The representation put.

removeRepresentations

public void removeRepresentations()
                           throws ResourceException
Removes all the representations of the resource and effectively the resource itself. The default behavior is to set the response status to Status.SERVER_ERROR_INTERNAL.

This is the higher-level method that let you process DELETE requests.

Throws:
ResourceException

represent

public Representation represent()
                         throws ResourceException
Returns the preferred representation according to the client preferences specified in the request. By default it calls the represent(Variant) method with the preferred variant returned by getPreferredVariant().

Returns:
The preferred representation.
Throws:
ResourceException
See Also:
getPreferredVariant()

represent

public Representation represent(Variant variant)
                         throws ResourceException
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 initialize 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.
Throws:
ResourceException
See Also:
getVariants()

setAvailable

public void setAvailable(boolean available)
Indicates if the resource is actually available. By default this property is true but it can be set to false if the resource doesn't exist at all or if it isn't visible to a specific client. The handleGet() method will set the response's status to Status.CLIENT_ERROR_NOT_FOUND if this property is false.

Parameters:
available - True if the resource is actually available.

setModifiable

public void setModifiable(boolean modifiable)
Indicates if the representations can be modified via the handlePost(), the handlePut() or the handleDelete() methods.

Parameters:
modifiable - Indicates if the representations can be modified.

setNegotiateContent

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

Parameters:
negotiateContent - True if content negotiation is enabled.

setReadable

public void setReadable(boolean readable)
Indicates if the representations can be read via the handleGet() method.

Parameters:
readable - Indicates if the representations can be read.

setVariants

public void setVariants(java.util.List<Variant> variants)
Sets the modifiable list of variants.

Parameters:
variants - The modifiable list of variants.

storeRepresentation

public void storeRepresentation(Representation entity)
                         throws ResourceException
Stores a representation put to the resource and replaces all existing representations of the resource. If the resource doesn't exist yet, it should create it and use the entity as its initial representation. The default behavior is to set the response status to Status.SERVER_ERROR_INTERNAL.

This is the higher-level method that let you process PUT requests.

Parameters:
entity -
Throws:
ResourceException


Copyright © 2005-2008 Noelios Technologies.