org.restlet
Class Route

java.lang.Object
  extended by org.restlet.Uniform
      extended by org.restlet.Restlet
          extended by org.restlet.Filter
              extended by org.restlet.Route

public class Route
extends Filter

Filter scoring the affinity of calls with the attached Restlet. The score is used by an associated Router in order to determine the most appropriate Restlet for a given call. The routing is based on a reference template. It also supports the extraction of some attributes from a call.

Multiple extractions can be defined, based on the query string of the resource reference, on the request form (ex: posted from a browser) or on cookies.

Concurrency note: instances of this class or its subclasses can be invoked by several threads at the same time and therefore must be thread-safe. You should be especially careful when storing state in member variables.

Author:
Jerome Louvel
See Also:
Template

Field Summary
 
Fields inherited from class org.restlet.Filter
CONTINUE, SKIP, STOP
 
Constructor Summary
Route(Restlet next)
          Constructor behaving as a simple extractor filter.
Route(Router router, java.lang.String uriTemplate, Restlet next)
          Constructor.
Route(Router router, Template template, Restlet next)
          Constructor.
 
Method Summary
protected  int beforeHandle(Request request, Response response)
          Allows filtering before its handling by the target Restlet.
 Route extractCookie(java.lang.String attribute, java.lang.String cookieName, boolean first)
          Extracts an attribute from the request cookies.
 Route extractEntity(java.lang.String attribute, java.lang.String parameter, boolean first)
          Extracts an attribute from the request entity form.
 Route extractQuery(java.lang.String attribute, java.lang.String parameter, boolean first)
          Extracts an attribute from the query string of the resource reference.
 int getMatchingMode()
          Returns the matching mode to use on the template when parsing a formatted reference.
 boolean getMatchQuery()
          Indicates whether the query part should be taken into account when matching a reference with the template.
 Router getRouter()
          Returns the parent router.
 Template getTemplate()
          Returns the reference template to match.
 float score(Request request, Response response)
          Returns the score for a given call (between 0 and 1.0).
 void setMatchingMode(int matchingMode)
          Sets the matching mode to use on the template when parsing a formatted reference.
 void setMatchQuery(boolean matchQuery)
          Sets whether the matching should be done on the URI with or without query string.
 void setRouter(Router router)
          Sets the parent router.
 void setTemplate(Template template)
          Sets the reference template to match.
 void validate(java.lang.String attribute, boolean required, java.lang.String format)
          Checks the request attributes for presence, format, etc.
 
Methods inherited from class org.restlet.Filter
afterHandle, doHandle, getNext, handle, hasNext, setNext, setNext
 
Methods inherited from class org.restlet.Restlet
getApplication, getContext, getLogger, init, isStarted, isStopped, setContext, start, stop
 
Methods inherited from class org.restlet.Uniform
delete, delete, get, get, handle, head, head, options, options, post, post, put, put
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

Route

public Route(Restlet next)
Constructor behaving as a simple extractor filter.

Parameters:
next - The next Restlet.

Route

public Route(Router router,
             java.lang.String uriTemplate,
             Restlet next)
Constructor. The URIs will be matched agains the template using the Template.MODE_STARTS_WITH matching mode. This can be changed by getting the template and calling Template.setMatchingMode(int) with Template.MODE_EQUALS for exact matching.

Parameters:
router - The parent router.
uriTemplate - The URI template.
next - The next Restlet.

Route

public Route(Router router,
             Template template,
             Restlet next)
Constructor.

Parameters:
router - The parent router.
template - The URI template.
next - The next Restlet.
Method Detail

beforeHandle

protected int beforeHandle(Request request,
                           Response response)
Allows filtering before its handling by the target Restlet. By default it parses the template variable, adjust the base reference, then extracts the attributes from form parameters (query, cookies, entity) and finally tries to validates the variables as indicated by the validate(String, boolean, String) method.

Overrides:
beforeHandle in class Filter
Parameters:
request - The request to filter.
response - The response to filter.
Returns:
The continuation status.

extractCookie

public Route extractCookie(java.lang.String attribute,
                           java.lang.String cookieName,
                           boolean first)
Extracts an attribute from the request cookies.

Parameters:
attribute - The name of the request attribute to set.
cookieName - The name of the cookies to extract.
first - Indicates if only the first cookie should be set. Otherwise as a List instance might be set in the attribute value.
Returns:
The current Filter.

extractEntity

public Route extractEntity(java.lang.String attribute,
                           java.lang.String parameter,
                           boolean first)
Extracts an attribute from the request entity form.

Parameters:
attribute - The name of the request attribute to set.
parameter - The name of the entity form parameter to extract.
first - Indicates if only the first cookie should be set. Otherwise as a List instance might be set in the attribute value.
Returns:
The current Filter.

extractQuery

public Route extractQuery(java.lang.String attribute,
                          java.lang.String parameter,
                          boolean first)
Extracts an attribute from the query string of the resource reference.

Parameters:
attribute - The name of the request attribute to set.
parameter - The name of the query string parameter to extract.
first - Indicates if only the first cookie should be set. Otherwise as a List instance might be set in the attribute value.
Returns:
The current Filter.

getMatchingMode

public int getMatchingMode()
Returns the matching mode to use on the template when parsing a formatted reference.

Returns:
The matching mode to use.

getMatchQuery

public boolean getMatchQuery()
Indicates whether the query part should be taken into account when matching a reference with the template.

Returns:
True if the query part of the reference should be taken into account, false otherwise.

getRouter

public Router getRouter()
Returns the parent router.

Returns:
The parent router.

getTemplate

public Template getTemplate()
Returns the reference template to match.

Returns:
The reference template to match.

score

public float score(Request request,
                   Response response)
Returns the score for a given call (between 0 and 1.0).

Parameters:
request - The request to score.
response - The response to score.
Returns:
The score for a given call (between 0 and 1.0).

setMatchingMode

public void setMatchingMode(int matchingMode)
Sets the matching mode to use on the template when parsing a formatted reference.

Parameters:
matchingMode - The matching mode to use.

setMatchQuery

public void setMatchQuery(boolean matchQuery)
Sets whether the matching should be done on the URI with or without query string.

Parameters:
matchQuery - True if the matching should be done with the query string, false otherwise.

setRouter

public void setRouter(Router router)
Sets the parent router.

Parameters:
router - The parent router.

setTemplate

public void setTemplate(Template template)
Sets the reference template to match.

Parameters:
template - The reference template to match.

validate

public void validate(java.lang.String attribute,
                     boolean required,
                     java.lang.String format)
Checks the request attributes for presence, format, etc. If the check fails, then a response status CLIENT_ERROR_BAD_REQUEST is returned with the proper status description.

Parameters:
attribute - Name of the attribute to look for.
required - Indicates if the attribute presence is required.
format - Format of the attribute value, using Regex pattern syntax.


Copyright © 2005-2008 Noelios Technologies.