AbstractRouter (org.openidentityplatform.commons.parent 2.2.3 Documentation)

java.lang.Object
- org.forgerock.services.routing.AbstractRouter<T,R,H,D>

Type Parameters:

T - The type of the router.

R - The type of the request.

H - The type of the handler that will be used to handle routing requests.

D - The type of descriptor object that the APIs supported by this router can be described using.

All Implemented Interfaces:

Describable<D,R>, Describable.Listener

Direct Known Subclasses:

Router, Router
```
public abstract class AbstractRouter<T extends AbstractRouter<T,R,H,D>,R,H,D>
extends Object
implements Describable<D,R>, Describable.Listener
```
An abstract base class for implementing routers. Routers are common in applications which need to process incoming requests based on varying criteria such as the target endpoint, API version expectations, client criteria (e.g. source address), etc. This base class is designed to be protocol and framework independent. Frameworks should sub-class an abstract router in order to provide framework specific behavior.
Generally speaking a router comprises of a series of routes, each of which is composed of a RouteMatcher and a handler (H). When a request (R) is received the router invokes each RouteMatcher to see if it matches and then invokes the associated handler if it is the best match.
Concrete implementations of AbstractRouter existing in both CHF and CREST.

Nested Class Summary
- Nested classes/interfaces inherited from interface org.forgerock.services.descriptor.Describable
  Describable.Listener

Field Summary

Fields
Modifier and Type Field and Description

protected D api
Api of the current router.

protected RouteMatcher<R> thisRouterUriMatcher
Matches the current route.

Fields
Modifier and Type	Field and Description
`protected D`	`api` Api of the current router.
`protected RouteMatcher<R>`	`thisRouterUriMatcher` Matches the current route.

Constructor Summary

Constructors
Modifier	Constructor and Description
`protected`	`AbstractRouter()` Creates a new abstract router with no routes defined.
`protected`	`AbstractRouter(AbstractRouter<T,R,H,D> router)` Creates a new router containing the same routes and default route as the provided router.

Method Summary

All Methods Instance Methods Abstract Methods Concrete Methods
Modifier and Type	Method and Description
`T`	`addAllRoutes(T router)` Adds all of the routes defined in the provided router to this router.
`void`	`addDescriptorListener(Describable.Listener listener)` Add a listener for API Descriptor changes.
`T`	`addRoute(RouteMatcher<R> matcher, H handler)` Adds a new route to this router for the provided handler.
`D`	`api(ApiProducer<D> producer)` Provide the API description for the component.
`protected D`	`buildApi(ApiProducer<D> producer)` Build an api with a given `ApiProducer`.
`protected Pair<Context,H>`	`getBestRoute(Context context, R request)` Finds the best route that matches the given request based on the route matchers of the registered routes.
`protected Map<RouteMatcher<R>,H>`	`getRoutes()` Gets all registered routes on this router.
`protected abstract T`	`getThis()` Returns this `AbstractRouter` instance, typed correctly.
`D`	`handleApiRequest(Context context, R request)` Handle a request for the API Descriptor.
`void`	`notifyDescriptorChange()` Implement this method to handle changes to API Descriptors.
`T`	`removeAllRoutes()` Removes all of the routes from this router.
`void`	`removeDescriptorListener(Describable.Listener listener)` Remove a listener from API Descriptor changes.
`boolean`	`removeRoute(RouteMatcher<R>... routes)` Removes one or more routes from this router.
`T`	`setDefaultRoute(H handler)` Sets the handler to be used as the default route for requests which do not match any of the other defined routes.
`protected abstract RouteMatcher<R>`	`uriMatcher(RoutingMode mode, String pattern)` Create a URI matcher suitable for the request type `<R>`.

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

- Field Detail
  - thisRouterUriMatcher
```
protected final RouteMatcher<R> thisRouterUriMatcher
```
    Matches the current route.
  - api
```
protected D api
```
    Api of the current router.
- Constructor Detail
  - AbstractRouter
```
protected AbstractRouter()
```
    Creates a new abstract router with no routes defined.
  - AbstractRouter
```
protected AbstractRouter(AbstractRouter<T,R,H,D> router)
```
    Creates a new router containing the same routes and default route as the provided router. Changes to the returned router's routing table will not impact the provided router.
    
    Parameters:
    
    router - The router to be copied.
- Method Detail
  - getThis
```
protected abstract T getThis()
```
    Returns this AbstractRouter instance, typed correctly.
    
    Returns:
    
    This AbstractRouter instance.
  - getRoutes
```
protected final Map<RouteMatcher<R>,H> getRoutes()
```
    Gets all registered routes on this router.
    
    Returns:
    
    All registered routes.
  - addAllRoutes
```
public final T addAllRoutes(T router)
```
    Adds all of the routes defined in the provided router to this router. New routes may be added while this router is processing requests.
    
    Parameters:
    
    router - The router whose routes are to be copied into this router.
    
    Returns:
    
    This router instance.
  - addRoute
```
public final T addRoute(RouteMatcher<R> matcher,
                        H handler)
```
    Adds a new route to this router for the provided handler. New routes may be added while this router is processing requests.
    The provided matcher can be used to remove this route later.
    
    Parameters:
    
    matcher - The RouteMatcher that will evaluate whether the incoming request matches this route.
    
    handler - The handler to which matching requests will be routed.
    
    Returns:
    
    This router instance.
  - setDefaultRoute
```
public final T setDefaultRoute(H handler)
```
    Sets the handler to be used as the default route for requests which do not match any of the other defined routes.
    
    Parameters:
    
    handler - The handler to be used as the default route.
    
    Returns:
    
    This router instance.
  - removeAllRoutes
```
public final T removeAllRoutes()
```
    Removes all of the routes from this router. Routes may be removed while this router is processing requests.
    
    Returns:
    
    This router instance.
  - removeRoute
```
@SafeVarargs
public final boolean removeRoute(RouteMatcher<R>... routes)
```
    Removes one or more routes from this router. Routes may be removed while this router is processing requests.
    
    Parameters:
    
    routes - The RouteMatchers of the routes to be removed.
    
    Returns:
    
    true if at least one of the routes was found and removed.
  - getBestRoute
```
protected Pair<Context,H> getBestRoute(Context context,
                                       R request)
                                throws IncomparableRouteMatchException
```
    Finds the best route that matches the given request based on the route matchers of the registered routes. If no registered route matches at all then the default route is chosen, if present.
    
    Parameters:
    
    context - The request context.
    
    request - The request to be matched against the registered routes.
    
    Returns:
    
    A Pair containing the decorated Context and the handler which is the best match for the given request or null if no route was found.
    
    Throws:
    
    IncomparableRouteMatchException - If any of the registered RouteMatchers could not be compared to one another.
  - api
```
public D api(ApiProducer<D> producer)
```
    Description copied from interface: Describable
    
    Provide the API description for the component. This method should perform the heavy-lifting of computing the API descriptor, and should be expected to be called rarely. Upstream handlers should call this method in order to compose all of their downstream API Descriptors into a single descriptor.
    
    Specified by:
    
    api in interface Describable<D,R>
    
    Parameters:
    
    producer - The API producer that provides general information to be built into the descriptor.
    
    Returns:
    
    The description object.
  - buildApi
```
protected D buildApi(ApiProducer<D> producer)
```
    Build an api with a given ApiProducer.
    
    Parameters:
    
    producer - The given ApiProducer to use.
    
    Returns:
    
    an api.
  - uriMatcher
```
protected abstract RouteMatcher<R> uriMatcher(RoutingMode mode,
                                              String pattern)
```
    Create a URI matcher suitable for the request type <R>.
    
    Parameters:
    
    mode - The routing mode.
    
    pattern - The pattern.
    
    Returns:
    
    The matcher.
  - handleApiRequest
```
public D handleApiRequest(Context context,
                          R request)
```
    Description copied from interface: Describable
    
    Handle a request for the API Descriptor. This method should not do any computation, but should return the already computed descriptor.
    
    Specified by:
    
    handleApiRequest in interface Describable<D,R>
    
    Parameters:
    
    context - The request context.
    
    request - The request.
    
    Returns:
    
    The descriptor.
  - addDescriptorListener
```
public void addDescriptorListener(Describable.Listener listener)
```
    Description copied from interface: Describable
    
    Add a listener for API Descriptor changes. The described object should call all the listeners.
    
    Specified by:
    
    addDescriptorListener in interface Describable<D,R>
    
    Parameters:
    
    listener - The listener.
  - removeDescriptorListener
```
public void removeDescriptorListener(Describable.Listener listener)
```
    Description copied from interface: Describable
    
    Remove a listener from API Descriptor changes.
    
    Specified by:
    
    removeDescriptorListener in interface Describable<D,R>
    
    Parameters:
    
    listener - The listener.
  - notifyDescriptorChange
```
public void notifyDescriptorChange()
```
    Description copied from interface: Describable.Listener
    
    Implement this method to handle changes to API Descriptors.
    
    Specified by:
    
    notifyDescriptorChange in interface Describable.Listener

Class AbstractRouter<T extends AbstractRouter<T,R,H,D>,R,H,D>

Nested Class Summary

Nested classes/interfaces inherited from interface org.forgerock.services.descriptor.Describable

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

thisRouterUriMatcher

api

Constructor Detail

AbstractRouter

AbstractRouter

Method Detail

getThis

getRoutes

addAllRoutes

addRoute

setDefaultRoute

removeAllRoutes

removeRoute

getBestRoute

api

buildApi

uriMatcher

handleApiRequest

addDescriptorListener

removeDescriptorListener

notifyDescriptorChange