| java.lang.Object
 org.restlet.resource.Resource
All known Subclasses: com.noelios.restlet.local.DirectoryResource, org.restlet.example.book.rest.ch7.UserResource, org.restlet.example.tutorial.UserResource,
| Resource | | public class Resource (Code) | | 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
Resource.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
Resource.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.
See Also: Source
* dissertation
See Also: Tutorial: Reaching
* target Resources
See Also: org.restlet.resource.Representation
See Also: org.restlet.Finder
author:
Jerome Louvel (contact@noelios.com)
author:
Thierry Boileau (thboileau@gmail.com) |
| Method Summary | |
| public boolean | allowDelete()
Indicates if it is allowed to delete the resource. | | public boolean | allowGet()
Indicates if it is allowed to get the variants. | | public boolean | allowPost()
Indicates if it is allowed to post to the resource. | | public boolean | allowPut()
Indicates if it is allowed to put to the resource. | | public void | delete()
Asks the resource to delete itself and all its representations. | | public Reference | generateRef(String uriTemplate)
Generates a reference based on a template URI. | | public Context | getContext()
Returns the context. | | public Logger | getLogger()
Returns the logger to use. | | public Representation | getPreferredRepresentation()
Returns the preferred representation according to the client preferences
specified in the associated request. | | public Variant | getPreferredVariant()
Returns the preferred variant according to the client preferences
specified in the associated request. | | public Representation | getRepresentation(Variant variant)
Returns a full representation for a given variant previously returned via
the getVariants() method. | | public Request | getRequest()
Returns the request. | | public Response | getResponse()
Returns the response. | | public List<Variant> | getVariants()
Returns the modifiable list of variants. | | public void | handleDelete()
Handles a DELETE call invoking the 'delete' method of the target resource
(as provided by the 'findTarget' method). | | public void | handleGet()
Handles a GET call by automatically returning the best entity available
from the target resource (as provided by the 'findTarget' method). | | public void | handleHead()
Handles a HEAD call, using a logic similar to the handleGet method. | | public void | handleOptions()
Handles an OPTIONS call introspecting the target resource (as provided by
the 'findTarget' method). | | public void | handlePost()
Handles a POST call invoking the 'post' method of the target resource (as
provided by the 'findTarget' method). | | public void | handlePut()
Handles a PUT call invoking the 'put' method of the target resource (as
provided by the 'findTarget' method). | | public void | init(Context context, Request request, Response response)
Initialize the resource with its context. | | public boolean | isNegotiateContent()
Indicates if the best content is automatically negotiated. | | public void | post(Representation entity)
Posts a representation to the resource. | | public void | put(Representation entity)
Puts a representation in the resource. | | public void | setContext(Context context)
Sets the parent context. | | public void | setNegotiateContent(boolean negotiateContent)
Indicates if the best content is automatically negotiated. | | public void | setRequest(Request request)
Sets the request to handle. | | public void | setResponse(Response response)
Sets the response to update. |
| Resource | | public Resource()(Code) | | 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)(Code) | | Constructor. This constructor will invoke the init() method by default.
Parameters:
context - The parent context.
Parameters:
request - The request to handle.
Parameters:
response - The response to return. |
| allowDelete | | public boolean allowDelete()(Code) | | Indicates if it is allowed to delete the resource. The default value is
false.
True if the method is allowed. |
| allowGet | | public boolean allowGet()(Code) | | Indicates if it is allowed to get the variants. The default value is
true.
True if the method is allowed. |
| allowPost | | public boolean allowPost()(Code) | | Indicates if it is allowed to post to the resource. The default value is
false.
True if the method is allowed. |
| allowPut | | public boolean allowPut()(Code) | | Indicates if it is allowed to put to the resource. The default value is
false.
True if the method is allowed. |
| delete | | public void delete()(Code) | | Asks the resource to delete itself and all its representations.
|
| generateRef | | public Reference generateRef(String uriTemplate)(Code) | | 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. The generated reference. |
| getContext | | public Context getContext()(Code) | | Returns the context.
The context. |
| getLogger | | public Logger getLogger()(Code) | | Returns the logger to use.
The logger to use. |
| getPreferredRepresentation | | public Representation getPreferredRepresentation()(Code) | | Returns the preferred representation according to the client preferences
specified in the associated request.
The preferred representation. |
| getPreferredVariant | | public Variant getPreferredVariant()(Code) | | Returns the preferred variant according to the client preferences
specified in the associated request.
The preferred variant. |
| getRepresentation | | public Representation getRepresentation(Variant variant)(Code) | | 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. The full representation for the variant.
See Also: Resource.getVariants() |
| getRequest | | public Request getRequest()(Code) | | Returns the request.
the request. |
| getResponse | | public Response getResponse()(Code) | | Returns the response.
the response. |
| getVariants | | public List<Variant> getVariants()(Code) | | 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.
The list of variants.
See Also: Resource.getRepresentation(Variant) |
| handleDelete | | public void handleDelete()(Code) | | Handles a DELETE call invoking the 'delete' method of the target resource
(as provided by the 'findTarget' method).
|
| handleGet | | public void handleGet()(Code) | | 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()(Code) | | Handles a HEAD call, using a logic similar to the handleGet method.
|
| handleOptions | | public void handleOptions()(Code) | | Handles an OPTIONS call introspecting the target resource (as provided by
the 'findTarget' method).
|
| handlePost | | public void handlePost()(Code) | | Handles a POST call invoking the 'post' method of the target resource (as
provided by the 'findTarget' method).
|
| handlePut | | public void handlePut()(Code) | | 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)(Code) | | 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.
Parameters:
request - The request to handle.
Parameters:
response - The response to return. |
| isNegotiateContent | | public boolean isNegotiateContent()(Code) | | Indicates if the best content is automatically negotiated. Default value
is true.
True if the best content is automatically negotiated. |
| post | | public void post(Representation entity)(Code) | | Posts a representation to the resource.
Parameters:
entity - The posted entity. |
| put | | public void put(Representation entity)(Code) | | Puts a representation in the resource.
Parameters:
entity - A new or updated representation. |
| setContext | | public void setContext(Context context)(Code) | | Sets the parent context.
Parameters:
context - The parent context. |
| setNegotiateContent | | public void setNegotiateContent(boolean negotiateContent)(Code) | | 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)(Code) | | Sets the request to handle.
Parameters:
request - The request to handle. |
| setResponse | | public void setResponse(Response response)(Code) | | Sets the response to update.
Parameters:
response - The response to update. |
|
|