Package org.restlet.resource

Class ServerResource

  • public abstract class ServerResource
extends Resource
    Base class for server-side resources. It acts as a wrapper to a given call, including the incoming Request and the outgoing Response.

    It's life cycle is managed by a Finder created either explicitly or more likely implicitly when your ServerResource subclass is attached to a Filter or a Router via the Filter.setNext(Class) or Router.attach(String, Class) methods for example. After instantiation using the default constructor, the final Resource.init(Context, Request, Response) method is invoked, setting the context, request and response. You can intercept this by overriding the Resource.doInit() method. Then, if the response status is still a success, the handle() method is invoked to actually handle the call. Finally, the final Resource.release() method is invoked to do the necessary clean-up, which you can intercept by overriding the Resource.doRelease() method. During this life cycle, if any exception is caught, then the doCatch(Throwable) method is invoked.

    Note that when an annotated method manually sets the response entity, if this entity is available then it will be preserved and the result of the annotated method ignored.

    In addition, there are two ways to declare representation variants, one is based on the getVariants() method and another one on the annotated methods. Both approaches can't however be used at the same time for now.

    Concurrency note: contrary to the Uniform class and its main Restlet subclass where a single instance can handle several calls concurrently, one instance of ServerResource is created for each call handled and accessed by only one thread at a time.
    Author:
    Jerome Louvel

    • Method Detail

      • abort

        public void abort()
        Ask the connector to abort the related network connection, for example immediately closing the socket.

      • commit

        public void commit()
        Asks the response to immediately commit making it ready to be sent back to the client. Note that all server connectors don't necessarily support this feature.

      • describeVariants

        protected Representation describeVariants()
        Describes the available variants to help client-side content negotiation. Return null by default.
        Returns:
        The description of available variants.

      • doCatch

        protected void doCatch​(java.lang.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.toStatus(Throwable, Resource).
        Overrides:
        doCatch in class Resource
        Parameters:
        throwable - The caught error or exception.

      • doError

        protected void doError​(Status errorStatus)
        By default, it sets the status on the response.
        Overrides:
        doError in class Resource
        Parameters:
        errorStatus - The error status received.

      • get

        protected Representation get​(Variant variant)
                      throws ResourceException
        Returns a full representation for a given variant. A variant parameter is passed to indicate which representation should be returned if any.

        This method is only invoked if content negotiation has been enabled as indicated by the isNegotiated(), otherwise the get() method is invoked.

        The default behavior is to set the response status to Status.CLIENT_ERROR_METHOD_NOT_ALLOWED.
        Parameters:
        variant - The variant whose full representation must be returned.
        Returns:
        The resource's representation.
        Throws:
        ResourceException
        See Also:
        get(Variant)

      • getAttribute

        public java.lang.String getAttribute​(java.lang.String name)
        Returns the attribute value by looking up the given name in the request attributes maps. The toString() method is then invoked on the attribute value. This is typically used for variables that are declared in the URI template used to route the call to this resource.
        Specified by:
        getAttribute in class Resource
        Parameters:
        name - The attribute name.
        Returns:
        The request attribute value.

      • getDescription

        public java.lang.String getDescription()
        Returns the description.
        Returns:
        The description

      • getInfo

        protected RepresentationInfo getInfo()
                              throws ResourceException
        Returns information about the resource's representation. Those metadata are important for conditional method processing. The advantage over the complete Representation class is that it is much lighter to create. This method is only invoked if content negotiation has been disabled as indicated by the isNegotiated(), otherwise the getInfo(Variant) method is invoked.

        The default behavior is to invoke the get() method.
        Returns:
        Information about the resource's representation.
        Throws:
        ResourceException

      • getInfo

        protected RepresentationInfo getInfo​(Variant variant)
                              throws ResourceException
        Returns information about the resource's representation. Those metadata are important for conditional method processing. The advantage over the complete Representation class is that it is much lighter to create. A variant parameter is passed to indicate which representation should be returned if any.

        This method is only invoked if content negotiation has been enabled as indicated by the isNegotiated(), otherwise the getInfo(Variant) method is invoked.

        The default behavior is to invoke the get(Variant) method.
        Parameters:
        variant - The variant whose representation information must be returned.
        Returns:
        Information about the resource's representation.
        Throws:
        ResourceException

      • getName

        public java.lang.String getName()
        Returns the display name.
        Returns:
        The display name.

      • getOnSent

        public Uniform getOnSent()
        Returns the callback invoked after sending the response.
        Returns:
        The callback invoked after sending the response.

      • getRole

        public Role getRole​(java.lang.String name)
        Retrieves an existing role or creates a new one if needed based on its name. Note that a null description will be set if the role has to be created.
        Parameters:
        name - The role name to find or create.
        Returns:
        The role found or created.

      • getVariants

        public java.util.List<Variant> getVariants()
        Returns a modifiable list of exposed variants for the current request method. You can declare variants manually by updating the result list , by overriding this method. By default, the variants will be provided based on annotated methods.
        Returns:
        The modifiable list of variants.
        Throws:
        java.io.IOException

      • getVariants

        protected java.util.List<Variant> getVariants​(Method method)
        Returns a modifiable list of exposed variants for the given method. You can declare variants manually by updating the result list , by overriding this method. By default, the variants will be provided based on annotated methods.
        Parameters:
        method - The method.
        Returns:
        The modifiable list of variants.

      • hasAnnotations

        protected boolean hasAnnotations()
        Indicates if annotations were defined on this resource.
        Returns:
        True if annotations were defined on this resource.

      • head

        protected Representation head​(Variant variant)
                       throws ResourceException
        Returns a representation whose metadata will be returned to the client. A variant parameter is passed to indicate which representation should be returned if any.

        This method is only invoked if content negotiation has been enabled as indicated by the isNegotiated(), otherwise the head() method is invoked.

        The default implementation directly returns the variant if it is already an instance of Representation. In other cases, you need to override this method in order to provide your own implementation. *
        Parameters:
        variant - The variant whose full representation must be returned.
        Returns:
        The resource's representation.
        Throws:
        ResourceException
        See Also:
        get(Variant)

      • isAnnotated

        public boolean isAnnotated()
        Indicates if annotations are supported. The default value is true.
        Returns:
        True if annotations are supported.

      • isAutoCommitting

        public boolean isAutoCommitting()
        Indicates if the response should be automatically committed. When processing a request on the server-side, setting this property to 'false' let you ask to the server connector to wait before sending the response back to the client when the initial calling thread returns. This will let you do further updates to the response and manually calling commit() later on, using another thread.
        Returns:
        True if the response should be automatically committed.

      • isCommitted

        public boolean isCommitted()
        Indicates if the response has already been committed.
        Returns:
        True if the response has already been committed.

      • isConditional

        public boolean isConditional()
        Indicates if conditional handling is enabled. The default value is true.
        Returns:
        True if conditional handling is enabled.

      • isExisting

        public boolean isExisting()
        Indicates if the identified resource exists. The default value is true.
        Returns:
        True if the identified resource exists.

      • isInRole

        public boolean isInRole​(java.lang.String roleName)
        Indicates if the authenticated client user associated to the current request is in the given role name.
        Parameters:
        roleName - The role name to test.
        Returns:
        True if the authenticated subject is in the given role.

      • isNegotiated

        public boolean isNegotiated()
        Indicates if content negotiation of response entities is enabled. The default value is true.
        Returns:
        True if content negotiation of response entities is enabled.

      • redirectPermanent

        public void redirectPermanent​(Reference targetRef)
        Permanently redirects the client to a target URI. The client is expected to reuse the same method for the new request.
        Parameters:
        targetRef - The target URI reference.

      • redirectPermanent

        public void redirectPermanent​(java.lang.String targetUri)
        Permanently redirects the client to a target URI. The client is expected to reuse the same method for the new request.

        If you pass a relative target URI, it will be resolved with the current base reference of the request's resource reference (see Request.getResourceRef() and Reference.getBaseRef().
        Parameters:
        targetUri - The target URI.

      • redirectSeeOther

        public void redirectSeeOther​(Reference targetRef)
        Redirects the client to a different URI that SHOULD be retrieved using a GET method on that resource. This method exists primarily to allow the output of a POST-activated script to redirect the user agent to a selected resource. The new URI is not a substitute reference for the originally requested resource.
        Parameters:
        targetRef - The target reference.

      • redirectSeeOther

        public void redirectSeeOther​(java.lang.String targetUri)
        Redirects the client to a different URI that SHOULD be retrieved using a GET method on that resource. This method exists primarily to allow the output of a POST-activated script to redirect the user agent to a selected resource. The new URI is not a substitute reference for the originally requested resource.

        If you pass a relative target URI, it will be resolved with the current base reference of the request's resource reference (see Request.getResourceRef() and Reference.getBaseRef().
        Parameters:
        targetUri - The target URI.

      • redirectTemporary

        public void redirectTemporary​(Reference targetRef)
        Temporarily redirects the client to a target URI. The client is expected to reuse the same method for the new request.
        Parameters:
        targetRef - The target reference.

      • redirectTemporary

        public void redirectTemporary​(java.lang.String targetUri)
        Temporarily redirects the client to a target URI. The client is expected to reuse the same method for the new request.

        If you pass a relative target URI, it will be resolved with the current base reference of the request's resource reference (see Request.getResourceRef() and Reference.getBaseRef().
        Parameters:
        targetUri - The target URI.

      • setAllowedMethods

        public void setAllowedMethods​(java.util.Set<Method> allowedMethods)
        Sets the set of methods allowed on the requested resource. The set instance set must be thread-safe (use CopyOnWriteArraySet for example.
        Parameters:
        allowedMethods - The set of methods allowed on the requested resource.
        See Also:
        Response.setAllowedMethods(Set)

      • setAnnotated

        public void setAnnotated​(boolean annotated)
        Indicates if annotations are supported. The default value is true.
        Parameters:
        annotated - Indicates if annotations are supported.

      • setAttribute

        public void setAttribute​(java.lang.String name,
                         java.lang.Object value)
        Sets the response attribute value.
        Specified by:
        setAttribute in class Resource
        Parameters:
        name - The attribute name.
        value - The attribute to set.

      • setAutoCommitting

        public void setAutoCommitting​(boolean autoCommitting)
        Indicates if the response should be automatically committed.
        Parameters:
        autoCommitting - True if the response should be automatically committed

      • setChallengeRequests

        public void setChallengeRequests​(java.util.List<ChallengeRequest> requests)
        Sets the list of authentication requests sent by an origin server to a client. The list instance set must be thread-safe (use CopyOnWriteArrayList for example.
        Parameters:
        requests - The list of authentication requests sent by an origin server to a client.
        See Also:
        Response.setChallengeRequests(List)

      • setCommitted

        public void setCommitted​(boolean committed)
        Indicates if the response has already been committed.
        Parameters:
        committed - True if the response has already been committed.

      • setConditional

        public void setConditional​(boolean conditional)
        Indicates if conditional handling is enabled. The default value is true.
        Parameters:
        conditional - True if conditional handling is enabled.

      • setDescription

        public void setDescription​(java.lang.String description)
        Sets the description.
        Parameters:
        description - The description.

      • setDimensions

        public void setDimensions​(java.util.Set<Dimension> dimensions)
        Sets the set of dimensions on which the response entity may vary. The set instance set must be thread-safe (use CopyOnWriteArraySet for example.
        Parameters:
        dimensions - The set of dimensions on which the response entity may vary.
        See Also:
        Response.setDimensions(Set)

      • setExisting

        public void setExisting​(boolean exists)
        Indicates if the identified resource exists. The default value is true.
        Parameters:
        exists - Indicates if the identified resource exists.

      • setLocationRef

        public void setLocationRef​(Reference locationRef)
        Sets the reference that the client should follow for redirections or resource creations.
        Parameters:
        locationRef - The reference to set.
        See Also:
        Response.setLocationRef(Reference)

      • setLocationRef

        public void setLocationRef​(java.lang.String locationUri)
        Sets the reference that the client should follow for redirections or resource creations. If you pass a relative location URI, it will be resolved with the current base reference of the request's resource reference (see Request.getResourceRef() and Reference.getBaseRef().
        Parameters:
        locationUri - The URI to set.
        See Also:
        Response.setLocationRef(String)

      • setName

        public void setName​(java.lang.String name)
        Sets the display name.
        Parameters:
        name - The display name.

      • setNegotiated

        public void setNegotiated​(boolean negotiateContent)
        Indicates if content negotiation of response entities is enabled. The default value is true.
        Parameters:
        negotiateContent - True if content negotiation of response entities is enabled.

      • setOnSent

        public void setOnSent​(Uniform onSentCallback)
        Sets the callback invoked after sending the response.
        Parameters:
        onSentCallback - The callback invoked after sending the response.

      • setProxyChallengeRequests

        public void setProxyChallengeRequests​(java.util.List<ChallengeRequest> requests)
        Sets the list of proxy authentication requests sent by an origin server to a client. The list instance set must be thread-safe (use CopyOnWriteArrayList for example.
        Parameters:
        requests - The list of proxy authentication requests sent by an origin server to a client.
        See Also:
        Response.setProxyChallengeRequests(List)

      • setStatus

        public void setStatus​(Status status,
                      java.lang.String message)
        Sets the status.
        Parameters:
        status - The status to set.
        message - The status message.
        See Also:
        Response.setStatus(Status, String)

      • setStatus

        public void setStatus​(Status status,
                      java.lang.Throwable throwable)
        Sets the status.
        Parameters:
        status - The status to set.
        throwable - The related error or exception.
        See Also:
        Response.setStatus(Status, Throwable)

      • setStatus

        public void setStatus​(Status status,
                      java.lang.Throwable throwable,
                      java.lang.String message)
        Sets the status.
        Parameters:
        status - The status to set.
        throwable - The related error or exception.
        message - The status message.
        See Also:
        Response.setStatus(Status, Throwable, String)

      • updateAllowedMethods

        public void updateAllowedMethods()
        Invoked when the list of allowed methods needs to be updated. The Resource.getAllowedMethods() or the setAllowedMethods(Set) methods should be used. The default implementation lists the annotated methods.