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

java.lang.Object
- org.forgerock.services.routing.AbstractRouter<Router,Request,RequestHandler,ApiDescription>
- - org.forgerock.json.resource.Router

All Implemented Interfaces:

RequestHandler, Describable<ApiDescription,Request>, Describable.Listener
```
public class Router
extends AbstractRouter<Router,Request,RequestHandler,ApiDescription>
implements RequestHandler
```
A router which routes requests based on route predicates. Each route is comprised of a route matcher and a corresponding handler, when routing a request the router will call RouteMatcher.evaluate(org.forgerock.services.context.Context, R) for each registered route and use the returned RouteMatcher to determine which route best matches the request.
Routes may be added and removed from a router as follows:
```
 Handler users = ...;
 Router router = new Router();
 RouteMatcher routeOne = RouteMatchers.requestUriMatcher(EQUALS, "users");
 RouteMatcher routeTwo = RouteMatchers.requestUriMatcher(EQUALS, "users/{userId}");
 router.addRoute(routeOne, users);
 router.addRoute(routeTwo, users);

 // Deregister a route.
 router.removeRoute(routeOne, routeTwo);
 
```
See Also:

AbstractRouter, RouteMatchers

Nested Class Summary

Nested Classes
Modifier and Type Class and Description

static class Router.UriTemplate
Represents a URI template string that will be used to match and route incoming requests.
- Nested classes/interfaces inherited from interface org.forgerock.services.descriptor.Describable
  Describable.Listener

Nested Classes
Modifier and Type	Class and Description
`static class`	`Router.UriTemplate` Represents a URI template string that will be used to match and route incoming requests.

Field Summary
- Fields inherited from class org.forgerock.services.routing.AbstractRouter
  api, thisRouterUriMatcher

Constructor Summary

Constructors
Constructor and Description
`Router()` Creates a new router with no routes defined.
`Router(AbstractRouter<Router,Request,RequestHandler,ApiDescription> router)` Creates a new router containing the same routes and default route as the provided router.

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`RouteMatcher<Request>`	`addRoute(Router.UriTemplate uriTemplate, CollectionResourceProvider provider)` Adds a new route to this router for the provided collection resource provider.
`RouteMatcher<Request>`	`addRoute(Router.UriTemplate uriTemplate, SingletonResourceProvider provider)` Adds a new route to this router for the provided singleton resource provider.
`RouteMatcher<Request>`	`addRoute(RoutingMode mode, Router.UriTemplate uriTemplate, RequestHandler handler)` Adds a new route to this router for the provided request handler.
`RouteMatcher<Request>`	`addRoute(Version version, CollectionResourceProvider provider)` Adds a new route to this router for the provided collection resource provider.
`RouteMatcher<Request>`	`addRoute(Version version, RequestHandler handler)` Adds a new route to this router for the provided request handler.
`RouteMatcher<Request>`	`addRoute(Version version, SingletonResourceProvider provider)` Adds a new route to this router for the provided singleton resource provider.
`protected Router`	`getThis()` Returns this `AbstractRouter` instance, typed correctly.
`Promise<ActionResponse,ResourceException>`	`handleAction(Context context, ActionRequest request)` Handles performing an action on a resource, and optionally returns an associated result.
`ApiDescription`	`handleApiRequest(Context context, Request request)` Handle a request for the API Descriptor.
`Promise<ResourceResponse,ResourceException>`	`handleCreate(Context context, CreateRequest request)` Adds a new JSON resource, returning a `Promise` that will be completed when the resource has been added.
`Promise<ResourceResponse,ResourceException>`	`handleDelete(Context context, DeleteRequest request)` Deletes a JSON resource, returning a `Promise` that will be completed when the resource has been deleted.
`Promise<ResourceResponse,ResourceException>`	`handlePatch(Context context, PatchRequest request)` Updates a JSON resource by applying a set of changes to its existing content, returning a `Promise` that will be completed when the resource has been updated.
`Promise<QueryResponse,ResourceException>`	`handleQuery(Context context, QueryRequest request, QueryResourceHandler handler)` Searches for all JSON resources matching a user specified set of criteria, returning a `Promise` that will be completed when the search has completed.
`Promise<ResourceResponse,ResourceException>`	`handleRead(Context context, ReadRequest request)` Reads a JSON resource, returning a `Promise` that will be completed when the resource has been read.
`Promise<ResourceResponse,ResourceException>`	`handleUpdate(Context context, UpdateRequest request)` Updates a JSON resource by replacing its existing content with new content, returning a `Promise` that will be completed when the resource has been updated.
`protected RouteMatcher<Request>`	`uriMatcher(RoutingMode mode, String pattern)` Create a URI matcher suitable for the request type `<R>`.
`static Router.UriTemplate`	`uriTemplate(String template)` Creates a `Router.UriTemplate` from a URI template string that will be used to match and route incoming requests.

