org.restlet.resource
Class Resource

java.lang.Object
  extended by org.restlet.resource.Resource
Direct Known Subclasses:
UniformResource

public abstract class Resource
extends 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 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
Resource()
           
 
Method Summary
protected  void doCatch(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, 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.
 Set<Method> getAllowedMethods()
          Returns the set of methods allowed for the current client by the resource.
 Application getApplication()
          Returns the parent application.
abstract  String getAttribute(String name)
          Returns the attribute value by looking up the given name in the request or response attributes maps.
 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.
 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.
 Logger getLogger()
          Returns the logger.
 Form getMatrix()
          Returns the resource reference's optional matrix.
 String getMatrixValue(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.
 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.
 String getQueryValue(String name)
          Returns the first value of the query parameter given its name if existing, or null.
 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.
 Map<String,Object> getRequestAttributes()
          Returns the request attributes.
 List<CacheDirective> getRequestCacheDirectives()
          Returns the request cache directives.

Note that when used with HTTP connectors, this property maps to the "Cache-Control" header.
 Representation getRequestEntity()
          Returns the request entity representation.
 Response getResponse()
          Returns the handled response.
 Map<String,Object> getResponseAttributes()
          Returns the response attributes.
 List<CacheDirective> getResponseCacheDirectives()
          Returns the response cache directives.

Note that when used with HTTP connectors, this property maps to the "Cache-Control" header.
 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(String name, Object value)
          Sets the request or response attribute value.
 void setQueryValue(String name, 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.
<T> T
toObject(Representation source, Class<T> target)
          Converts a representation into a Java object.
 Representation toRepresentation(Object source, Variant target)
          Converts an object into a representation based on client preferences.
 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

doCatch

protected void doCatch(Throwable throwable)
Invoked when a Throwable is caught during initialization, handling or releasing. By default, updates the responses's status with the result of StatusService.getStatus(Throwable, Resource) .

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,
                             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 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 String getAttribute(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 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 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 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 String getMatrixValue(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 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 String getQueryValue(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 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 Map<String,Object> getRequestAttributes()
Returns the request attributes.

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

getRequestCacheDirectives

public 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 Map<String,Object> getResponseAttributes()
Returns the response attributes.

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

getResponseCacheDirectives

public 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(String name,
                                  Object value)
Sets the request or response attribute value.

Parameters:
name - The attribute name.
value - The attribute to set.

setQueryValue

public void setQueryValue(String name,
                          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,
                      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(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.

toString

public String toString()
Overrides:
toString in class Object


Copyright © 2005-2014 Restlet.