AuditServiceProxy (OpenIG doc 6.5.4 Documentation)

java.lang.Object
- org.forgerock.audit.AuditServiceProxy

All Implemented Interfaces:

AuditService, RequestHandler
```
public class AuditServiceProxy
extends Object
implements AuditService
```
AuditService proxy that allows products to implement threadsafe hot-swappable configuration updates.
The proxied AuditService can be swapped by calling setDelegate(AuditService).

Thread-safety is achieved by blocking proxied calls until the old AuditService has flushed all buffers and closed any open file or network connections.

Field Summary

Fields
Modifier and Type	Field and Description
`static String`	`ACTION_PARAM_TARGET_HANDLER` Parameter that may be used when using an action, to provide the name of the handler to use as a target.

Constructor Summary

Constructors
Constructor and Description

AuditServiceProxy(AuditService delegate)
Create a new AuditServiceProxy.

Constructors
Constructor and Description
`AuditServiceProxy(AuditService delegate)` Create a new `AuditServiceProxy`.

Method Summary

All Methods Instance Methods Concrete Methods
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.
`protected void`	`obtainReadLock()` Obtain the read lock or block until it becomes available.
`protected void`	`obtainWriteLock()` Obtain the write lock or block until it becomes available.
`protected void`	`releaseReadLock()` Release the read lock.
`protected void`	`releaseWriteLock()` Release the write lock.
`void`	`setDelegate(AuditService newDelegate)` Sets the AuditService this object proxies.
`void`	`shutdown()` Closes this `AuditService` and all its `AuditEventHandler`s.
`void`	`startup()` Allows this `AuditService` and all its `AuditEventHandler`s to perform any initialization that would be unsafe to do if any other instance of the `AuditService` were still running.

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

- Field Detail
  - ACTION_PARAM_TARGET_HANDLER
```
public static final String ACTION_PARAM_TARGET_HANDLER
```
    Parameter that may be used when using an action, to provide the name of the handler to use as a target.
    
    See Also:
    
    Constant Field Values
- Constructor Detail
  - AuditServiceProxy
```
public AuditServiceProxy(AuditService delegate)
```
    Create a new AuditServiceProxy.
    
    Parameters:
    
    delegate - The AuditService that this object should proxy.
- Method Detail
  - setDelegate
```
public void setDelegate(AuditService newDelegate)
                 throws ServiceUnavailableException
```
    Sets the AuditService this object proxies.
    Thread-safety is achieved by blocking proxied calls until the old AuditService has flushed all buffers and closed any open file or network connections.
    
    Parameters:
    
    newDelegate - A new AuditService instance with updated configuration.
    
    Throws:
    
    ServiceUnavailableException - If the new audit service cannot be started.
  - handleRead
```
public Promise<ResourceResponse,ResourceException> handleRead(Context context,
                                                              ReadRequest request)
```
    Description copied from interface: AuditService
    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 AuditService
    
    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
```
public Promise<ResourceResponse,ResourceException> handleCreate(Context context,
                                                                CreateRequest request)
```
    Description copied from interface: AuditService
    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 AuditService
    
    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
```
public Promise<ResourceResponse,ResourceException> handleUpdate(Context context,
                                                                UpdateRequest request)
```
    Description copied from interface: AuditService
    
    Audit service does not support changing audit entries.
    The returned promise will resolve to a NotSupportedException.
    
    Specified by:
    
    handleUpdate in interface AuditService
    
    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
```
public Promise<ResourceResponse,ResourceException> handleDelete(Context context,
                                                                DeleteRequest request)
```
    Description copied from interface: AuditService
    
    Audit service does not support changing audit entries.
    The returned promise will resolve to a NotSupportedException.
    
    Specified by:
    
    handleDelete in interface AuditService
    
    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: AuditService
    
    Audit service does not support changing audit entries.
    The returned promise will resolve to a NotSupportedException.
    
    Specified by:
    
    handlePatch in interface AuditService
    
    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: AuditService
    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 AuditService
    
    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
```
public Promise<ActionResponse,ResourceException> handleAction(Context context,
                                                              ActionRequest request)
```
    Description copied from interface: AuditService
    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 AuditService
    
    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
```
public AuditServiceConfiguration getConfig()
                                    throws ServiceUnavailableException
```
    Description copied from interface: AuditService
    
    Gets the AuditService configuration.
    
    Specified by:
    
    getConfig in interface AuditService
    
    Returns:
    
    the audit service config
    
    Throws:
    
    ServiceUnavailableException - if the AuditService has been closed.
  - getRegisteredHandler
```
public AuditEventHandler getRegisteredHandler(String handlerName)
                                       throws ServiceUnavailableException
```
    Description copied from interface: AuditService
    
    Returns the registered handler corresponding to provided name.
    
    Specified by:
    
    getRegisteredHandler in interface AuditService
    
    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
```
public Collection<AuditEventHandler> getRegisteredHandlers()
                                                    throws ServiceUnavailableException
```
    Description copied from interface: AuditService
    
    Returns the registered handlers.
    
    Specified by:
    
    getRegisteredHandlers in interface AuditService
    
    Returns:
    
    the handlers
    
    Throws:
    
    ServiceUnavailableException - if the AuditService has been closed.
  - isAuditing
```
public boolean isAuditing(String topic)
                   throws ServiceUnavailableException
```
    Description copied from interface: AuditService
    
    Returns whether or not events of the specified topic will be handled.
    
    Specified by:
    
    isAuditing in interface AuditService
    
    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
```
public Set<String> getKnownTopics()
                           throws ServiceUnavailableException
```
    Description copied from interface: AuditService
    
    Returns the set of event topics (schemas) that the AuditService understands.
    
    Specified by:
    
    getKnownTopics in interface AuditService
    
    Returns:
    
    The set of event topics.
    
    Throws:
    
    ServiceUnavailableException - if the AuditService has been closed.
  - shutdown
```
public void shutdown()
```
    Description copied from interface: AuditService
    
    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.
    
    Specified by:
    
    shutdown in interface AuditService
  - startup
```
public void startup()
             throws ServiceUnavailableException
```
    Description copied from interface: AuditService
    
    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.
    
    Specified by:
    
    startup in interface AuditService
    
    Throws:
    
    ServiceUnavailableException - if the AuditService has been closed.
  - isRunning
```
public boolean isRunning()
```
    Description copied from interface: AuditService
    
    Returns true if this object is running.
    This object will be in a 'running' state if AuditService.startup() completed successfully and AuditService.shutdown() has not yet been called.
    
    Specified by:
    
    isRunning in interface AuditService
    
    Returns:
    
    true if this object is running; false otherwise.
  - obtainReadLock
```
protected final void obtainReadLock()
```
    Obtain the read lock or block until it becomes available.
    
    Throws:
    
    IllegalStateException - If the current thread already holds the write lock.
  - releaseReadLock
```
protected final void releaseReadLock()
```
    Release the read lock.
  - obtainWriteLock
```
protected final void obtainWriteLock()
```
    Obtain the write lock or block until it becomes available.
  - releaseWriteLock
```
protected final void releaseWriteLock()
```
    Release the write lock.

Class AuditServiceProxy

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

ACTION_PARAM_TARGET_HANDLER

Constructor Detail

AuditServiceProxy

Method Detail

setDelegate

handleRead

handleCreate

handleUpdate

handleDelete

handlePatch

handleQuery

handleAction

getConfig

getRegisteredHandler

getRegisteredHandlers

isAuditing

getKnownTopics

shutdown

startup

isRunning

obtainReadLock

releaseReadLock

obtainWriteLock

releaseWriteLock