Methods inherited from class org.forgerock.services.routing.AbstractRouter
addAllRoutes, addDescriptorListener, addRoute, api, buildApi, getBestRoute, getRoutes, notifyDescriptorChange, removeAllRoutes, removeDescriptorListener, removeRoute, setDefaultRoute

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

- Constructor Detail
  - Router
```
public Router()
```
    Creates a new router with no routes defined.
  - Router
```
public Router(AbstractRouter<Router,Request,RequestHandler,ApiDescription> 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 Router getThis()
```
    Description copied from class: AbstractRouter
    
    Returns this AbstractRouter instance, typed correctly.
    
    Specified by:
    
    getThis in class AbstractRouter<Router,Request,RequestHandler,ApiDescription>
    
    Returns:
    
    This AbstractRouter instance.
  - uriMatcher
```
protected RouteMatcher<Request> uriMatcher(RoutingMode mode,
                                           String pattern)
```
    Description copied from class: AbstractRouter
    
    Create a URI matcher suitable for the request type <R>.
    
    Specified by:
    
    uriMatcher in class AbstractRouter<Router,Request,RequestHandler,ApiDescription>
    
    Parameters:
    
    mode - The routing mode.
    
    pattern - The pattern.
    
    Returns:
    
    The matcher.
  - addRoute
```
public RouteMatcher<Request> addRoute(Router.UriTemplate uriTemplate,
                                      CollectionResourceProvider provider)
```
    Adds a new route to this router for the provided collection resource provider. New routes may be added while this router is processing requests.
    The provided URI template must match the resource collection itself, not resource instances. For example:
```
 CollectionResourceProvider users = ...;
 Router router = new Router();

 // This is valid usage: the template matches the resource collection.
 router.addRoute(Router.uriTemplate("users"), users);

 // This is invalid usage: the template matches resource instances.
 router.addRoute(Router.uriTemplate("users/{userId}"), users);
 
```
    Parameters:
    
    uriTemplate - The URI template which request resource names must match.
    
    provider - The collection resource provider to which matching requests will be routed.
    
    Returns:
    
    The RouteMatcher for the route that can be used to remove the route at a later point.
  - addRoute
```
public RouteMatcher<Request> addRoute(Router.UriTemplate uriTemplate,
                                      SingletonResourceProvider provider)
```
    Adds a new route to this router for the provided singleton resource provider. New routes may be added while this router is processing requests.
    
    Parameters:
    
    uriTemplate - The URI template which request resource names must match.
    
    provider - The singleton resource provider to which matching requests will be routed.
    
    Returns:
    
    The RouteMatcher for the route that can be used to remove the route at a later point.
  - addRoute
```
public RouteMatcher<Request> addRoute(RoutingMode mode,
                                      Router.UriTemplate uriTemplate,
                                      RequestHandler handler)
```
    Adds a new route to this router for the provided request handler. New routes may be added while this router is processing requests.
    
    Parameters:
    
    mode - Indicates how the URI template should be matched against resource names.
    
    uriTemplate - The URI template which request resource names must match.
    
    handler - The request handler to which matching requests will be routed.
    
    Returns:
    
    The RouteMatcher for the route that can be used to remove the route at a later point.
  - uriTemplate
```
public static Router.UriTemplate uriTemplate(String template)
```
    Creates a Router.UriTemplate from a URI template string that will be used to match and route incoming requests.
    
    Parameters:
    
    template - The URI template.
    
    Returns:
    
    A UriTemplate instance.
  - addRoute
