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
`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`