Router (Restlet API 2.4.4 - Java Standard Edition)

java.lang.Object
- org.restlet.Restlet
- - org.restlet.routing.Router

All Implemented Interfaces:

Uniform

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:
- Best match
- First match (default)
- Last match
- Random match
- Round robin
- Custom
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:

User Guide - Routers and hierarchical URIs

Field Summary

Fields
Modifier and Type	Field and Description
`static int`	`MODE_BEST_MATCH` Each call will be routed to the route with the best score, if the required score is reached.
`static int`	`MODE_CUSTOM` Each call will be routed according to a custom mode.
`static int`	`MODE_FIRST_MATCH` Each call is routed to the first route if the required score is reached.
`static int`	`MODE_LAST_MATCH` Each call will be routed to the last route if the required score is reached.
`static int`	`MODE_NEXT_MATCH` Each call is routed to the next route target if the required score is reached.
`static int`	`MODE_RANDOM_MATCH` Each call will be randomly routed to one of the routes that reached the required score.

Constructor Summary

Constructors
Constructor and Description

Router()
Constructor.

Router(Context context)
Constructor.

Constructors
Constructor and Description
`Router()` Constructor.
`Router(Context context)` Constructor.

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`TemplateRoute`	`attach(Restlet target)` Attaches a target Restlet to this router with an empty URI pattern.
`TemplateRoute`	`attach(Restlet target, int matchingMode)` Attaches a target Restlet to this router with an empty URI pattern.
`TemplateRoute`	`attach(java.lang.String pathTemplate, java.lang.Class<? extends ServerResource> targetClass)` Attaches a target Resource class to this router based on a given URI pattern.
`TemplateRoute`	`attach(java.lang.String pathTemplate, java.lang.Class<? extends ServerResource> targetClass, int matchingMode)` Attaches a target Resource class to this router based on a given URI pattern.
`TemplateRoute`	`attach(java.lang.String pathTemplate, Restlet target)` Attaches a target Restlet to this router based on a given URI pattern.
`TemplateRoute`	`attach(java.lang.String pathTemplate, Restlet target, int matchingMode)` Attaches a target Restlet to this router based on a given URI pattern.
`TemplateRoute`	`attachDefault(java.lang.Class<? extends ServerResource> defaultTargetClass)` Attaches a Resource class to this router as the default target to invoke when no route matches.
`TemplateRoute`	`attachDefault(Restlet defaultTarget)` Attaches a Restlet to this router as the default target to invoke when no route matches.
`protected TemplateRoute`	`createRoute(java.lang.String uriPattern, Restlet target)` Creates a new route for the given URI pattern and target.
`protected TemplateRoute`	`createRoute(java.lang.String uriPattern, Restlet target, int matchingMode)` Creates a new route for the given URI pattern, target and matching mode.
`void`	`detach(java.lang.Class<?> targetClass)` Detaches the target from this router.
`void`	`detach(Restlet target)` Detaches the target from this router.
`protected void`	`doHandle(Restlet next, Request request, Response response)` Effectively handles the call using the selected next `Restlet`, typically the selected `Route`.
`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`	`getDefaultMatchingQuery()` 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 attempts.
`protected int`	`getMatchingMode(Restlet target)` Returns the matching mode for the target Restlet.
`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 milliseconds before a new attempt is made.
`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.
`protected void`	`logRoute(Route route)` Logs the route selected.
`TemplateRoute`	`redirectPermanent(java.lang.String pathTemplate, java.lang.String targetUri)` Attaches a permanent redirection to this router based on a given URI pattern.
`TemplateRoute`	`redirectSeeOther(java.lang.String pathTemplate, java.lang.String targetUri)` Attaches a redirection to this router based on a given URI pattern.
`TemplateRoute`	`redirectTemporary(java.lang.String pathTemplate, java.lang.String targetUri)` Attaches a temporary redirection to this router based on a given URI pattern.
`void`	`setDefaultMatchingMode(int defaultMatchingMode)` Sets the default matching mode to use when selecting routes based on URIs.
`void`	`setDefaultMatchingQuery(boolean defaultMatchingQuery)` 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`	`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 milliseconds before a new attempt is made.
`void`	`setRoutes(RouteList routes)` Sets the modifiable list of routes.
`void`	`setRoutingMode(int routingMode)` Sets the routing mode.
`void`	`start()` Starts the filter and the attached routes.
`void`	`stop()` Stops the filter and the attached routes.

Methods inherited from class org.restlet.Restlet
createFinder, finalize, getApplication, getAuthor, getContext, getDescription, getFinderClass, getLogger, getName, getOwner, handle, handle, handle, isStarted, isStopped, setAuthor, setContext, setDescription, setFinderClass, setName, setOwner

Methods inherited from class java.lang.Object
clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Field Detail
  - MODE_BEST_MATCH
```
public static final int MODE_BEST_MATCH
```
    Each call will be routed to the route with the best score, if the required score is reached. See RouteList.getBest(Request, Response, float) method for implementation details.
    
    See Also:
    
    Constant Field Values
  - MODE_CUSTOM