```
public RouteMatcher<Request> addRoute(Version version,
                                      CollectionResourceProvider provider)
```
    Adds a new route to this router for the provided collection resource provider. New routes may be added while this router is processing requests.
    
    Parameters:
    
    version - The resource API version the the request must match.
    
    provider - The collection resource provider to which matching requests will be routed.
    
    Returns:
    
    The RouteMatcher for the route that can be used to remove the route at a later point.
  - addRoute
```
public RouteMatcher<Request> addRoute(Version version,
                                      SingletonResourceProvider provider)
```
    Adds a new route to this router for the provided singleton resource provider. New routes may be added while this router is processing requests.
    
    Parameters:
    
    version - The resource API version the the request must match.
    
    provider - The singleton resource provider to which matching requests will be routed.
    
    Returns:
    
    The RouteMatcher for the route that can be used to remove the route at a later point.
  - addRoute
```
public RouteMatcher<Request> addRoute(Version version,
                                      RequestHandler handler)
```
    Adds a new route to this router for the provided request handler. New routes may be added while this router is processing requests.
    
    Parameters:
    
    version - The resource API version the the request must match.
    
    handler - The request handler to which matching requests will be routed.
    
    Returns:
    
    The RouteMatcher for the route that can be used to remove the route at a later point.
  - handleAction
```
public Promise<ActionResponse,ResourceException> handleAction(Context context,
                                                              ActionRequest request)
```
    Description copied from interface: RequestHandler
    
    Handles performing an action on a resource, and optionally returns an associated result. The execution of an action is allowed to incur side effects.
    Actions are parametric; a set of named parameters is provided as input to the action. The action result is a JSON object structure composed of basic Java types; its overall structure is defined by a specific implementation.
    On completion, the action result (or null) must be used to complete the returned Promise. On failure, the returned Promise must be completed with the exception.
    Action expects failure exceptions as follows: ForbiddenException if access to the resource is forbidden. NotSupportedException if the requested functionality is not implemented/supported BadRequestException if the passed identifier, parameters or filter is invalid NotFoundException if the specified resource could not be found.
    
    Specified by:
    
    handleAction in interface RequestHandler
    
    Parameters:
    
    context - The request server context, such as associated principal.
    
    request - The action request.
    
    Returns:
    
    A Promise containing the result of the operation.
  - handleCreate
```
public Promise<ResourceResponse,ResourceException> handleCreate(Context context,
                                                                CreateRequest request)
```
    Description copied from interface: RequestHandler
    Adds a new JSON resource, returning a Promise that will be completed when the resource has been added.
    Create expects failure exceptions as follows:
    - ForbiddenException if access to the resource is forbidden.
    - NotSupportedException if the requested functionality is not implemented/supported
    - PreconditionFailedException if a resource with the same ID already exists
    - BadRequestException if the passed identifier or value is invalid
    - NotFoundException if the specified id could not be resolved, for example when an intermediate resource in the hierarchy does not exist.
    Specified by:
    
    handleCreate in interface RequestHandler
    
    Parameters:
    
    context - The request server context, such as associated principal.
    
    request - The create request.
    
    Returns:
    
    A Promise containing the result of the operation.
  - handleDelete
```
public Promise<ResourceResponse,ResourceException> handleDelete(Context context,
                                                                DeleteRequest request)
```
    Description copied from interface: RequestHandler
    Deletes a JSON resource, returning a Promise that will be completed when the resource has been deleted.
    Delete expects failure exceptions as follows:
    - ForbiddenException if access to the resource is forbidden
    - NotSupportedException if the requested functionality is not implemented/supported
    - BadRequestException if the passed identifier is invalid
    - NotFoundException if the specified resource could not be found
    - PreconditionRequiredException if version is required, but is null
    - PreconditionFailedException if version did not match the existing resource.
    Specified by:
    
    handleDelete in interface RequestHandler
    
    Parameters:
    
    context - The request server context, such as associated principal.
    
    request - The delete request.
    
    Returns:
    
    A Promise containing the result of the operation.
  - handlePatch
