org.forgerock.json.resource

Interface RequestHandler

All Known Implementing Classes:

AbstractRequestHandler, AnonymousProcessService, DescribedSyncRequestHandlerAdapter, FilterChain, Router

public interface RequestHandler

Represents the contract with a set of resources.

The structure and depth of the (potentially nested) resource set it deals with is up to the implementation. It can choose to just deal with one level, and hand off to another resource implementation, or it can choose to handle multiple levels.

As an example, taking an id of level1/level2/leaf, and assuming that the resource implementation registers to handle level1 with the router; the implementation could choose to hand off processing to other implementations for level2 (or leaf) or it could handle all operations down to leaf.

Supports either synchronous or asynchronous internal processing, i.e. it does not have to block the request thread until a response becomes available.

For synchronous internal processing, immediately return a completed Promise, e.g.

 return Promises.newResultPromise(result);
 

NOTE: field filtering alters the structure of a JSON resource and MUST only be performed once while processing a request. It is therefore the responsibility of front-end implementations (e.g. HTTP listeners, Servlets, etc) to perform field filtering. Request handler and resource provider implementations SHOULD NOT filter fields, but MAY choose to optimise their processing in order to return a resource containing only the fields targeted by the field filters.

Method Summary

Modifier and Type	Method and Description
default Promise<ActionResponse,ResourceException>	handleAction(Context context, ActionRequest request) Handles performing an action on a resource, and optionally returns an associated result.
default 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.
default 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.
default 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.
default 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.
default 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.
default 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.

Method Detail

handleAction

default Promise<ActionResponse,ResourceException> handleAction(Context context,
                                                               ActionRequest request)

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.

Parameters:

context - The request server context, such as associated principal.

request - The action request.

Returns:

A Promise containing the result of the operation.

handleCreate

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

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.

Parameters:

context - The request server context, such as associated principal.

request - The create request.

Returns:

A Promise containing the result of the operation.

handleDelete

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

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.

Parameters:

context - The request server context, such as associated principal.

request - The delete request.

Returns:

A Promise containing the result of the operation.

handlePatch

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

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.

Parameters:

context - The request server context, such as associated principal.

request - The patch request.

Returns:

A Promise containing the result of the operation.

handleQuery

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

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

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

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

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.

Parameters:

context - The request server context, such as associated principal.

request - The read request.

Returns:

A Promise containing the result of the operation.

handleUpdate

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

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.

Parameters:

context - The request server context, such as associated principal.

request - The update request.

Returns:

A Promise containing the result of the operation.