org.restlet
Class Handler

java.lang.Object
  extended by org.restlet.Handler
Direct Known Subclasses:
Resource

public abstract class Handler
extends java.lang.Object

Final handler of calls typically created by Finders. Handler instances allow the processing of a call in a thread-safe context. This is different from the Uniform subclasses like Restlet, Filter and Router which can be invoked by multiple threads at the same time. However, as they offer a rather low-level API and its subclass Resource is often preferred for concrete handlers.

This class exposes a different set of handle*() and allow*() Java methods for each type of Uniform method supported by your handler. It has a predefined set for common methods like GET, POST, PUT, DELETE, HEAD and OPTIONS. Extension methods like MOVE or PATCH are automatically supported using Java introspection. The actual dispatching of the call to those methods is dynamically done by the Finder class.

The HEAD method has a default implementation based on the GET method and the OPTIONS method automatically updates the list of allowed methods in the response, as required by the HTTP specification.

Also, you can declare which REST methods are allowed by your Handler by overiding the matching allow*() method. By default, allowOptions() returns true, but all other allow*() methods will return false. Therefore, if you want to accept MOVE method calls, just override allowMove() and return true. Again, the invoking Finder will be able to detect this method and know whether or not your Handler should be invoked. It is also used by the handleOptions() method to return the list of allowed methods.

Concurrency note: typically created by Finders, Handler instances are the final handlers of requests. Unlike the other processors in the Restlet chain, a Handler instance is not reused by several calls and is only invoked by one thread. Therefore, it doesn't have to be thread-safe.

Author:
Jerome Louvel
See Also:
Finder

Constructor Summary
Handler()
          Special constructor used by IoC frameworks.
Handler(Context context, Request request, Response response)
          Normal constructor.
 
Method Summary
 boolean allowDelete()
          Indicates if DELETE calls are allowed.
 boolean allowGet()
          Indicates if GET calls are allowed.
 boolean allowHead()
          Indicates if HEAD calls are allowed.
 boolean allowOptions()
          Indicates if OPTIONS calls are allowed.
 boolean allowPost()
          Indicates if POST calls are allowed.
 boolean allowPut()
          Indicates if PUT calls are allowed.
 Reference generateRef(java.lang.String uriTemplate)
          Generates a reference based on a template URI.
 java.util.Set<Method> getAllowedMethods()
          Returns the set of allowed methods.
 Application getApplication()
          Returns the parent application if it exists, or null.
 Context getContext()
          Returns the context.
 java.util.logging.Logger getLogger()
          Returns the logger to use.
 Form getMatrix()
          Returns the optional matrix of the request's target resource reference as a form (series of parameters).
 Form getQuery()
          Returns the parsed query of the request's target resource reference as a form (series of parameters).
 Request getRequest()
          Returns the request.
 Response getResponse()
          Returns the response.
 void handleDelete()
          Handles a DELETE call.
 void handleGet()
          Handles a GET call.
 void handleHead()
          Handles a HEAD call.
 void handleOptions()
          Handles an OPTIONS call introspecting the target resource (as provided by the 'findTarget' method).
 void handlePost()
          Handles a POST call.
 void handlePut()
          Handles a PUT call.
 void init(Context context, Request request, Response response)
          Initialize the resource with its context.
 void setContext(Context context)
          Sets the parent context.
 void setRequest(Request request)
          Sets the request to handle.
 void setResponse(Response response)
          Sets the response to update.
 void updateAllowedMethods()
          Updates the set of allowed methods on the response.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

Handler

public Handler()
Special constructor used by IoC frameworks. Note that the init() method MUST be invoked right after the creation of the handler in order to keep a behavior consistent with the normal three arguments constructor.


Handler

public Handler(Context context,
               Request request,
               Response response)
Normal constructor.

Parameters:
context - The parent context.
request - The request to handle.
response - The response to return.
Method Detail

allowDelete

