org.restlet.resource
Class UniformResource

java.lang.Object
  extended by org.restlet.resource.UniformResource
Direct Known Subclasses:
ClientResource, ServerResource

public abstract class UniformResource
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 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
UniformResource()
           
 
Method Summary
protected  void doCatch(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.
 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.
 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.
 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.
 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.
 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.
 Representation getRequestEntity()
          Returns the request entity representation.
 Response getResponse()
          Returns the handled response.
 Map<String,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, Class<T> target)
          Converts a representation into a Java object.
protected  Representation toRepresentation(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(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 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 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 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()

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 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()

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()

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,
                         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(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.


Copyright © 2005-2011 Noelios Technologies.