Package org.forgerock.audit

Class 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 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:

        • CreateNotSupportedException if create is not implemented or supported by the RequestHandler.
        • 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.

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

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

      • 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

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