public boolean allowDelete()
Indicates if DELETE calls are allowed. The default value is false.

Returns:
True if the method is allowed.

allowGet

public boolean allowGet()
Indicates if GET calls are allowed. The default value is false.

Returns:
True if the method is allowed.

allowHead

public boolean allowHead()
Indicates if HEAD calls are allowed. The default behavior is to call allowGet().

Returns:
True if the method is allowed.

allowOptions

public boolean allowOptions()
Indicates if OPTIONS calls are allowed. The default value is true.

Returns:
True if the method is allowed.

allowPost

public boolean allowPost()
Indicates if POST calls are allowed. The default value is false.

Returns:
True if the method is allowed.

allowPut

public boolean allowPut()
Indicates if PUT calls are allowed. The default value is false.

Returns:
True if the method is allowed.

generateRef

public Reference generateRef(java.lang.String uriTemplate)
Generates a reference based on a template URI. Note that you can leverage all the variables defined in the Template class as they will be resolved using the resource's request and response properties.

Parameters:
uriTemplate - The URI template to use for generation.
Returns:
The generated reference.

getAllowedMethods

public java.util.Set<Method> getAllowedMethods()
Returns the set of allowed methods.

Returns:
The set of allowed methods.

getApplication

public Application getApplication()
Returns the parent application if it exists, or null.

Returns:
The parent application if it exists, or null.

getContext

public Context getContext()
Returns the context.

Returns:
The context.

getLogger

public java.util.logging.Logger getLogger()
Returns the logger to use.

Returns:
The logger to use.

getMatrix

public Form getMatrix()
Returns the optional matrix of the request's target resource reference as a form (series of parameters).

Returns:
The parsed query.
See Also:
Reference.getMatrixAsForm()

getQuery

public Form getQuery()
Returns the parsed query of the request's target resource reference as a form (series of parameters).

Returns:
The parsed query.
See Also:
Reference.getQueryAsForm()

getRequest

public Request getRequest()
Returns the request.

Returns:
the request.

getResponse

public Response getResponse()
Returns the response.

Returns:
the response.

handleDelete

public void handleDelete()
Handles a DELETE call. The default behavior, to be overriden by subclasses, is to set the status to Status.SERVER_ERROR_INTERNAL.


handleGet

public void handleGet()
Handles a GET call. The default behavior, to be overriden by subclasses, is to set the status to Status.SERVER_ERROR_INTERNAL.


handleHead

public void handleHead()
Handles a HEAD call. The default behavior is to invoke the handleGet() method. This is the expected behavior of the HTTP 1.1 specification for example. Note that the server connectors will take care of never sending back to the client the response entity bodies.


handleOptions

public void handleOptions()
Handles an OPTIONS call introspecting the target resource (as provided by the 'findTarget' method). The default implementation is based on the HTTP specification which says that OPTIONS should return the list of allowed methods in the Response headers.


handlePost

public void handlePost()
Handles a POST call. The default behavior, to be overriden by subclasses, is to set the status to Status.SERVER_ERROR_INTERNAL.


handlePut

public void handlePut()
Handles a PUT call. The default behavior, to be overriden by subclasses, is to set the status to Status.SERVER_ERROR_INTERNAL.


init

public void init(Context context,
                 Request request,
                 Response response)
Initialize the resource with its context. If you override this method, make sure that you don't forget to call super.init() first, otherwise your Resource won't behave properly.

Parameters:
context - The parent context.
request - The request to handle.
response - The response to return.

setContext

public void setContext(Context context)
Sets the parent context.

Parameters:
context - The parent context.

setRequest

public void setRequest(Request request)
Sets the request to handle.

Parameters:
request - The request to handle.

setResponse

public void setResponse(Response response)
Sets the response to update.

Parameters:
response - The response to update.

updateAllowedMethods

public void updateAllowedMethods()
Updates the set of allowed methods on the response.



Copyright © 2005-2008 Noelios Technologies.