Resource (Restlet API 2.4.4 - Java Standard Edition)

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

Direct Known Subclasses:

ClientResource, ServerResource
```
public abstract class Resource
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 init(Context, Request, Response) method is invoked. If you need to do some additional initialization, you should just override 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 Resource 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

Resource()

Constructors
Constructor and Description
`Resource()`

Method Summary

All Methods Static Methods Instance Methods Abstract Methods Concrete Methods
Modifier and Type	Method and Description
`protected void`	`doCatch(java.lang.Throwable throwable)` Invoked when a `Throwable` is caught during initialization, handling or releasing.
`protected void`	`doError(Status errorStatus)` Invoked when an error response status is received.
`protected void`	`doError(Status errorStatus, java.lang.String errorMessage)` Invoked when an error response status is received.
`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.
`abstract java.lang.String`	`getAttribute(java.lang.String name)` Returns the attribute value by looking up the given name in the request or response attributes maps.
`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.
`ConnegService`	`getConnegService()` Returns the application's content negotiation service or create a new one.
`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.
`java.lang.String`	`getMatrixValue(java.lang.String name)` Returns the first value of the matrix parameter given its name if existing, or null.
`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.
`java.util.List<ChallengeRequest>`	`getProxyChallengeRequests()` Returns the list of proxy authentication requests sent by an origin server to a client.
`ChallengeResponse`	`getProxyChallengeResponse()` Returns the proxy authentication response sent by a client to an origin server.
`Form`	`getQuery()` Returns the resource reference's optional query.
`java.lang.String`	`getQueryValue(java.lang.String name)` Returns the first value of the query parameter given its name if existing, or null.
`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.
`java.util.List<CacheDirective>`	`getRequestCacheDirectives()` Returns the request cache directives.
`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.
`java.util.List<CacheDirective>`	`getResponseCacheDirectives()` Returns the response cache directives.
`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.
`boolean`	`isLoggable()` Indicates if the call is loggable
`void`	`release()` Releases the resource by calling `doRelease()`.
`void`	`setApplication(Application application)` Sets the parent application.
`abstract void`	`setAttribute(java.lang.String name, java.lang.Object value)` Sets the request or response attribute value.
`void`	`setQueryValue(java.lang.String name, java.lang.String value)` Sets the query value for the named parameter.
`void`	`setRequest(Request request)` Sets the handled request.
`void`	`setResponse(Response response)` Sets the handled response.
`static java.lang.Boolean`	`toBoolean(java.lang.String value)` Converts the given `String` value into a `Boolean` or null.
`static java.lang.Byte`	`toByte(java.lang.String value)` Converts the given `String` value into a `Byte` or null.
`static java.lang.Double`	`toDouble(java.lang.String value)` Converts the given `String` value into an `Double` or null.
`static java.lang.Float`	`toFloat(java.lang.String value)` Converts the given `String` value into a `Float` or null.
`static java.lang.Integer`	`toInteger(java.lang.String value)` Converts the given `String` value into an `Integer` or null.
`static java.lang.Long`	`toLong(java.lang.String value)` Converts the given `String` value into an `Long` or null.
`<T> T`	`toObject(Representation source, java.lang.Class<T> target)` Converts a representation into a Java object.
`Representation`	`toRepresentation(java.lang.Object source)` Converts an object into a representation based on the default converter service variant.
`Representation`	`toRepresentation(java.lang.Object source, MediaType target)` Converts an object into a representation based on a given media type.
`Representation`	`toRepresentation(java.lang.Object source, Variant target)` Converts an object into a representation based on client preferences.
`static java.lang.Short`	`toShort(java.lang.String value)` Converts the given `String` value into a `Short` or null.
`java.lang.String`	`toString()`

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

- Constructor Detail
  - Resource
```
public Resource()
```
- Method Detail
  - toBoolean
```
public static java.lang.Boolean toBoolean(java.lang.String value)
```
    Converts the given String value into a Boolean or null.
    
    Parameters:
    
    value - The value to convert or null.
    
    Returns:
    
    The converted Boolean value or null.
  - toByte
