|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Objectorg.restlet.resource.Resource
public class Resource
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.
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 |
---|
public Resource()
public Resource(Context context, Request request, Response response)
context
- The parent context.request
- The request to handle.response
- The response to return.Method Detail |
---|
public boolean allowDelete()
public boolean allowGet()
public boolean allowPost()
public boolean allowPut()
public void delete()
public Reference generateRef(String uriTemplate)
uriTemplate
- The URI template to use for generation.
public Context getContext()
public Logger getLogger()
public Representation getPreferredRepresentation()
public Variant getPreferredVariant()
public Representation getRepresentation(Variant variant)
variant
- The variant whose full representation must be returned.
getVariants()
public Request getRequest()
public Response getResponse()
public List<Variant> getVariants()
getRepresentation(Variant)
public void handleDelete()
public void handleGet()
public void handleHead()
public void handleOptions()
public void handlePost()
public void handlePut()
public void init(Context context, Request request, Response response)
context
- The parent context.request
- The request to handle.response
- The response to return.public boolean isNegotiateContent()
public void post(Representation entity)
entity
- The posted entity.public void put(Representation entity)
entity
- A new or updated representation.public void setContext(Context context)
context
- The parent context.public void setNegotiateContent(boolean negotiateContent)
negotiateContent
- True if the best content is automatically negotiated.public void setRequest(Request request)
request
- The request to handle.public void setResponse(Response response)
response
- The response to update.
|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |