org.restlet
Class Router

java.lang.Object
  extended by org.restlet.Uniform
      extended by org.restlet.Restlet
          extended by org.restlet.Router
Direct Known Subclasses:
VirtualHost

public class Router
extends Restlet

Restlet routing calls to one of the attached routes. Each route can compute an affinity score for each call depending on various criteria. The attach() method allow the creation of routes based on URI patterns matching the beginning of a the resource reference's remaining part.

In addition, several routing modes are supported, implementing various algorithms:


Note that for routes using URI patterns will update the resource reference's base reference during the routing if they are selected. It is also important to know that the routing is very strict about path separators in your URI patterns. Finally, you can modify the list of routes while handling incoming calls as the delegation code is ensured to be thread-safe.

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:
Tutorial: Routers and hierarchical URIs

Field Summary
static int BEST
          Each call will be routed to the route with the best score, if the required score is reached.
static int CUSTOM
          Each call will be routed according to a custom mode.
static int FIRST
          Each call is routed to the first route if the required score is reached.
static int LAST
          Each call will be routed to the last route if the required score is reached.
static int NEXT
          Each call is be routed to the next route target if the required score is reached.
static int RANDOM
          Each call will be randomly routed to one of the routes that reached the required score.
 
Constructor Summary
Router()
          Constructor.
Router(Context context)
          Constructor.
 
Method Summary
 Route attach(Restlet target)
          Attaches a target Restlet to this router with an empty URI pattern.
 Route attach(java.lang.String uriPattern, java.lang.Class<? extends Resource> targetClass)
          Attaches a target Resource class to this router based on a given URI pattern.
 Route attach(java.lang.String uriPattern, Restlet target)
          Attaches a target Restlet to this router based on a given URI pattern.
 Route attachDefault(java.lang.Class<? extends Resource> defaultTargetClass)
          Attaches a Resource class to this router as the default target to invoke when no route matches.
 Route attachDefault(Restlet defaultTarget)
          Attaches a Restlet to this router as the default target to invoke when no route matches.
protected  Finder createFinder(java.lang.Class<? extends Resource> targetClass)
          Creates a new finder instance based on the "targetClass" property.
protected  Route createRoute(java.lang.String uriPattern, Restlet target)
          Creates a new route for the given URI pattern and target.
 void detach(Restlet target)
          Detaches the target from this router.
protected  Route getCustom(Request request, Response response)
          Returns the matched route according to a custom algorithm.
 int getDefaultMatchingMode()
          Returns the default matching mode to use when selecting routes based on URIs.
 boolean getDefaultMatchQuery()
          Returns the default setting for whether the routing should be done on URIs with or without taking into account query string.
 Route getDefaultRoute()
          Returns the default route to test if no other one was available after retrying the maximum number of attemps.
 java.lang.Class<? extends Finder> getFinderClass()
          Returns the finder class to instantiate.
 int getMaxAttempts()
          Returns the maximum number of attempts if no attachment could be matched on the first attempt.
 Restlet getNext(Request request, Response response)
          Returns the next Restlet if available.
 float getRequiredScore()
          Returns the minimum score required to have a match.
 long getRetryDelay()
          Returns the delay (in seconds) before a new attempt.
 RouteList getRoutes()
          Returns the modifiable list of routes.
 int getRoutingMode()
          Returns the routing mode.
 void handle(Request request, Response response)
          Handles a call by invoking the next Restlet if it is available.
 void setDefaultMatchingMode(int defaultMatchingMode)
          Sets the default matching mode to use when selecting routes based on URIs.
 void setDefaultMatchQuery(boolean defaultMatchQuery)
          Sets the default setting for whether the routing should be done on URIs with or without taking into account query string.
 void setDefaultRoute(Route defaultRoute)
          Sets the default route tested if no other one was available.
 void setFinderClass(java.lang.Class<? extends Finder> finderClass)
          Sets the finder class to instantiate.
 void setMaxAttempts(int maxAttempts)
          Sets the maximum number of attempts if no attachment could be matched on the first attempt.
 void setRequiredScore(float score)
          Sets the score required to have a match.
 void setRetryDelay(long retryDelay)
          Sets the delay (in seconds) before a new attempt.
 void setRoutes(RouteList routes)
          Sets the modifiable list of routes.
 void setRoutingMode(int routingMode)
          Sets the routing mode.
 
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
 

