org.forgerock.audit

Class AuditServiceBuilder

java.lang.Object

org.forgerock.audit.AuditServiceBuilder

public final class AuditServiceBuilder
extends Object

Builder for AuditService.

Method Summary

Modifier and Type	Method and Description
AuditService	build() Creates a new AuditService instance.
static AuditServiceBuilder	newAuditService() Factory method for new instances of this builder.
AuditServiceBuilder	withAuditEventHandler(AuditEventHandler auditEventHandler) Register an AuditEventHandler.
AuditServiceBuilder	withAuditEventHandler(Class<? extends AuditEventHandler> clazz, EventHandlerConfiguration configuration) Register an AuditEventHandler.
AuditServiceBuilder	withAuditEventHandlerFactory(AuditEventHandlerFactory auditEventHandlerFactory) Register factory for creating instances of AuditEventHandler.
AuditServiceBuilder	withConfiguration(AuditServiceConfiguration auditServiceConfiguration) Sets the AuditServiceConfiguration that is to be passed to the AuditService.
AuditServiceBuilder	withDependencyProvider(DependencyProvider dependencyProvider) Register the DependencyProvider, after which, an AuditEventHandler can be registered and receive this provider.
AuditServiceBuilder	withEventTopicsMetaData(EventTopicsMetaData eventTopicsMetaData) Set the topic metadata that should be used by the audit service and the handlers.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

newAuditService

public static AuditServiceBuilder newAuditService()

Factory method for new instances of this builder.

Returns:

A new instance of the AuditServiceBuilder.

withConfiguration

public AuditServiceBuilder withConfiguration(AuditServiceConfiguration auditServiceConfiguration)

Sets the AuditServiceConfiguration that is to be passed to the AuditService.

AuditServiceConfiguration embodies the configuration state that can be set by system administrators.

Parameters:

auditServiceConfiguration - user-facing configuration that is to be applied to the AuditService.

Returns:

this builder for method-chaining.

withEventTopicsMetaData

public AuditServiceBuilder withEventTopicsMetaData(EventTopicsMetaData eventTopicsMetaData)

Set the topic metadata that should be used by the audit service and the handlers.

Parameters:

eventTopicsMetaData - The metadata.

Returns:

This builder.

withDependencyProvider

public AuditServiceBuilder withDependencyProvider(DependencyProvider dependencyProvider)

Register the DependencyProvider, after which, an AuditEventHandler can be registered and receive this provider. The dependency provider allows the handler to obtain resources or objects from the product which integrates the Audit Service.

Parameters:

dependencyProvider - the DependencyProvider to register.

Returns:

this builder for method-chaining.

withAuditEventHandlerFactory

public AuditServiceBuilder withAuditEventHandlerFactory(AuditEventHandlerFactory auditEventHandlerFactory)

Register factory for creating instances of AuditEventHandler.

Parameters:

auditEventHandlerFactory - the AuditEventHandlerFactory to register.

Returns:

this builder for method-chaining.

withAuditEventHandler

public AuditServiceBuilder withAuditEventHandler(Class<? extends AuditEventHandler> clazz,
                                                 EventHandlerConfiguration configuration)
                                          throws AuditException

Register an AuditEventHandler. After that registration, that AuditEventHandler can be referred with the given name. This AuditEventHandler will only be notified about the events specified in the parameter events.

Parameters:

clazz - the AuditEventHandler type to register.

configuration - the handler configuration.

Returns:

this builder for method-chaining.

Throws:

AuditException - if already asked to register a handler with the same name.

withAuditEventHandler

public AuditServiceBuilder withAuditEventHandler(AuditEventHandler auditEventHandler)
                                          throws AuditException

Register an AuditEventHandler.

Parameters:

auditEventHandler - the AuditEventHandler to register.

Returns:

this builder for method-chaining.

Throws:

AuditException - if already asked to register a handler with the same name.

build

public AuditService build()

Creates a new AuditService instance.

Instances receive their configuration when constructed and cannot be reconfigured. Where "hot-swappable" reconfiguration is required, an instance of AuditServiceProxy should be used as a proxy. The old AuditService should fully shutdown before the new instance is started. Care must be taken to ensure that no other threads can interact with this object while AuditService.startup() and AuditService.shutdown() methods are running.

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

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

Calling AuditService.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 AuditService.shutdown() will be ignored. When in the 'SHUTDOWN' state, a call to any method other than AuditService.shutdown() will lead to ServiceUnavailableException.

When instances are no longer needed, AuditService.shutdown() should be called to ensure that any buffered audit events are flushed and that all open file handles or connections are closed.

Returns:

a new AuditService instance.