```
public Promise<ResourceResponse,ResourceException> handlePatch(Context context,
                                                               PatchRequest request)
```
    Description copied from interface: RequestHandler
    Updates a JSON resource by applying a set of changes to its existing content, returning a Promise that will be completed when the resource has been updated.
    Patch expects failure exceptions as follows:
    - ForbiddenException if access to the resource is forbidden
    - NotSupportedException if the requested functionality is not implemented/supported
    - PreconditionRequiredException if version is required, but is null
    - PreconditionFailedException if version did not match the existing resource
    - BadRequestException if the passed identifier or filter is invalid
    - NotFoundException if the specified resource could not be found
    - ConflictException if patch could not be applied for the given resource state.
    Specified by:
    
    handlePatch in interface RequestHandler
    
    Parameters:
    
    context - The request server context, such as associated principal.
    
    request - The patch request.
    
    Returns:
    
    A Promise containing the result of the operation.
  - handleQuery
```
public Promise<QueryResponse,ResourceException> handleQuery(Context context,
                                                            QueryRequest request,
                                                            QueryResourceHandler handler)
```
    Description copied from interface: RequestHandler
    Searches for all JSON resources matching a user specified set of criteria, returning a Promise that will be completed when the search has completed.
    Implementations must invoke QueryResourceHandler.handleResource(ResourceResponse) for each resource which matches the query criteria. Once all matching resources have been returned implementations are required to return either a QueryResponse if the query has completed successfully, or ResourceException if the query did not complete successfully (even if some matching resources were returned).
    Query expects failure exceptions as follows:
    - ForbiddenException if access to the resource is forbidden
    - NotSupportedException if the requested functionality is not implemented/supported
    - BadRequestException if the passed identifier, parameters or filter is invalid
    - NotFoundException if the specified resource could not be found
    Specified by:
    
    handleQuery in interface RequestHandler
    
    Parameters:
    
    context - The request server context, such as associated principal.
    
    request - The query request.
    
    handler - The query resource handler to be notified for each matching resource.
    
    Returns:
    
    A Promise containing the result of the operation.
  - handleRead
```
public Promise<ResourceResponse,ResourceException> handleRead(Context context,
                                                              ReadRequest request)
```
    Description copied from interface: RequestHandler
    Reads a JSON resource, returning a Promise that will be completed when the resource has been read.
    Read expects failure exceptions as follows:
    - ForbiddenException if access to the resource is forbidden.
    - NotSupportedException if the requested functionality is not implemented/supported
    - BadRequestException if the passed identifier or filter is invalid
    - NotFoundException if the specified resource could not be found.
    Specified by:
    
    handleRead in interface RequestHandler
    
    Parameters:
    
    context - The request server context, such as associated principal.
    
    request - The read request.
    
    Returns:
    
    A Promise containing the result of the operation.
  - handleUpdate
```
public Promise<ResourceResponse,ResourceException> handleUpdate(Context context,
                                                                UpdateRequest request)
```
    Description copied from interface: RequestHandler
    Updates a JSON resource by replacing its existing content with new content, returning a Promise that will be completed when the resource has been updated.
    Update expects failure the following failure exceptions:
    - ForbiddenException if access to the resource is forbidden
    - NotSupportedException if the requested functionality is not implemented/supported
    - PreconditionRequiredException if version is required, but is null
    - PreconditionFailedException if version did not match the existing resource
    - BadRequestException if the passed identifier or filter is invalid
    - NotFoundException if the specified resource could not be found.
    Specified by:
    
    handleUpdate in interface RequestHandler
    
    Parameters:
    
    context - The request server context, such as associated principal.
    
    request - The update request.
    
    Returns:
    
    A Promise containing the result of the operation.
  - handleApiRequest
```
public ApiDescription handleApiRequest(Context context,
                                       Request 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<ApiDescription,Request>
    
    Overrides:
    
    handleApiRequest in class AbstractRouter<Router,Request,RequestHandler,ApiDescription>
    
    Parameters:
    
    context - The request context.
    
    request - The request.
    
    Returns:
    
    The descriptor.

Class Router

Nested Class Summary

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

Field Summary

Fields inherited from class org.forgerock.services.routing.AbstractRouter

Constructor Summary

Method Summary

Methods inherited from class org.forgerock.services.routing.AbstractRouter

Methods inherited from class java.lang.Object

Constructor Detail

Router

Router

Method Detail

getThis

uriMatcher

addRoute

addRoute

addRoute

uriTemplate

addRoute

addRoute

addRoute

handleAction

handleCreate

handleDelete

handlePatch

handleQuery

handleRead

handleUpdate

handleApiRequest