```
public static java.lang.Byte toByte(java.lang.String value)
```
    Converts the given String value into a Byte or null.
    
    Parameters:
    
    value - The value to convert or null.
    
    Returns:
    
    The converted Byte value or null.
  - toDouble
```
public static java.lang.Double toDouble(java.lang.String value)
```
    Converts the given String value into an Double or null.
    
    Parameters:
    
    value - The value to convert or null.
    
    Returns:
    
    The converted Double value or null.
  - toFloat
```
public static java.lang.Float toFloat(java.lang.String value)
```
    Converts the given String value into a Float or null.
    
    Parameters:
    
    value - The value to convert or null.
    
    Returns:
    
    The converted Float value or null.
  - toInteger
```
public static java.lang.Integer toInteger(java.lang.String value)
```
    Converts the given String value into an Integer or null.
    
    Parameters:
    
    value - The value to convert or null.
    
    Returns:
    
    The converted Integer value or null.
  - toLong
```
public static java.lang.Long toLong(java.lang.String value)
```
    Converts the given String value into an Long or null.
    
    Parameters:
    
    value - The value to convert or null.
    
    Returns:
    
    The converted Long value or null.
  - toShort
```
public static java.lang.Short toShort(java.lang.String value)
```
    Converts the given String value into a Short or null.
    
    Parameters:
    
    value - The value to convert or null.
    
    Returns:
    
    The converted Short value or null.
  - doCatch
```
protected void doCatch(java.lang.Throwable throwable)
```
    Invoked when a Throwable is caught during initialization, handling or releasing.
    
    Parameters:
    
    throwable - The caught error or exception.
  - doError
```
protected void doError(Status errorStatus)
```
    Invoked when an error response status is received.
    
    Parameters:
    
    errorStatus - The error status received.
  - doError
```
protected final void doError(Status errorStatus,
                             java.lang.String errorMessage)
```
    Invoked when an error response status is received.
    
    Parameters:
    
    errorStatus - The error status received.
    
    errorMessage - The custom error message.
  - 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 wasn't set, it attempts to retrieve the current one via Application.getCurrent() if it exists, or instantiates a new one as a last resort.
    
    Returns:
    
    The parent application if it exists, or a new one.
  - getAttribute
```
public abstract java.lang.String getAttribute(java.lang.String name)
```
    Returns the attribute value by looking up the given name in the request or response attributes maps. This is typically used for variables that are declared in the URI template used to route the call to this resource.
    
    Parameters:
    
    name - The attribute name.
    
    Returns:
    
    The matching request or response attribute value.
  - 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()
  - getConnegService
```
public ConnegService getConnegService()
```
    Returns the application's content negotiation service or create a new one.
    
    Returns:
    
    The content negotiation service.
  - 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()
  - getMatrixValue
```
public java.lang.String getMatrixValue(java.lang.String name)
```
    Returns the first value of the matrix parameter given its name if existing, or null.
    
    Parameters:
    
    name - The matrix parameter name.
    
    Returns:
    
    The first value of the matrix parameter.
  - 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()
  - getProxyChallengeRequests
```
public java.util.List<ChallengeRequest> getProxyChallengeRequests()
```
    Returns the list of proxy authentication requests sent by an origin server to a client. If none is available, an empty list is returned.
    
    Returns:
    
    The list of proxy authentication requests.
    
    See Also:
    
    Response.getProxyChallengeRequests()
  - getProxyChallengeResponse
```
public ChallengeResponse getProxyChallengeResponse()
```
    Returns the proxy authentication response sent by a client to an origin server.
    
    Returns:
    
    The proxy authentication response sent by a client to an origin server.
    
    See Also:
    
    Request.getProxyChallengeResponse()
  - getQuery
```
public Form getQuery()
```
    Returns the resource reference's optional query. Note that modifications to the returned Form object aren't reported to the underlying reference.
    
    Returns:
    
    The resource reference's optional query.
    
    See Also:
    
    Reference.getQueryAsForm()
  - getQueryValue
```
public java.lang.String getQueryValue(java.lang.String name)
```
    Returns the first value of the query parameter given its name if existing, or null.
    
    Parameters:
    
    name - The query parameter name.
    
    Returns:
    
    The first value of the query parameter.
  - 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()
  - getRequestCacheDirectives
```
public java.util.List<CacheDirective> getRequestCacheDirectives()
```
    Returns the request cache directives. Note that when used with HTTP connectors, this property maps to the "Cache-Control" header.
    
    Returns:
    
    The cache directives.
  - 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()
  - getResponseCacheDirectives
```
public java.util.List<CacheDirective> getResponseCacheDirectives()
```
    Returns the response cache directives. Note that when used with HTTP connectors, this property maps to the "Cache-Control" header.
    
    Returns:
    
    The cache directives.
  - 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 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()
  - isLoggable
```
public boolean isLoggable()
```
    Indicates if the call is loggable
    
    Returns:
    
    True if the call is loggable
  - release
```
public final void release()
```
    Releases the resource by calling doRelease().
  - setApplication
```
public void setApplication(Application application)
```
    Sets the parent application.
    
    Parameters:
    
    application - The parent application.
  - setAttribute
```
public abstract void setAttribute(java.lang.String name,
                                  java.lang.Object value)
```
    Sets the request or response attribute value.
    
    Parameters:
    
    name - The attribute name.
    
    value - The attribute to set.
  - setQueryValue
```
public void setQueryValue(java.lang.String name,
                          java.lang.String value)
```
    Sets the query value for the named parameter. If no query is defined, it creates one. If the same parameter exists, it replaces it altogether.
    
    Parameters:
    
    name - The query parameter name.
    
    value - The query parameter value.
  - 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
```
public <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
```
public Representation toRepresentation(java.lang.Object source)
                                throws java.io.IOException
```
    Converts an object into a representation based on the default converter service variant.
    
    Parameters:
    
    source - The object to convert.
    
    Returns:
    
    The wrapper representation.
    
    Throws:
    
    java.io.IOException
  - toRepresentation
```
public Representation toRepresentation(java.lang.Object source,
                                       MediaType target)
                                throws java.io.IOException
```
    Converts an object into a representation based on a given media type.
    
    Parameters:
    
    source - The object to convert.
    
    target - The target representation media type.
    
    Returns:
    
    The wrapper representation.
    
    Throws:
    
    java.io.IOException
  - toRepresentation
```
public Representation toRepresentation(java.lang.Object source,
                                       Variant target)
                                throws java.io.IOException
```
    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.
    
    Throws:
    
    java.io.IOException
  - toString
```
public java.lang.String toString()
```
    Overrides:
    
    toString in class java.lang.Object

Class Resource

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

Resource

Method Detail

toBoolean

toByte

toDouble

toFloat

toInteger

toLong

toShort

doCatch

doError

doError

doInit

doRelease

getAllowedMethods

getApplication

getAttribute

getChallengeRequests

getChallengeResponse

getClientInfo

getConditions

getConnegService

getContext

getConverterService

getCookies

getCookieSettings

getDimensions

getHostRef

getLocationRef

getLogger

getMatrix

getMatrixValue

getMaxForwards

getMetadataService

getMethod

getOriginalRef

getProtocol

getProxyChallengeRequests

getProxyChallengeResponse

getQuery

getQueryValue

getRanges

getReference

getReferrerRef

getRequest

getRequestAttributes

getRequestCacheDirectives

getRequestEntity

getResponse

getResponseAttributes

getResponseCacheDirectives

getResponseEntity

getRootRef

getServerInfo

getStatus

getStatusService

handle

init

isConfidential

isLoggable

release

setApplication

setAttribute

setQueryValue

setRequest

setResponse

toObject

toRepresentation

toRepresentation

toRepresentation

toString