|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Objectorg.restlet.Handler
org.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.
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.
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 |
---|
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 void acceptRepresentation(Representation entity) throws ResourceException
Status.SERVER_ERROR_INTERNAL
.
entity
- The posted entity.
ResourceException
public boolean allowDelete()
allowDelete
in class Handler
public boolean allowGet()
allowGet
in class Handler
public boolean allowPost()
allowPost
in class Handler
public boolean allowPut()
allowPut
in class Handler
@Deprecated public void delete()
removeRepresentations()
method instead.
removeRepresentations()
method.
@Deprecated public Representation getPreferredRepresentation()
represent()
method instead.
getPreferredVariant()
public Variant getPreferredVariant()
@Deprecated public Representation getRepresentation(Variant variant)
represent(Variant)
method instead.
variant
- The variant whose full representation must be returned.
getVariants()
public java.util.List<Variant> getVariants()
getRepresentation(Variant)
public void handleDelete()
removeRepresentations()
method. It also automatically support conditional DELETEs.
handleDelete
in class Handler
public void handleGet()
Status.CLIENT_ERROR_NOT_FOUND
status.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.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).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).Status.CLIENT_ERROR_NOT_FOUND
.
handleGet
in class Handler
public void handlePost()
acceptRepresentation(Representation)
method. It also logs a
trace if there is no entity posted.
handlePost
in class Handler
public void handlePut()
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.
handlePut
in class Handler
public void init(Context context, Request request, Response response)
init
in class Handler
context
- The parent context.request
- The request to handle.response
- The response to return.public boolean isAvailable()
handleGet()
method will set the response's status to
Status.CLIENT_ERROR_NOT_FOUND
if this property is false.
public boolean isModifiable()
handlePost()
, the handlePut()
or the
handleDelete()
methods.
public boolean isNegotiateContent()
public boolean isReadable()
handleGet()
method.
@Deprecated public void post(Representation entity)
acceptRepresentation(Representation)
method
instead.
acceptRepresentation(Representation)
method.
entity
- The representation posted.@Deprecated public void put(Representation entity)
storeRepresentation(Representation)
method
instead.
storeRepresentation(Representation)
method.
entity
- The representation put.public void removeRepresentations() throws ResourceException
Status.SERVER_ERROR_INTERNAL
.
ResourceException
public Representation represent() throws ResourceException
represent(Variant)
method with the preferred variant returned by
getPreferredVariant()
.
ResourceException
getPreferredVariant()
public Representation represent(Variant variant) throws ResourceException
variant
- The variant whose full representation must be returned.
ResourceException
getVariants()
public void setAvailable(boolean available)
handleGet()
method will set the response's status to
Status.CLIENT_ERROR_NOT_FOUND
if this property is false.
available
- True if the resource is actually available.public void setModifiable(boolean modifiable)
handlePost()
, the handlePut()
or the
handleDelete()
methods.
modifiable
- Indicates if the representations can be modified.public void setNegotiateContent(boolean negotiateContent)
negotiateContent
- True if content negotiation is enabled.public void setReadable(boolean readable)
handleGet()
method.
readable
- Indicates if the representations can be read.public void setVariants(java.util.List<Variant> variants)
variants
- The modifiable list of variants.public void storeRepresentation(Representation entity) throws ResourceException
Status.SERVER_ERROR_INTERNAL
.
entity
-
ResourceException
|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |