Package org.restlet.resource

Class ServerResource

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

  • Constructor Details

  • Method Details

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

    • delete

      protected Representation delete() throws ResourceException
      Deletes the resource and all its representations. This method is only invoked if content negotiation has been disabled as indicated by the isNegotiated(), otherwise the delete(Variant) method is invoked.

      The default behavior is to set the response status to Status.CLIENT_ERROR_METHOD_NOT_ALLOWED.
      Returns:
      The optional response entity.
      Throws:
      ResourceException
      See Also:

    • delete

      protected Representation delete(Variant variant) throws ResourceException
      Deletes the resource and all its representations. 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 delete() method is invoked.

      The default behavior is to set the response status to Status.CLIENT_ERROR_METHOD_NOT_ALLOWED.
      Parameters:
      variant - The variant of the response entity.
      Returns:
      The optional response entity.
      Throws:
      ResourceException
      See Also:

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

    • doConditionalHandle

      protected Representation doConditionalHandle() throws ResourceException
      Handles a call by first verifying the optional request conditions and continue the processing if possible. Note that in order to evaluate those conditions, getInfo() or getInfo(Variant) methods might be invoked.
      Returns:
      The response entity.
      Throws:
      ResourceException

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

    • doHandle

      protected Representation doHandle() throws ResourceException
      Effectively handles a call without content negotiation of the response entity. The default behavior is to dispatch the call to one of the get(), post(Representation), put(Representation), delete(), head() or options() methods.
      Returns:
      The response entity.
      Throws:
      ResourceException

    • doHandle

      protected Representation doHandle(MethodAnnotationInfo annotationInfo, Variant variant) throws ResourceException
      Effectively handles a call with content negotiation of the response entity using an annotated method.
      Parameters:
      annotationInfo - The annotation descriptor.
      variant - The response variant expected (can be null).
      Returns:
      The response entity.
      Throws:
      ResourceException

    • doHandle

      protected Representation doHandle(Variant variant) throws ResourceException
      Effectively handles a call with content negotiation of the response entity. The default behavior is to dispatch the call to one of the get(Variant), post(Representation,Variant), put(Representation,Variant), delete(Variant), head(Variant) or options(Variant) methods.
      Parameters:
      variant - The response variant expected.
      Returns:
      The response entity.
      Throws:
      ResourceException

    • doNegotiatedHandle

      protected Representation doNegotiatedHandle() throws ResourceException
      Effectively handles a call with content negotiation of the response entity. The default behavior is to dispatch the call to call a matching annotated method or one of the get(Variant), post(Representation,Variant), put(Representation,Variant), delete(Variant), head(Variant) or options(Variant) methods.

      If no acceptable variant is found, the Status.CLIENT_ERROR_NOT_ACCEPTABLE status is set.
      Returns:
      The response entity.
      Throws:
      ResourceException

    • get

      protected Representation get() throws ResourceException
      Returns a full representation. This method is only invoked if content negotiation has been disabled as indicated by the isNegotiated() , otherwise the get(Variant) method is invoked.

      The default behavior is to set the response status to Status.CLIENT_ERROR_METHOD_NOT_ALLOWED.
      Returns:
      The resource's representation.
      Throws:
      ResourceException
      See Also:

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

    • getAnnotation

      protected MethodAnnotationInfo getAnnotation(Method method) throws IOException
      Returns the first annotation descriptor matching the given method.
      Parameters:
      method - The method to match.
      Returns:
      The annotation descriptor.
      Throws:
      IOException

    • getAnnotation

      protected MethodAnnotationInfo getAnnotation(Method method, Form query, Representation entity) throws IOException
      Returns the first annotation descriptor matching the given method.
      Parameters:
      method - The method to match.
      query - The query parameters.
      entity - The request entity or null.
      Returns:
      The annotation descriptor.
      Throws:
      IOException

    • getAnnotations

      protected List<AnnotationInfo> getAnnotations()
      Returns the annotation descriptors.
      Returns:
      The annotation descriptors.

    • getAttribute

      public String getAttribute(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 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 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.

    • getPreferredVariant

      protected Variant getPreferredVariant(List<Variant> variants)
      Returns the preferred variant among a list of available variants. The selection is based on the client preferences using the ConnegService.getPreferredVariant(List, Request, org.restlet.service.MetadataService) method.
      Parameters:
      variants - The available variants.
      Returns:
      The preferred variant.

    • getRole

      public Role getRole(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 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:
      IOException

    • getVariants

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

    • handle

      public Representation handle()
      Handles any call to this resource. The default implementation check the isConditional() and isNegotiated() method to determine which one of the doConditionalHandle(), doNegotiatedHandle() and doHandle() methods should be invoked. It also catches any ResourceException thrown and updates the response status using the setStatus(Status, Throwable, String) method.

      After handling, if the status is set to Status.CLIENT_ERROR_METHOD_NOT_ALLOWED, then updateAllowedMethods() is invoked to give the resource a chance to inform the client about the allowed methods.
      Specified by:
      handle in class Resource
      Returns:
      The response entity, but this method is still responsible for setting the response entity.

    • 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() throws ResourceException
      Returns a representation whose metadata will be returned to the client. This method is only invoked if content negotiation has been disabled as indicated by the isNegotiated(), otherwise the head(Variant) method is invoked.

      The default behavior is to set the response status to Status.CLIENT_ERROR_METHOD_NOT_ALLOWED.
      Returns:
      The resource's representation.
      Throws:
      ResourceException
      See Also:

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

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

    • options

      protected Representation options() throws ResourceException
      Indicates the communication options available for this resource. This method is only invoked if content negotiation has been disabled as indicated by the isNegotiated(), otherwise the options(Variant) method is invoked.

      The default behavior is to set the response status to Status.CLIENT_ERROR_METHOD_NOT_ALLOWED.
      Returns:
      The optional response entity.
      Throws:
      ResourceException

    • options

      protected Representation options(Variant variant) throws ResourceException
      Indicates the communication options available for this resource. 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 options() method is invoked.

      The default behavior is to set the response status to Status.CLIENT_ERROR_METHOD_NOT_ALLOWED.
      Parameters:
      variant - The variant of the response entity.
      Returns:
      The optional response entity.
      Throws:
      ResourceException
      See Also:

    • patch

      protected Representation patch(Representation entity) throws ResourceException
      Apply a patch entity to the current representation of the resource retrieved by calling get(). By default, the ConverterService.applyPatch(Representation, Representation) method is used and then the put(Representation) method called.
      Parameters:
      entity - The patch entity to apply.
      Returns:
      The optional result entity.
      Throws:
      ResourceException
      See Also:

    • patch

      protected Representation patch(Representation entity, Variant variant) throws ResourceException
      Apply a patch entity to the current representation of the resource retrieved by calling get(). By default, the ConverterService.applyPatch(Representation, Representation) method is used and then the put(Representation, Variant) method called.
      Parameters:
      entity - The patch entity to apply.
      variant - The variant of the response entity.
      Returns:
      The optional result entity.
      Throws:
      ResourceException
      See Also:

    • post

      protected Representation post(Representation entity) throws ResourceException
      Posts a representation to the resource at the target URI reference. This method is only invoked if content negotiation has been disabled as indicated by the isNegotiated(), otherwise the post(Representation, Variant) method is invoked.

      The default behavior is to set the response status to Status.CLIENT_ERROR_METHOD_NOT_ALLOWED.
      Parameters:
      entity - The posted entity.
      Returns:
      The optional response entity.
      Throws:
      ResourceException
      See Also:

    • post

      protected Representation post(Representation entity, Variant variant) throws ResourceException
      Posts a representation to the resource at the target URI reference. 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 post(Representation) method is invoked.

      The default behavior is to set the response status to Status.CLIENT_ERROR_METHOD_NOT_ALLOWED.
      Parameters:
      entity - The posted entity.
      variant - The variant of the response entity.
      Returns:
      The optional result entity.
      Throws:
      ResourceException
      See Also:

    • put

      protected Representation put(Representation entity) throws ResourceException
      Creates or updates a resource with the given representation as new state to be stored. This method is only invoked if content negotiation has been disabled as indicated by the isNegotiated(), otherwise the put(Representation, Variant) method is invoked.

      The default behavior is to set the response status to Status.CLIENT_ERROR_METHOD_NOT_ALLOWED.
      Parameters:
      entity - The representation to store.
      Returns:
      The optional result entity.
      Throws:
      ResourceException
      See Also:

    • put

      protected Representation put(Representation representation, Variant variant) throws ResourceException
      Creates or updates a resource with the given representation as new state to be stored. 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 put(Representation) method is invoked.

      The default behavior is to set the response status to Status.CLIENT_ERROR_METHOD_NOT_ALLOWED.
      Parameters:
      representation - The representation to store.
      variant - The variant of the response entity.
      Returns:
      The optional result entity.
      Throws:
      ResourceException
      See Also:

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

    • 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(String name, 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(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:

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

    • setCookieSettings

      public void setCookieSettings(Series<CookieSetting> cookieSettings)
      Sets the cookie settings provided by the server.
      Parameters:
      cookieSettings - The cookie settings provided by the server.
      See Also:

    • setDescription

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

    • setDimensions

      public void setDimensions(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:

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

    • setLocationRef

      public void setLocationRef(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:

    • setName

      public void setName(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(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:

    • setServerInfo

      public void setServerInfo(ServerInfo serverInfo)
      Sets the server-specific information.
      Parameters:
      serverInfo - The server-specific information.
      See Also:

    • setStatus

      public void setStatus(Status status)
      Sets the status.
      Parameters:
      status - The status to set.
      See Also:

    • setStatus

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

    • setStatus

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

    • setStatus

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

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

    • updateDimensions

      protected void updateDimensions()
      Update the dimensions that were used for content negotiation. By default, it adds the Dimension.CHARACTER_SET, Dimension.ENCODING, Dimension.LANGUAGEand Dimension.MEDIA_TYPE constants.