org.restlet.resource

## Class UniformResource

- java.lang.Object
- - org.restlet.resource.UniformResource

Direct Known Subclasses:
  ClientResource, ServerResource

    public abstract class UniformResource
    extends java.lang.Object

Base resource class exposing the uniform REST interface. Intended conceptual target of a hypertext reference. An uniform resource encapsulates a `Context`, a `Request` and a `Response`, corresponding to a specific target resource.
It also defines a precise life cycle. First, the instance is created and the final `init(Context, Request, Response)` method is invoked, with a chance for the developer to do some additional initialization by overriding the `doInit()` method.
Then, the abstract `handle()` method can be invoked. For concrete behavior, see the `ClientResource` and `ServerResource` subclasses. Note that the state of the resource can be changed several times and the `handle()` method called more than once, but always by the same thread.
Finally, the final `release()` method can be called to clean-up the resource, with a chance for the developer to do some additional clean-up by overriding the `doRelease()` method.
Note also that throwable raised such as `Error` and `Exception` can be caught in a single point by overriding the `doCatch(Throwable)` method.
"The central feature that distinguishes the REST architectural style from other network-based styles is its emphasis on a uniform interface between components. By applying the software engineering principle of generality to the component interface, the overall system architecture is simplified and the visibility of interactions is improved. Implementations are decoupled from the services they provide, which encourages independent evolvability." Roy T. Fielding
Concurrency note: contrary to the `Uniform` class and its main `Restlet` subclass where a single instance can handle several calls concurrently, one instance of `UniformResource` is created for each call handled and accessed by only one thread at a time.

Author:
  Jerome Louvel
See Also:
  Source dissertation

### Constructor Summary

Constructors
Constructor and Description
`UniformResource()`

### Method Summary

Methods
`protected void` `doCatch(java.lang.Throwable throwable)` Invoked when an error or an exception is caught during initialization, handling or releasing.
`protected void` `doInit()` Set-up method that can be overridden in order to initialize the state of the resource.
`protected void` `doRelease()` Clean-up method that can be overridden in order to release the state of the resource.
`java.util.Set<Method>` `getAllowedMethods()` Returns the set of methods allowed for the current client by the resource.
`Application` `getApplication()` Returns the parent application if it exists, or instantiates a new one if needed.
`java.util.List<ChallengeRequest>` `getChallengeRequests()` Returns the list of authentication requests sent by an origin server to a client.
`ChallengeResponse` `getChallengeResponse()` Returns the authentication response sent by a client to an origin server.
`ClientInfo` `getClientInfo()` Returns the client-specific information.
`Conditions` `getConditions()` Returns the modifiable conditions applying to this request.
`Context` `getContext()` Returns the current context.
`ConverterService` `getConverterService()` Returns the application's converter service or create a new one.
`Series<Cookie>` `getCookies()` Returns the modifiable series of cookies provided by the client.
`Series<CookieSetting>` `getCookieSettings()` Returns the modifiable series of cookie settings provided by the server.
`java.util.Set<Dimension>` `getDimensions()` Returns the modifiable set of selecting dimensions on which the response entity may vary.
`Reference` `getHostRef()` Returns the host reference.
`Reference` `getLocationRef()` Returns the reference that the client should follow for redirections or resource creations.
`java.util.logging.Logger` `getLogger()` Returns the logger.
`Form` `getMatrix()` Returns the resource reference's optional matrix.
`int` `getMaxForwards()` Returns the maximum number of intermediaries.
`MetadataService` `getMetadataService()` Returns the application's metadata service or create a new one.
`Method` `getMethod()` Returns the method.
`Reference` `getOriginalRef()` Returns the original reference as requested by the client.
`Protocol` `getProtocol()` Returns the protocol by first returning the resourceRef.schemeProtocol property if it is set, or the baseRef.schemeProtocol property otherwise.
`Form` `getQuery()` Returns the resource reference's optional query.
`java.util.List<Range>` `getRanges()` Returns the ranges to return from the target resource's representation.
`Reference` `getReference()` Returns the URI reference.
`Reference` `getReferrerRef()` Returns the referrer reference if available.
`Request` `getRequest()` Returns the handled request.
`java.util.Map<java.lang.String,java.lang.Object>` `getRequestAttributes()` Returns the request attributes.
`Representation` `getRequestEntity()` Returns the request entity representation.
`Response` `getResponse()` Returns the handled response.
`java.util.Map<java.lang.String,java.lang.Object>` `getResponseAttributes()` Returns the response attributes.
`Representation` `getResponseEntity()` Returns the response entity representation.
`Reference` `getRootRef()` Returns the application root reference.
`ServerInfo` `getServerInfo()` Returns the server-specific information.
`Status` `getStatus()` Returns the status.
`StatusService` `getStatusService()` Returns the application's status service or create a new one.
`abstract Representation` `handle()` Handles the call composed of the current context, request and response.
`void` `init(Context context, Request request, Response response)` Initialization method setting the environment of the current resource instance.
`boolean` `isConfidential()` Indicates if the message was or will be exchanged confidentially, for example via a SSL-secured connection.
`void` `release()` Releases the resource by calling `doRelease()`.
`void` `setRequest(Request request)` Sets the handled request.
`void` `setResponse(Response response)` Sets the handled response.
`protected <T> T` `toObject(Representation source, java.lang.Class<T> target)` Converts a representation into a Java object.
`protected Representation` `toRepresentation(java.lang.Object source, Variant target)` Converts an object into a representation based on client preferences.