Field Detail

BEST

public static final int BEST
Each call will be routed to the route with the best score, if the required score is reached.

See Also:
Constant Field Values

CUSTOM

public static final int CUSTOM
Each call will be routed according to a custom mode.

See Also:
Constant Field Values

FIRST

public static final int FIRST
Each call is routed to the first route if the required score is reached. If the required score is not reached, then the route is skipped and the next one is considered.

See Also:
Constant Field Values

LAST

public static final int LAST
Each call will be routed to the last route if the required score is reached. If the required score is not reached, then the route is skipped and the previous one is considered.

See Also:
Constant Field Values

NEXT

public static final int NEXT
Each call is be routed to the next route target if the required score is reached. The next route is relative to the previous call routed (round robin mode). If the required score is not reached, then the route is skipped and the next one is considered. If the last route is reached, the first route will be considered.

See Also:
Constant Field Values

RANDOM

public static final int RANDOM
Each call will be randomly routed to one of the routes that reached the required score. If the random route selected is not a match then the immediate next route is evaluated until one matching route is found. If we get back to the inital random route selected with no match, then we return null.

See Also:
Constant Field Values
Constructor Detail

Router

public Router()
Constructor. Note that usage of this constructor is not recommended as the Router won't have a proper context set. In general you will prefer to use the other constructor and pass it the parent application's context or eventually the parent component's context if you don't use applications.


Router

public Router(Context context)
Constructor.

Parameters:
context - The context.
Method Detail

attach

public Route attach(Restlet target)
Attaches a target Restlet to this router with an empty URI pattern. A new route will be added routing to the target when any call is received.

Parameters:
target - The target Restlet to attach.
Returns:
The created route.

attach

public Route attach(java.lang.String uriPattern,
                    java.lang.Class<? extends Resource> targetClass)
Attaches a target Resource class to this router based on a given URI pattern. A new route will be added routing to the target when calls with a URI matching the pattern will be received.

Parameters:
uriPattern - The URI pattern that must match the relative part of the resource URI.
targetClass - The target Resource class to attach.
Returns:
The created route.

attach

public Route attach(java.lang.String uriPattern,
                    Restlet target)
Attaches a target Restlet to this router based on a given URI pattern. A new route will be added routing to the target when calls with a URI matching the pattern will be received.

Parameters:
uriPattern - The URI pattern that must match the relative part of the resource URI.
target - The target Restlet to attach.
Returns:
The created route.

attachDefault

public Route attachDefault(java.lang.Class<? extends Resource> defaultTargetClass)
Attaches a Resource class to this router as the default target to invoke when no route matches. It actually sets a default route that scores all calls to 1.0.

Parameters:
defaultTargetClass - The target Resource class to attach.
Returns:
The created route.

attachDefault

public Route attachDefault(Restlet defaultTarget)
Attaches a Restlet to this router as the default target to invoke when no route matches. It actually sets a default route that scores all calls to 1.0.

Parameters:
defaultTarget - The Restlet to use as the default target.
Returns:
The created route.

createFinder

protected Finder createFinder(java.lang.Class<? extends Resource> targetClass)
Creates a new finder instance based on the "targetClass" property.

Parameters:
targetClass - The target Resource class to attach.
Returns:
The new finder instance.

createRoute

protected Route createRoute(java.lang.String uriPattern,
                            Restlet target)
Creates a new route for the given URI pattern and target.

Parameters:
uriPattern - The URI pattern that must match the relative part of the resource URI.
target - The target Restlet to attach.
Returns:
The created route.

detach

public void detach(Restlet target)
Detaches the target from this router. All routes routing to this target Restlet are removed from the list of routes and the default route is set to null.

Parameters:
target - The target Restlet to detach.

getCustom

protected Route getCustom(Request request,
                          Response response)
Returns the matched route according to a custom algorithm. To use in combination of the RouterMode.CUSTOM enumeration. The default implementation (to be overriden), returns null.

Parameters:
request - The request to handle.
response - The response to update.
Returns:
The matched route if available or null.

getDefaultMatchingMode

public int getDefaultMatchingMode()
Returns the default matching mode to use when selecting routes based on URIs. By default it returns Template.MODE_STARTS_WITH.

Returns:
The default matching mode.

getDefaultMatchQuery

public boolean getDefaultMatchQuery()
Returns the default setting for whether the routing should be done on URIs with or without taking into account query string.

Returns:
the default setting for whether the routing should be done on URIs with or without taking into account query string.

getDefaultRoute

public Route getDefaultRoute()
Returns the default route to test if no other one was available after retrying the maximum number of attemps.

Returns:
The default route tested if no other one was available.

getFinderClass

public java.lang.Class<? extends Finder> getFinderClass()
Returns the finder class to instantiate.

Returns:
the finder class to instantiate.

getMaxAttempts

public int getMaxAttempts()
Returns the maximum number of attempts if no attachment could be matched on the first attempt. This is useful when the attachment scoring is dynamic and therefore could change on a retry. The default value is set to 1.

Returns:
The maximum number of attempts if no attachment could be matched on the first attempt.

getNext

public Restlet getNext(Request request,
                       Response response)
Returns the next Restlet if available.

Parameters:
request - The request to handle.
response - The response to update.
Returns:
The next Restlet if available or null.

getRequiredScore

public float getRequiredScore()
Returns the minimum score required to have a match.

Returns:
The minimum score required to have a match.

getRetryDelay

public long getRetryDelay()
Returns the delay (in seconds) before a new attempt. The default value is 500 ms.

Returns:
The delay (in seconds) before a new attempt.

getRoutes

public RouteList getRoutes()
Returns the modifiable list of routes. Creates a new instance if no one has been set.

Returns:
The modifiable list of routes.

getRoutingMode

public int getRoutingMode()
Returns the routing mode.

Returns:
The routing mode.

handle

public void handle(Request request,
                   Response response)
Handles a call by invoking the next Restlet if it is available.

Overrides:
handle in class Restlet
Parameters:
request - The request to handle.
response - The response to update.

setDefaultMatchingMode

public void setDefaultMatchingMode(int defaultMatchingMode)
Sets the default matching mode to use when selecting routes based on URIs.

Parameters:
defaultMatchingMode - The default matching mode.

setDefaultMatchQuery

public void setDefaultMatchQuery(boolean defaultMatchQuery)
Sets the default setting for whether the routing should be done on URIs with or without taking into account query string.

Parameters:
defaultMatchQuery - The default setting for whether the routing should be done on URIs with or without taking into account query string.

setDefaultRoute

public void setDefaultRoute(Route defaultRoute)
Sets the default route tested if no other one was available.

Parameters:
defaultRoute - The default route tested if no other one was available.

setFinderClass

public void setFinderClass(java.lang.Class<? extends Finder> finderClass)
Sets the finder class to instantiate.

Parameters:
finderClass - The finder class to instantiate.

setMaxAttempts

public void setMaxAttempts(int maxAttempts)
Sets the maximum number of attempts if no attachment could be matched on the first attempt. This is useful when the attachment scoring is dynamic and therefore could change on a retry.

Parameters:
maxAttempts - The maximum number of attempts.

setRequiredScore

public void setRequiredScore(float score)
Sets the score required to have a match.

Parameters:
score - The score required to have a match.

setRetryDelay

public void setRetryDelay(long retryDelay)
Sets the delay (in seconds) before a new attempt.

Parameters:
retryDelay - The delay (in seconds) before a new attempt.

setRoutes

public void setRoutes(RouteList routes)
Sets the modifiable list of routes.

Parameters:
routes - The modifiable list of routes.

setRoutingMode

public void setRoutingMode(int routingMode)
Sets the routing mode.

Parameters:
routingMode - The routing mode.


Copyright © 2005-2008 Noelios Technologies.