org.forgerock.audit

Interface AuditService

All Superinterfaces:

RequestHandler

All Known Implementing Classes:

AuditServiceProxy

public interface AuditService
extends RequestHandler

CREST RequestHandler responsible for storing and retrieving audit events.

After construction, the AuditService will be in the 'STARTING' state until startup() is called. When in the 'STARTING' state, a call to any method other than startup() will lead to ServiceUnavailableException.

After startup() is called, assuming startup succeeds, the AuditService will then be in the 'RUNNING' state and further calls to startup() will be ignored.

Calling shutdown() will put the AuditService into the 'SHUTDOWN' state; once shutdown, the AuditService will remain in this state and cannot be restarted. Further calls to shutdown() will be ignored. When in the 'SHUTDOWN' state, a call to any method other than shutdown() will lead to ServiceUnavailableException.

Method Summary

Modifier and Type	Method and Description
AuditServiceConfiguration	getConfig() Gets the AuditService configuration.
Set<String>	getKnownTopics() Returns the set of event topics (schemas) that the AuditService understands.
AuditEventHandler	getRegisteredHandler(String handlerName) Returns the registered handler corresponding to provided name.
Collection<AuditEventHandler>	getRegisteredHandlers() Returns the registered handlers.
Promise<ActionResponse,ResourceException>	handleAction(Context context, ActionRequest request) Audit service may support actions on the service itself or on handlers.
Promise<ResourceResponse,ResourceException>	handleCreate(Context context, CreateRequest request) Propagates the audit event to the AuditEventHandler objects that have been registered for the audit event topic.
Promise<ResourceResponse,ResourceException>	handleDelete(Context context, DeleteRequest request) Audit service does not support changing audit entries.
Promise<ResourceResponse,ResourceException>	handlePatch(Context context, PatchRequest request) Audit service does not support changing audit entries.
Promise<QueryResponse,ResourceException>	handleQuery(Context context, QueryRequest request, QueryResourceHandler handler) Performs the query on the specified object and returns the associated results.
Promise<ResourceResponse,ResourceException>	handleRead(Context context, ReadRequest request) Gets an object from the audit logs by identifier.
Promise<ResourceResponse,ResourceException>	handleUpdate(Context context, UpdateRequest request) Audit service does not support changing audit entries.
boolean	isAuditing(String topic) Returns whether or not events of the specified topic will be handled.
boolean	isRunning() Returns true if this object is running.
void	shutdown() Closes this AuditService and all its AuditEventHandlers.
void	startup() Allows this AuditService and all its AuditEventHandlers to perform any initialization that would be unsafe to do if any other instance of the AuditService were still running.

Method Detail

handleRead

Promise<ResourceResponse,ResourceException> handleRead(Context context,
                                                       ReadRequest request)

Gets an object from the audit logs by identifier. The returned object is not validated against the current schema and may need processing to conform to an updated schema.

The object will contain metadata properties, including object identifier _id, and object version _rev to enable optimistic concurrency

If this AuditService has been closed, the returned promise will resolve to a ServiceUnavailableException.

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.

handleCreate

Promise<ResourceResponse,ResourceException> handleCreate(Context context,
                                                         CreateRequest request)

Propagates the audit event to the AuditEventHandler objects that have been registered for the audit event topic.

This method sets the _id property to the assigned identifier for the object, and the _rev property to the revised object version (For optimistic concurrency).

If this AuditService has been closed, the returned promise will resolve to a ServiceUnavailableException.

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.

handleUpdate

Promise<ResourceResponse,ResourceException> handleUpdate(Context context,
                                                         UpdateRequest request)

Audit service does not support changing audit entries.

The returned promise will resolve to a NotSupportedException.

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.

handleDelete

Promise<ResourceResponse,ResourceException> handleDelete(Context context,
                                                         DeleteRequest request)

Audit service does not support changing audit entries.

The returned promise will resolve to a NotSupportedException.

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

Promise<ResourceResponse,ResourceException> handlePatch(Context context,
                                                        PatchRequest request)

Audit service does not support changing audit entries.

The returned promise will resolve to a NotSupportedException.

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

Promise<QueryResponse,ResourceException> handleQuery(Context context,
                                                     QueryRequest request,
                                                     QueryResourceHandler handler)

Performs the query on the specified object and returns the associated results.

Queries are parametric; a set of named parameters is provided as the query criteria. The query result is a JSON object structure composed of basic Java types.

The returned map is structured as follow:

• The top level map contains meta-data about the query, plus an entry with the actual result records.
• The QueryConstants defines the map keys, including the result records (QUERY_RESULT)

If this AuditService has been closed, the returned promise will resolve to a ServiceUnavailableException.

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.

handleAction

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

Audit service may support actions on the service itself or on handlers.

One of the following paths format is expected:

 [path-to-audit-service]?_action=XXX : call a global action on audit service
 [path-to-audit-service/[topic]?_action=XXX : call an action on audit service and a single topic
 [path-to-audit-service]?_action=XXX&handler=HHH : call on action on a specific handler
 [path-to-audit-service/[topic]?_action=XXX&handler=HHH : call on action on a specific handler and topic
 

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.

getConfig

AuditServiceConfiguration getConfig()
                             throws ServiceUnavailableException

Gets the AuditService configuration.

Returns:

the audit service config

Throws:

ServiceUnavailableException - if the AuditService has been closed.

getRegisteredHandler

AuditEventHandler getRegisteredHandler(String handlerName)
                                throws ServiceUnavailableException

Returns the registered handler corresponding to provided name.

Parameters:

handlerName - Name of the registered handler to retrieve.

Returns:

the handler, or null if no handler with the provided name was registered to the service.

Throws:

ServiceUnavailableException - if the AuditService has been closed.

getRegisteredHandlers

Collection<AuditEventHandler> getRegisteredHandlers()
                                             throws ServiceUnavailableException

Returns the registered handlers.

Returns:

the handlers

Throws:

ServiceUnavailableException - if the AuditService has been closed.

isAuditing

boolean isAuditing(String topic)
            throws ServiceUnavailableException

Returns whether or not events of the specified topic will be handled.

Parameters:

topic - Identifies a category of events to which handlers may or may not be registered.

Returns:

whether handling of the specified topic is enabled.

Throws:

ServiceUnavailableException - if the AuditService has been closed.

getKnownTopics

Set<String> getKnownTopics()
                    throws ServiceUnavailableException

Returns the set of event topics (schemas) that the AuditService understands.

Returns:

The set of event topics.

Throws:

ServiceUnavailableException - if the AuditService has been closed.

startup

void startup()
      throws ServiceUnavailableException

Allows this AuditService and all its AuditEventHandlers to perform any initialization that would be unsafe to do if any other instance of the AuditService were still running.

Throws:

ServiceUnavailableException - if the AuditService has been closed.

shutdown

void shutdown()

Closes this AuditService and all its AuditEventHandlers.

This ensures that any buffered are flushed and all file handles / network connections are closed.

Once closed, any further calls to this AuditService will throw, or return a promise that will resolve to, ServiceUnavailableException.

isRunning

boolean isRunning()

Returns true if this object is running.

This object will be in a 'running' state if startup() completed successfully and shutdown() has not yet been called.

Returns:

true if this object is running; false otherwise.