Module io.inverno.mod.http.base
Package io.inverno.mod.http.base.router

Class RoutingLink<A,B,C extends Route<A>,D extends RouteExtractor<A,C>>

java.lang.Object
io.inverno.mod.http.base.router.RoutingLink<A,B,C,D>
Type Parameters:
A - the resource type
B - the input type
C - the route type
D - the route extractor type
Direct Known Subclasses:
AcceptLanguageRoutingLink, AuthorityRoutingLink, ContentRoutingLink, ErrorRoutingLink, HeadersRoutingLink, InboundAcceptContentRoutingLink, MethodRoutingLink, OutboundAcceptContentRoutingLink, PathRoutingLink, QueryParametersRoutingLink, URIRoutingLink, WebSocketSubprotocolRoutingLink
public abstract class RoutingLink<A,B,C extends Route<A>,D extends RouteExtractor<A,C>> extends Object

A routing link is used in an AbstractRouter to implement a routing chain.

A routing chain is composed of multiple links that each matches a particular criteria from a router input, the result is a tree of criteria which allows to efficiently resolve the resources matching a particular input.

Resolution is done top to bottom which means an input can't match different branch in the routing tree, each link must determine the next best matching link and so on until we get to the end of the chain, it is not possible to change branch. The advantage of this approach is that for a given input we'll always resolve exactly one resource or no resource which is what is expected from a router.

A routing chain can be created using RoutingLink.ChainBuilder as follows: 


 RoutingLink<SampleResource, SampleInput, SampleRoute, SampleRouteExtractor> firstLink = RoutingLink
     .link(ARoutingLink::new)
     .link(BRoutingLink::new)
     .link(ign -> new CRoutingLink())
     .getRoutingChain();

In above example, the routing chain is composed of ARoutinglink, BRoutinglink and CRoutinglink which are evaluated in that order when resolving resources. Unlike ARoutinglink and BRoutinglink, CRoutinglink is at the end of the chain and as a result the next link factory is ignored in order to terminate the chain.

Since:
1.12
Author:
Jeremy Kuhn

  • Constructor Details

    • RoutingLink

      protected RoutingLink()

      Creates a terminal routing link.

    • RoutingLink

      protected RoutingLink(Supplier<RoutingLink<A,B,C,D>> nextLinkFactory)

      Creates a routing link chained to a next link.

      Parameters:
      nextLinkFactory - the next link factory

  • Method Details

    • createLink

      protected final RoutingLink<A,B,C,D> createLink()

      Creates a link.

      A link is created when a route is set in the routing chain and the link can handle the route (i.e. the route defines a criteria handled by the link).

      Returns:
      a new routing link

    • canLink

      protected abstract boolean canLink(C route)

      Determines whether the link can link the specified route.

      A route is linkable by a link when it defines a criteria handled by the link so basically when the link is able to route an input based on that particular criteria (e.g. a path, an HTTP method...).

      Parameters:
      route - a route
      Returns:
      true if the link can

    • getLink

      protected abstract RoutingLink<A,B,C,D> getLink(C route)

      Returns the next link in the routing chain that is matching the specified route.

      Parameters:
      route - a route
      Returns:
      the next routing link in the routing chain or null if there is no link matching the route

    • getOrSetLink

      protected abstract RoutingLink<A,B,C,D> getOrSetLink(C route)

      Returns or sets the next link in the routing chain that is matching the specified route.

      If there is no link matching the route, a new link shall be created and set in the routing chain.

      Parameters:
      route - a route
      Returns:
      the next routing link in the routing chain

    • getLinks

      protected abstract Collection<RoutingLink<A,B,C,D>> getLinks()

      Returns all links bound to the link.

      Returns:
      the list of links bound to the link

    • removeLink

      protected abstract void removeLink(C route)

      Removes the link matching the specified route.

      Parameters:
      route - a route

    • refreshEnabled

      protected abstract void refreshEnabled()

      Refreshes enabled links.

      This method is invoked after a change in the routing chain in order to optimize the resource resolution process by identifying disabled links as close as possible from the beginning of the chain.

    • extractLinks

      protected abstract void extractLinks(D routeExtractor)

      Populates the specified route extractor with the criteria managed by the link.

      This basically comes down to extracting the links managed by the link.

      Parameters:
      routeExtractor - a route extractor

    • resolveLink

      protected abstract RoutingLink<A,B,C,D> resolveLink(B input)

      Resolves the link best matching the specified input.

      The link is resolved by comparing the criteria coming from the routes to the criteria defined in the input.

      Parameters:
      input - an input
      Returns:
      the matching link or null if no route matching the input was defined in the link

    • resolveAllLink

      protected abstract List<RoutingLink<A,B,C,D>> resolveAllLink(B input)

      Resolves all links matching the specified input.

      Links are resolved by comparing the criteria coming from the routes to the criteria defined in the input.

      Parameters:
      input - an input
      Returns:
      a list of links sorted from the best matching to the least matching or an empty list if no route matching the input was defined in the link

    • link

      public static <A, B, C extends Route<A>, D extends RouteExtractor<A, C>> RoutingLink.ChainBuilder<A,B,C,D> link(RoutingLink.ChainBuilder<A,B,C,D> link)

      Creates a routing chain.

      Type Parameters:
      A - the resource type
      B - the input type
      C - the route type
      D - the route extractor type
      Parameters:
      link - the first link builder
      Returns:
      a chain builder

    • setRoute

      public final void setRoute(C route)

      Sets the specified route in the routing chain.

      Parameters:
      route - the route to set

    • removeRoute

      public final void removeRoute(C route)

      Removes the specified route from the routing chain.

      Parameters:
      route - the route to remove

    • enableRoute

      public final void enableRoute(C route)

      Enables the specified route in the routing chain.

      Parameters:
      route - the route to enable

    • disableRoute

      public final void disableRoute(C route)

      Disables the specified route in the routing chain.

      Parameters:
      route - the route to disable

    • isEnabled

      public final boolean isEnabled()

      Determines whether the link is enabled in the routing chain.

      A link is enabled when it is not disabled and it has enabled routing links.

      Returns:
      true if the link is enabled, false otherwise

    • extractRoutes

      public final void extractRoutes(D routeExtractor)

      Extracts routes defined in the routing chain.

      Parameters:
      routeExtractor - a route extractor

    • resolve

      public final A resolve(B input)

      Resolves the resource best matching the specified input.

      Parameters:
      input - an input
      Returns:
      a resource or null if no route matching the input was defined in the routing chain

    • resolveAll

      public final Collection<A> resolveAll(B input)

      Resolves all resources matching the specified input sorted from best matching to least matching.

      Parameters:
      input - an input
      Returns:
      a list of matching resources

    • currentOrErrorRoutingLink

      protected final RoutingLink<A,B,C,D> currentOrErrorRoutingLink(Supplier<? extends Throwable> exceptionSupplier)

      Returns a routing link wrapper that returns either the current resource (see getCurrentResource()) or throw an exception if no resource has been defined.

      This is typically used by RoutingLink implementors in order to throw errors instead of returning no resources.

      Parameters:
      exceptionSupplier - the exception supplier
      Returns:
      a routing link wrapper
      See Also:

    • bestMatchingRoutingLink

      protected final RoutingLink<A,B,C,D> bestMatchingRoutingLink(List<RoutingLink<A,B,C,D>> links)

      Returns a routing link wrapper that returns the best matching link from a list of matching links.

      This is typically used by RoutingLink implementors when it is not possible to resolve the best matching resource from a single link and resolve(Object) must be invoked successively on the element of a list of matching links, ordered from the best matching to the least matching, until a resource is resolved.

      null can be specified in the list of links to identify the default link.

      Parameters:
      links - a list of routing links ordered from the best matching to the least matching
      Returns:
      a routing link wrapper
      See Also: