Package org.restlet.client.resource

Class Resource

  • Direct Known Subclasses:
    ClientResource
    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 Description
      Resource()  

    • Method Summary

      All Methods Static Methods Instance Methods Abstract Methods Concrete Methods 
      Modifier and Type Method 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.
      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.
      Context getContext()
      Returns the current context.
      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.
      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.
      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().
      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.
      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.

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

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

      • getContext

        public Context getContext()
        Returns the current context.
        Returns:
        The current context.

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

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

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

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

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

      • 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