org.restlet.resource

Class Resource

java.lang.Object

org.restlet.resource.Handler

org.restlet.resource.Resource

Deprecated.

Use the new ServerResource class instead.

@Deprecated
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, Representation, Finder

Constructor Summary

Constructors

Constructor and Description
Resource() Deprecated. Special constructor used by IoC frameworks.
Resource(Context context, Request request, Response response) Deprecated. Normal constructor.

Method Summary

Methods

Modifier and Type	Method and Description
void	acceptRepresentation(Representation entity) Deprecated. Accepts and processes a representation posted to the resource.
boolean	allowDelete() Deprecated. Indicates if DELETE calls are allowed by checking the "modifiable" property.
boolean	allowGet() Deprecated. Indicates if GET calls are allowed by checking the "readable" property.
boolean	allowPost() Deprecated. Indicates if POST calls are allowed by checking the "modifiable" property.
boolean	allowPut() Deprecated. Indicates if PUT calls are allowed by checking the "modifiable" property.
Variant	getPreferredVariant() Deprecated. Returns the preferred variant according to the client preferences specified in the request.
java.util.List<Variant>	getVariants() Deprecated. Returns the modifiable list of variants.
void	handleDelete() Deprecated. Handles a DELETE call by invoking the removeRepresentations() method.
void	handleGet() Deprecated. Handles a GET call by automatically returning the best representation available.
void	handlePost() Deprecated. Handles a POST call by invoking the acceptRepresentation(Representation) method.
void	handlePut() Deprecated. Handles a PUT call by invoking the storeRepresentation(Representation) method.
void	init(Context context, Request request, Response response) Deprecated. Initialize the resource with its context.
boolean	isAvailable() Deprecated. Indicates if the resource is actually available.
boolean	isModifiable() Deprecated. Indicates if the representations can be modified via the handlePost(), the handlePut() or the handleDelete() methods.
boolean	isNegotiateContent() Deprecated. Indicates if the best content is automatically negotiated.
boolean	isReadable() Deprecated. Indicates if the representations can be read via the handleGet() method.
void	removeRepresentations() Deprecated. Removes all the representations of the resource and effectively the resource itself.
Representation	represent() Deprecated. Returns the preferred representation according to the client preferences specified in the request.
Representation	represent(Variant variant) Deprecated. Returns a full representation for a given variant previously returned via the getVariants() method.
void	setAvailable(boolean available) Deprecated. Indicates if the resource is actually available.
void	setModifiable(boolean modifiable) Deprecated. Indicates if the representations can be modified via the handlePost(), the handlePut() or the handleDelete() methods.
void	setNegotiateContent(boolean negotiateContent) Deprecated. Indicates if the returned representation is automatically negotiated.
void	setReadable(boolean readable) Deprecated. Indicates if the representations can be read via the handleGet() method.
void	setVariants(java.util.List<Variant> variants) Deprecated. Sets the modifiable list of variants.
void	storeRepresentation(Representation entity) Deprecated. Stores a representation put to the resource and replaces all existing representations of the resource.

Methods inherited from class org.restlet.resource.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()

Deprecated.

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)

Deprecated.

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

Deprecated.

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

Deprecated.

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

Deprecated.

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

Deprecated.

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

Deprecated.

Indicates if PUT calls are allowed by checking the "modifiable" property.

Overrides:

allowPut in class Handler

Returns:

True if the method is allowed.

getPreferredVariant

public Variant getPreferredVariant()

Deprecated.

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

Returns:

The preferred variant.

getVariants

public java.util.List<Variant> getVariants()

Deprecated.

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:

represent(Variant)

handleDelete

public void handleDelete()

Deprecated.

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

Overrides:

handleDelete in class Handler

handleGet

public void handleGet()

Deprecated.

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

Deprecated.

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

Deprecated.

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)

Deprecated.

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

Deprecated.

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

Deprecated.

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

Deprecated.

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

Deprecated.

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

Returns:

True if the representations can be read.

removeRepresentations

public void removeRepresentations()
                           throws ResourceException

Deprecated.

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

Deprecated.

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

Deprecated.

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)

Deprecated.

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)

Deprecated.

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)

Deprecated.

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)

Deprecated.

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)

Deprecated.

Sets the modifiable list of variants.

Parameters:

variants - The modifiable list of variants.

storeRepresentation

public void storeRepresentation(Representation entity)
                         throws ResourceException

Deprecated.

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