```
public static final int MODE_CUSTOM
```
    Each call will be routed according to a custom mode. Override the getCustom(Request, Response) method to provide your own logic.
    
    See Also:
    
    Constant Field Values
  - MODE_FIRST_MATCH
```
public static final int MODE_FIRST_MATCH
```
    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 RouteList.getFirst(Request, Response, float) method for implementation details.
    
    See Also:
    
    Constant Field Values
  - MODE_LAST_MATCH
```
public static final int MODE_LAST_MATCH
```
    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 RouteList.getLast(Request, Response, float) method for implementation details.
    
    See Also:
    
    Constant Field Values
  - MODE_NEXT_MATCH
```
public static final int MODE_NEXT_MATCH
```
    Each call is 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 RouteList.getNext(Request, Response, float) method for implementation details.
    
    See Also:
    
    Constant Field Values
  - MODE_RANDOM_MATCH
```
public static final int MODE_RANDOM_MATCH
```
    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 initial random route selected with no match, then we return null. Unless all the routes score above the required score, this mode will result in non-uniform distribution of calls. See RouteList.getRandom(Request, Response, float) method for implementation details.
    
    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 TemplateRoute attach(Restlet target)
```
    Attaches a target Restlet to this router with an empty URI pattern. A new route using the matching mode returned by getMatchingMode(Restlet) 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 TemplateRoute attach(Restlet target,
                            int matchingMode)
```
    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.
    
    matchingMode - The matching mode.
    
    Returns:
    
    The created route.
  - attach
```
public TemplateRoute attach(java.lang.String pathTemplate,
                            java.lang.Class<? extends ServerResource> targetClass)
```
    Attaches a target Resource class to this router based on a given URI pattern. A new route using the matching mode returned by getMatchingMode(Restlet) will be added routing to the target when calls with a URI matching the pattern will be received.
    
    Parameters:
    
    pathTemplate - The URI path template that must match the relative part of the resource URI.
    
    targetClass - The target Resource class to attach.
    
    Returns:
    
    The created route.
  - attach
```
public TemplateRoute attach(java.lang.String pathTemplate,
                            java.lang.Class<? extends ServerResource> targetClass,
                            int matchingMode)
```
    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:
    
    pathTemplate - The URI path template that must match the relative part of the resource URI.
    
    targetClass - The target Resource class to attach.
    
    matchingMode - The matching mode.
    
    Returns:
    
    The created route.
  - attach
```
public TemplateRoute attach(java.lang.String pathTemplate,
                            Restlet target)
```
    Attaches a target Restlet to this router based on a given URI pattern. A new route using the matching mode returned by getMatchingMode(Restlet) will be added routing to the target when calls with a URI matching the pattern will be received.
    
    Parameters:
    
    pathTemplate - The URI path template that must match the relative part of the resource URI.
    
    target - The target Restlet to attach.
    
    Returns:
    
    The created route.
  - attach
```
public TemplateRoute attach(java.lang.String pathTemplate,
                            Restlet target,
                            int matchingMode)
```
    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:
    
    pathTemplate - The URI path template that must match the relative part of the resource URI.
    
    target - The target Restlet to attach.
    
    matchingMode - The matching mode.
    
    Returns:
    
    The created route.
  - attachDefault
```
public TemplateRoute attachDefault(java.lang.Class<? extends ServerResource> 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 TemplateRoute 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.
  - createRoute
```
protected TemplateRoute createRoute(java.lang.String uriPattern,
                                    Restlet target)
```
    Creates a new route for the given URI pattern and target. The route will match the URI query string depending on the result of getDefaultMatchingQuery() and the matching mode will be given by getMatchingMode(Restlet).
    
    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.
  - createRoute
```
protected TemplateRoute createRoute(java.lang.String uriPattern,
                                    Restlet target,
                                    int matchingMode)
```
    Creates a new route for the given URI pattern, target and matching mode. The route will match the URI query string depending on the result of getDefaultMatchingQuery().
    
    Parameters:
    
    uriPattern - The URI pattern that must match the relative part of the resource URI.
    
    target - The target Restlet to attach.
    
    matchingMode - The matching mode.
    
    Returns:
    
    The created route.
  - detach
```
public void detach(java.lang.Class<?> targetClass)
```
    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:
    
    targetClass - The target class to detach.
  - 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.
  - doHandle
```
protected void doHandle(Restlet next,
                        Request request,
                        Response response)
```
    Effectively handles the call using the selected next Restlet, typically the selected Route. By default, it just invokes the next Restlet.
    
    Parameters:
    
    next - The next Restlet to invoke.
    
    request - The request.
    
    response - The response.
  - getCustom
```
protected Route getCustom(Request request,
                          Response response)
