com.metamatrix.platform.security.audit
Class AuditManager

java.lang.Object
  com.metamatrix.platform.security.audit.AuditManager

public final class AuditManager
extends java.lang.Object

This class represents the interface to a single auditing framework that is easily accessible by any component. Using the AuditManager, a component can quickly submit a log message, and can rely upon the AuditManager to determine (a) whether that message is to be recorded or discarded; and (b) where to send any recorded messages. Thus, the component's code that submits messages does not have to be modified to alter the logging behavior of the application.

The AuditManager has a number of features that makes it an efficient and configurable framework. First, the methods in the AuditManager that submit messages are asynchronous to minimize the amount of time a client component waits for the AuditManager. Within these asynchronous methods, the AuditManager simply checks the current auditing level and, if the message level is being recorded, places the submitted message in a queue and returns; one or more workers in separate threads pull sumbitted messages out of the queue and process them. During processing, the contexts of each message is examined; any message that is not to be recorded is simply discarded, while those that are to be recorded are sent to each of the destinations.

Secondly, the AuditManager's behavior can be controlled both at VM start time (through current Server configuration properties) and during execution (through method invocation). The destinations of the AuditManager must be configured at the start time of the VM, (i.e., through the current configuration properties) but the control parameters (i.e., the auditing level and the contexts, see below) are initially defined using the current configuration properties at start time and optionally during normal execution via method invocations.

By default, all context(s) are logged by the AuditManager. The messages that the AuditManager actually records and sends to the destinations can be controlled using two different and orthogonal parameters. The first is a message level that filters messages based upon detail, and the second is a message context that filters messages based upon origin. The AuditManager tracks only those context(s) that should NOT be logged. Only if a message (which also is defined with these two parameters) passes both filters will it be sent to the destinations.

Each message is submitted with one of the following levels (determined by the particular method used to submit the message), sorted from the least detailed to the greatest:

None: No audit messages are recorded.

Full: All audit messages are recorded.

The context for a message is any application-specified String. Again, only those message contexts that match those in the AuditManager's configuration will be sent to the destinations.

Field Summary

protected static java.lang.String	DEFAULT_AUDIT_MAX_THREADS
protected static java.lang.String	DEFAULT_AUDIT_THREAD_TTL
static java.lang.String	SYSTEM_AUDIT_CONSOLE_PROPERTY_NAME The name of the configuration property that contains 'true' if the log messages are to be sent to System.out, or 'false' otherwise.
static java.lang.String	SYSTEM_AUDIT_LEVEL_PROPERTY_NAME The name of the configuration property that contains the message level for the AuditManager.

Method Summary

AuditConfiguration	getAuditConfiguration() Utility method to obtain the current log configuration for the AuditManager.
static AuditManager	getInstance()
boolean	isMessageToBeRecorded(AuditMessage message) Utility method to identify whether a log message will be recorded in the AuditManager's destinations.
boolean	isMessageToBeRecorded(java.lang.String context) Utility method to identify whether a audit message with the specified context will be recorded in the AuditManager's destinations.
void	record(java.lang.String context, java.lang.String activity, java.lang.String principal, java.util.Collection permissions) Send a critical message to the log.
void	record(java.lang.String context, java.lang.String activity, java.lang.String principal, java.lang.Object[] resources) Send a critical message to the log.
void	record(java.lang.String context, java.lang.String activity, java.lang.String principal, java.lang.String resource) Send a critical message to the log.
void	setAuditConfiguration(AuditConfiguration config)
void	stop() Utility method to stop (permanently or temporarily) the audit manager for this VM.

Methods inherited from class java.lang.Object

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

Field Detail

SYSTEM_AUDIT_LEVEL_PROPERTY_NAME

public static final java.lang.String SYSTEM_AUDIT_LEVEL_PROPERTY_NAME

The name of the configuration property that contains the message level for the AuditManager. This is an optional property that defaults to '0'.

See Also:

Constant Field Values

SYSTEM_AUDIT_CONSOLE_PROPERTY_NAME

