Package org.forgerock.services.routing

Class AbstractRouter<T extends AbstractRouter<T,​R,​H,​D>,​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.

    • 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.

      • getBestApiRoute

        protected Pair<Context,​H> getBestApiRoute​(Context context,
                                                R request)
                                         throws IncomparableRouteMatchException
        Get the best route for an API request. This is differs from getBestRoute(Context, Object) in that it also checks to see whether this router itself is being addressed, and returns the merged descriptor for all the routes if so.
        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.

      • getSelfApiHandler

        protected abstract Pair<RouteMatcher<R>,​H> getSelfApiHandler()
        Return a Describable handler that returns this AbstractRouter's internal api description from the Describable.handleApiRequest(Context, Object) method. All other methods should throw an UnsupportedOperationException, as they should never be used.
        Returns:
        The describable handler.

      • 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<T extends AbstractRouter<T,​R,​H,​D>,​R>
        Parameters:
        producer - The API producer that provides general information to be built into the descriptor.
        Returns:
        The description object.

      • 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<T extends AbstractRouter<T,​R,​H,​D>,​R>
        Parameters:
        context - The request context.
        request - The request.
        Returns:
        The descriptor.

      • buildApi

        protected D buildApi​(ApiProducer<D> producer)
        Build an api with a given ApiProducer.
        Parameters:
        producer - The given ApiProducer to use.
        Returns:
        an api.