```
    Returns the matched route according to a custom algorithm. To use in combination of the MODE_CUSTOM option. The default implementation (to be overridden), 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_EQUALS.
    
    Returns:
    
    The default matching mode.
  - getDefaultMatchingQuery
```
public boolean getDefaultMatchingQuery()
```
    Returns the default setting for whether the routing should be done on URIs with or without taking into account query string. By default, it returns false.
    
    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 attempts.
    
    Returns:
    
    The default route tested if no other one was available.
  - getMatchingMode
```
protected int getMatchingMode(Restlet target)
```
    Returns the matching mode for the target Restlet. By default it returns getDefaultMatchingMode(). If the target is an instance of Directory or Router then the mode returned is Template.MODE_STARTS_WITH to allow further routing by those objects. If the target is an instance of Filter, then it returns the matching mode for the Filter.getNext() Restlet recursively.
    
    Parameters:
    
    target - The target Restlet.
    
    Returns:
    
    The preferred matching mode.
  - 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. By default, it returns 0.5.
    
    Returns:
    
    The minimum score required to have a match.
  - getRetryDelay
```
public long getRetryDelay()
```
    Returns the delay in milliseconds before a new attempt is made. The default value is 500.
    
    Returns:
    
    The delay in milliseconds before a new attempt is made.
  - 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. By default, it returns the MODE_FIRST_MATCH 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.
    
    Specified by:
    
    handle in interface Uniform
    
    Overrides:
    
    handle in class Restlet
    
    Parameters:
    
    request - The request to handle.
    
    response - The response to update.
  - logRoute
```
protected void logRoute(Route route)
```
    Logs the route selected.
    
    Parameters:
    
    route - The route selected.
  - redirectPermanent
```
public TemplateRoute redirectPermanent(java.lang.String pathTemplate,
                                       java.lang.String targetUri)
```
    Attaches a permanent redirection to this router based on a given URI pattern. The client is expected to reuse the same method for the new request.
    
    Parameters:
    
    pathTemplate - The URI path template that must match the relative part of the resource URI.
    
    targetUri - The target URI.
    
    Returns:
    
    The created route.
  - redirectSeeOther
```
public TemplateRoute redirectSeeOther(java.lang.String pathTemplate,
                                      java.lang.String targetUri)
```
    Attaches a redirection to this router based on a given URI pattern. It 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:
    
    pathTemplate - The URI path template that must match the relative part of the resource URI.
    
    targetUri - The target URI.
    
    Returns:
    
    The created route.
  - redirectTemporary
```
public TemplateRoute redirectTemporary(java.lang.String pathTemplate,
                                       java.lang.String targetUri)
```
    Attaches a temporary redirection to this router based on a given URI pattern. The client is expected to reuse the same method for the new request.
    
    Parameters:
    
    pathTemplate - The URI path template that must match the relative part of the resource URI.
    
    targetUri - The target URI.
    
    Returns:
    
    The created route.
  - setDefaultMatchingMode
```
public void setDefaultMatchingMode(int defaultMatchingMode)
```
    Sets the default matching mode to use when selecting routes based on URIs. By default it is set to Template.MODE_EQUALS.
    
    Parameters:
    
    defaultMatchingMode - The default matching mode.
  - setDefaultMatchingQuery
```
public void setDefaultMatchingQuery(boolean defaultMatchingQuery)
```
    Sets the default setting for whether the routing should be done on URIs with or without taking into account query string. By default, it is set to false.
    
    Parameters:
    
    defaultMatchingQuery - 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.
  - 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. By default, it is set to 0.5.
    
    Parameters:
    
    score - The score required to have a match.
  - setRetryDelay
```
public void setRetryDelay(long retryDelay)
```
    Sets the delay in milliseconds before a new attempt is made. By default, it is set to 500.
    
    Parameters:
    
    retryDelay - The delay in milliseconds before a new attempt is made.
  - 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. By default, it is set to the MODE_FIRST_MATCH mode.
    
    Parameters:
    
    routingMode - The routing mode.
  - start
```
public void start()
           throws java.lang.Exception
```
    Starts the filter and the attached routes.
    
    Overrides:
    
    start in class Restlet
    
    Throws:
    
    java.lang.Exception
  - stop
```
public void stop()
          throws java.lang.Exception
```
    Stops the filter and the attached routes.
    
    Overrides:
    
    stop in class Restlet
    
    Throws:
    
    java.lang.Exception

Class Router

Field Summary

Constructor Summary

Method Summary

Methods inherited from class org.restlet.Restlet

Methods inherited from class java.lang.Object

Field Detail

MODE_BEST_MATCH

MODE_CUSTOM

MODE_FIRST_MATCH

MODE_LAST_MATCH

MODE_NEXT_MATCH

MODE_RANDOM_MATCH

Constructor Detail

Router

Router

Method Detail

attach

attach

attach

attach

attach

attach

attachDefault

attachDefault

createRoute

createRoute

detach

detach

doHandle

getCustom

getDefaultMatchingMode

getDefaultMatchingQuery

getDefaultRoute

getMatchingMode

getMaxAttempts

getNext

getRequiredScore

getRetryDelay

getRoutes

getRoutingMode

handle

logRoute

redirectPermanent

redirectSeeOther

redirectTemporary

setDefaultMatchingMode

setDefaultMatchingQuery

setDefaultRoute

setMaxAttempts

setRequiredScore

setRetryDelay

setRoutes

setRoutingMode

start

stop