public static final java.lang.String SYSTEM_AUDIT_CONSOLE_PROPERTY_NAME

The name of the configuration property that contains 'true' if the log messages are to be sent to System.out, or 'false' otherwise. This is an optional property that defaults to 'true'. Note, however, that if the message level for the logger is specified to be something other than NONE but no file destination is specified, the value for this propery is always assumed to be 'true'.

See Also:

Constant Field Values

DEFAULT_AUDIT_MAX_THREADS

protected static final java.lang.String DEFAULT_AUDIT_MAX_THREADS

See Also:

Constant Field Values

DEFAULT_AUDIT_THREAD_TTL

protected static final java.lang.String DEFAULT_AUDIT_THREAD_TTL

See Also:

Constant Field Values

Method Detail

getInstance

public static AuditManager getInstance()

record

public void record(java.lang.String context,
                   java.lang.String activity,
                   java.lang.String principal,
                   java.util.Collection permissions)

Send a critical message to the log. This level of message is generally used to record an event or error that must be recorded (if any logging is used). If it is used to record an error, it generally means that the system encountered a critical error which affects the integrity, accuracy, reliability and/or capability of the system.

Only if the log manager is configured to send such messages to the destination will the message be recorded.

Parameters:

context - the context for this log message (for example, the component that is generating this message).

principal - the principal attempting access to the given resources.

permissions - A collection of AuthorizationPermissions that contain resources the given principal wishes to access.

record

public void record(java.lang.String context,
                   java.lang.String activity,
                   java.lang.String principal,
                   java.lang.Object[] resources)

Send a critical message to the log. This level of message is generally used to record an event or error that must be recorded (if any logging is used). If it is used to record an error, it generally means that the system encountered a critical error which affects the integrity, accuracy, reliability and/or capability of the system.

Only if the log manager is configured to send such messages to the destination will the message be recorded.

Parameters:

context - the context for this log message (for example, the component that is generating this message).

activity - the activity the given principal is attempting to perform on the given resources.

principal - the principal attempting access to the given resources.

resources - the resources that the given proncipal is attempting to access.

record

public void record(java.lang.String context,
                   java.lang.String activity,
                   java.lang.String principal,
                   java.lang.String resource)

Send a critical message to the log. This level of message is generally used to record an event or error that must be recorded (if any logging is used). If it is used to record an error, it generally means that the system encountered a critical error which affects the integrity, accuracy, reliability and/or capability of the system.

Only if the log manager is configured to send such messages to the destination will the message be recorded.

Parameters:

context - the context for this log message (for example, the component that is generating this message).

activity - the activity the given principal is attempting to perform on the given resources.

principal - the principal attempting access to the given resources.

resource - the resource that the given proncipal is attempting to access.

stop

public void stop()

Utility method to stop (permanently or temporarily) the audit manager for this VM. This method should be called when messages to the AuditManager are to be prevented, but to wait until all messages already in the AuditManager are processed. Note that this method does block until all messages are processed and until all destinations are closed.

This method is designed to be called by an application that wishes to exit gracefully yet have all messages sent to the audit destinations.

getAuditConfiguration

public AuditConfiguration getAuditConfiguration()

Utility method to obtain the current log configuration for the AuditManager.

Returns:

the current log configuration

setAuditConfiguration

public void setAuditConfiguration(AuditConfiguration config)

isMessageToBeRecorded

public boolean isMessageToBeRecorded(java.lang.String context)

Utility method to identify whether a audit message with the specified context will be recorded in the AuditManager's destinations.

Parameters:

context - the context of the message

Returns:

true if the message would be recorded if sent to the AuditManager, or false if it would be discarded by the AuditManager.

isMessageToBeRecorded

public boolean isMessageToBeRecorded(AuditMessage message)

Utility method to identify whether a log message will be recorded in the AuditManager's destinations.

Parameters:

message - the message

Returns:

true if the message would be recorded if sent to the AuditManager, or false if it would be discarded by the AuditManager.