Package org.restlet.resource

Class Resource

java.lang.Object
org.restlet.resource.Resource
Direct Known Subclasses:
ClientResource, ServerResource
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 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:

  • Constructor Details

    • Resource

      public Resource()

  • Method Details

    • toBoolean

      public static Boolean toBoolean(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 Byte toByte(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 Double toDouble(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 Float toFloat(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 Integer toInteger(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 Long toLong(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 Short toShort(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(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, 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:

    • 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:

    • 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:

    • 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:

    • 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:

    • 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:

    • 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:

    • 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:

    • 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:

    • 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:

    • getLocationRef

      public Reference getLocationRef()
      Returns the reference that the client should follow for redirections or resource creations.
      Returns:
      The redirection reference.
      See Also:

    • 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:

    • 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:

    • 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:

    • 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:

    • 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:

    • 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:

    • 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:

    • 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:

    • 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:

    • 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:

    • 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:

    • 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:

    • getStatus

      public Status getStatus()
      Returns the status.
      Returns:
      The status.
      See Also:

    • 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:

    • 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) throws 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:
      IOException

    • toRepresentation

      public Representation toRepresentation(Object source, MediaType target) throws 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:
      IOException

    • toRepresentation

      public Representation toRepresentation(Object source, Variant target) throws 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:
      IOException

    • toString

      public String toString()
      Overrides:
      toString in class Object