### Methods inherited from class java.lang.Object

`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

### Constructor Detail

#### UniformResource

    public UniformResource()

### Method Detail

#### doCatch

    protected void doCatch(java.lang.Throwable throwable)

Invoked when an error or an exception is caught during initialization, handling or releasing. By default, updates the responses's status with the result of `StatusService.getStatus(Throwable, UniformResource)` .

Parameters:
  `throwable` - The caught error or exception.

#### doInit

    protected void doInit()
                   throws ResourceException

Set-up method that can be overridden in order to initialize the state of the resource. By default it does nothing.

Throws:
  `ResourceException`
See Also:
  `init(Context, Request, Response)`

#### doRelease

    protected void doRelease()
                      throws ResourceException

Clean-up method that can be overridden in order to release the state of the resource. By default it does nothing.

Throws:
  `ResourceException`
See Also:
  `release()`

#### getAllowedMethods

    public java.util.Set<Method> getAllowedMethods()

Returns the set of methods allowed for the current client by the resource. The result can vary based on the client's user agent, authentication and authorization data provided by the client.

Returns:
  The set of allowed methods.

#### getApplication

    public Application getApplication()

Returns the parent application if it exists, or instantiates a new one if needed.

Returns:
  The parent application if it exists, or a new one.

#### getChallengeRequests

    public java.util.List<ChallengeRequest> getChallengeRequests()

Returns the list of authentication requests sent by an origin server to a client. If none is available, an empty list is returned.

Returns:
  The list of authentication requests.
See Also:
  `Response.getChallengeRequests()`

#### getChallengeResponse

    public ChallengeResponse getChallengeResponse()

Returns the authentication response sent by a client to an origin server.

Returns:
  The authentication response sent by a client to an origin server.
See Also:
  `Request.getChallengeResponse()`

#### getClientInfo

    public ClientInfo getClientInfo()

Returns the client-specific information. Creates a new instance if no one has been set.

Returns:
  The client-specific information.
See Also:
  `Request.getClientInfo()`

#### getConditions

    public Conditions getConditions()

Returns the modifiable conditions applying to this request. Creates a new instance if no one has been set.

Returns:
  The conditions applying to this call.
See Also:
  `Request.getConditions()`

#### getContext

    public Context getContext()

Returns the current context.

Returns:
  The current context.

#### getConverterService

    public ConverterService getConverterService()

Returns the application's converter service or create a new one.

Returns:
  The converter service.

#### getCookies

    public Series<Cookie> getCookies()

Returns the modifiable series of cookies provided by the client. Creates a new instance if no one has been set.

Returns:
  The cookies provided by the client.
See Also:
  `Request.getCookies()`

#### getCookieSettings

    public Series<CookieSetting> getCookieSettings()

Returns the modifiable series of cookie settings provided by the server. Creates a new instance if no one has been set.

Returns:
  The cookie settings provided by the server.
See Also:
  `Response.getCookieSettings()`

#### getDimensions

    public java.util.Set<Dimension> getDimensions()

Returns the modifiable set of selecting dimensions on which the response entity may vary. If some server-side content negotiation is done, this set should be properly updated, other it can be left empty. Creates a new instance if no one has been set.

Returns:
  The set of dimensions on which the response entity may vary.
See Also:
  `Response.getDimensions()`

#### getHostRef

    public Reference getHostRef()

Returns the host reference. This may be different from the resourceRef's host, for example for URNs and other URIs that don't contain host information.

Returns:
  The host reference.
See Also:
  `Request.getHostRef()`

#### getLocationRef

    public Reference getLocationRef()

Returns the reference that the client should follow for redirections or resource creations.

Returns:
  The redirection reference.
See Also:
  `Response.getLocationRef()`

#### getLogger

    public java.util.logging.Logger getLogger()

Returns the logger.

Returns:
  The logger.

#### getMatrix

    public Form getMatrix()

Returns the resource reference's optional matrix.

Returns:
  The resource reference's optional matrix.
See Also:
  `Reference.getMatrixAsForm()`

#### getMaxForwards

    public int getMaxForwards()

Returns the maximum number of intermediaries.

Returns:
  The maximum number of intermediaries.

#### getMetadataService

    public MetadataService getMetadataService()

Returns the application's metadata service or create a new one.

Returns:
  The metadata service.

#### getMethod

    public Method getMethod()

Returns the method.

Returns:
  The method.
See Also:
  `Request.getMethod()`

#### getOriginalRef

    public Reference getOriginalRef()

Returns the original reference as requested by the client. Note that this property is not used during request routing.

Returns:
  The original reference.
See Also:
  `Request.getOriginalRef()`

#### getProtocol

    public Protocol getProtocol()

Returns the protocol by first returning the resourceRef.schemeProtocol property if it is set, or the baseRef.schemeProtocol property otherwise.

Returns:
  The protocol or null if not available.
See Also:
  `Request.getProtocol()`

#### getQuery

    public Form getQuery()

Returns the resource reference's optional query.

Returns:
  The resource reference's optional query.
See Also:
  `Reference.getQueryAsForm()`

#### getRanges

    public java.util.List<Range> getRanges()

Returns the ranges to return from the target resource's representation.

Returns:
  The ranges to return.
See Also:
  `Request.getRanges()`

#### getReference

    public Reference getReference()

Returns the URI reference.

Returns:
  The URI reference.

#### getReferrerRef

    public Reference getReferrerRef()

Returns the referrer reference if available.

Returns:
  The referrer reference.

#### getRequest

    public Request getRequest()

Returns the handled request.

Returns:
  The handled request.

#### getRequestAttributes

    public java.util.Map<java.lang.String,java.lang.Object> getRequestAttributes()

Returns the request attributes.

Returns:
  The request attributes.
See Also:
  `Message.getAttributes()`

#### getRequestEntity

    public Representation getRequestEntity()

Returns the request entity representation.

Returns:
  The request entity representation.

#### getResponse

    public Response getResponse()

Returns the handled response.

Returns:
  The handled response.

#### getResponseAttributes

    public java.util.Map<java.lang.String,java.lang.Object> getResponseAttributes()

Returns the response attributes.

Returns:
  The response attributes.
See Also:
  `Message.getAttributes()`

#### getResponseEntity

    public Representation getResponseEntity()

Returns the response entity representation.

Returns:
  The response entity representation.

#### getRootRef

    public Reference getRootRef()

Returns the application root reference.

Returns:
  The application root reference.
See Also:
  `Request.getRootRef()`

#### getServerInfo

    public ServerInfo getServerInfo()

Returns the server-specific information. Creates a new instance if no one has been set.

Returns:
  The server-specific information.
See Also:
  `Response.getServerInfo()`

#### getStatus

    public Status getStatus()

Returns the status.

Returns:
  The status.
See Also:
  `Response.getStatus()`

#### getStatusService

    public StatusService getStatusService()

Returns the application's status service or create a new one.

Returns:
  The status service.

#### handle

    public abstract Representation handle()

Handles the call composed of the current context, request and response.

Returns:
  The optional response entity.

#### init

    public final void init(Context context,
            Request request,
            Response response)

Initialization method setting the environment of the current resource instance. It the calls the `doInit()` method that can be overridden.

Parameters:
  `context` - The current context.
  `request` - The handled request.
  `response` - The handled response.

#### isConfidential

    public boolean isConfidential()

Indicates if the message was or will be exchanged confidentially, for example via a SSL-secured connection.

Returns:
  True if the message is confidential.
See Also:
  `Request.isConfidential()`

#### release

    public final void release()

Releases the resource by calling `doRelease()`.

#### setRequest

    public void setRequest(Request request)

Sets the handled request.

Parameters:
  `request` - The handled request.

#### setResponse

    public void setResponse(Response response)

Sets the handled response.

Parameters:
  `response` - The handled response.

#### toObject

    protected <T> T toObject(Representation source,
                 java.lang.Class<T> target)
                  throws ResourceException

Converts a representation into a Java object. Leverages the `ConverterService`.

Type Parameters:
  `T` - The expected class of the Java object.
Parameters:
  `source` - The source representation to convert.
  `target` - The target class of the Java object.
Returns:
  The converted Java object.
Throws:
  `ResourceException`

#### toRepresentation

    protected Representation toRepresentation(java.lang.Object source,
                                  Variant target)

Converts an object into a representation based on client preferences.

Parameters:
  `source` - The object to convert.
  `target` - The target representation variant.
Returns:
  The wrapper representation.