org.opends.server.api
Class DebugLogPublisher<T extends DebugLogPublisherCfg>

java.lang.Object
  extended by org.opends.server.api.DebugLogPublisher<T>
Type Parameters:
T - The type of debug log publisher configuration handled by this log publisher implementation.
Direct Known Subclasses:
TextDebugLogPublisher

@PublicAPI(stability=VOLATILE,
           mayInstantiate=false,
           mayExtend=true,
           mayInvoke=false)
public abstract class DebugLogPublisher<T extends DebugLogPublisherCfg>
extends java.lang.Object

This class defines the set of methods and structures that must be implemented for a Directory Server debug log publisher.


Constructor Summary
protected DebugLogPublisher()
          Construct a default configuration where the global scope will only log at the ERROR level.
 
Method Summary
 void addTraceSettings(java.lang.String scope, TraceSettings settings)
          Adds a trace settings to the current set for a specified scope.
abstract  void close()
          Close this publisher.
 TraceSettings getClassSettings(java.lang.String className)
          Get the trace settings for a specified class.
abstract  DN getDN()
          Gets the DN of the configuration entry for this debug log publisher.
 java.util.Map<java.lang.String,TraceSettings> getMethodSettings(java.lang.String className)
          Gets the method trace levels for a specified class.
 TraceSettings getTraceSettings(java.lang.String scope)
          Determine whether a trace setting is already defined for a particular scope.
abstract  void initializeDebugLogPublisher(T config)
          Initializes this debug publisher provider based on the information in the provided debug publisher configuration.
 boolean isConfigurationAcceptable(DebugLogPublisherCfg configuration, java.util.List<Message> unacceptableReasons)
          Indicates whether the provided configuration is acceptable for this debug log publisher.
 TraceSettings removeTraceSettings(java.lang.String scope)
          Remove a trace setting by scope.
abstract  void traceCaught(LogLevel level, TraceSettings settings, java.lang.String signature, java.lang.String sourceLocation, java.lang.Throwable ex, java.lang.StackTraceElement[] stackTrace)
          Log a caught exception in a method.
abstract  void traceConstructor(LogLevel level, TraceSettings settings, java.lang.String signature, java.lang.String sourceLocation, java.lang.Object[] args, java.lang.StackTraceElement[] stackTrace)
          Log a constructor entry.
abstract  void traceData(LogLevel level, TraceSettings settings, java.lang.String signature, java.lang.String sourceLocation, byte[] data, java.lang.StackTraceElement[] stackTrace)
          Log raw data in a method.
abstract  void traceJEAccess(LogLevel level, TraceSettings settings, java.lang.String signature, java.lang.String sourceLocation, com.sleepycat.je.OperationStatus status, com.sleepycat.je.Database database, com.sleepycat.je.Transaction txn, com.sleepycat.je.DatabaseEntry key, com.sleepycat.je.DatabaseEntry data, java.lang.StackTraceElement[] stackTrace)
          Log an JE database access in a method.
abstract  void traceMessage(LogLevel level, TraceSettings settings, java.lang.String signature, java.lang.String sourceLocation, java.lang.String msg, java.lang.StackTraceElement[] stackTrace)
          Log an arbitrary event in a method.
abstract  void traceMethodEntry(LogLevel level, TraceSettings settings, java.lang.String signature, java.lang.String sourceLocation, java.lang.Object obj, java.lang.Object[] args, java.lang.StackTraceElement[] stackTrace)
          Log a non-static method entry.
abstract  void traceProtocolElement(LogLevel level, TraceSettings settings, java.lang.String signature, java.lang.String sourceLocation, ProtocolElement element, java.lang.StackTraceElement[] stackTrace)
          Log a protocol element in a method.
abstract  void traceReturn(LogLevel level, TraceSettings settings, java.lang.String signature, java.lang.String sourceLocation, java.lang.Object ret, java.lang.StackTraceElement[] stackTrace)
          Log a method return.
abstract  void traceStaticMethodEntry(LogLevel level, TraceSettings settings, java.lang.String signature, java.lang.String sourceLocation, java.lang.Object[] args, java.lang.StackTraceElement[] stackTrace)
          Log a static method entry.
abstract  void traceThrown(LogLevel level, TraceSettings settings, java.lang.String signature, java.lang.String sourceLocation, java.lang.Throwable ex, java.lang.StackTraceElement[] stackTrace)
          Log a thrown exception in a method.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

DebugLogPublisher

protected DebugLogPublisher()
Construct a default configuration where the global scope will only log at the ERROR level.

Method Detail

initializeDebugLogPublisher

public abstract void initializeDebugLogPublisher(T config)
                                          throws ConfigException,
                                                 InitializationException
Initializes this debug publisher provider based on the information in the provided debug publisher configuration.

Parameters:
config - The debug publisher configuration that contains the information to use to initialize this debug publisher.
Throws:
ConfigException - If an unrecoverable problem arises in the process of performing the initialization as a result of the server configuration.
InitializationException - If a problem occurs during initialization that is not related to the server configuration.

isConfigurationAcceptable

public boolean isConfigurationAcceptable(DebugLogPublisherCfg configuration,
                                         java.util.List<Message> unacceptableReasons)
Indicates whether the provided configuration is acceptable for this debug log publisher. It should be possible to call this method on an uninitialized debug log publisher instance in order to determine whether the debug log publisher would be able to use the provided configuration.

Note that implementations which use a subclass of the provided configuration class will likely need to cast the configuration to the appropriate subclass type.

Parameters:
configuration - The debug log publisher configuration for which to make the determination.
unacceptableReasons - A list that may be used to hold the reasons that the provided configuration is not acceptable.
Returns:
true if the provided configuration is acceptable for this debug log publisher, or false if not.

getMethodSettings

public final java.util.Map<java.lang.String,TraceSettings> getMethodSettings(java.lang.String className)
Gets the method trace levels for a specified class.

Parameters:
className - The fully-qualified name of the class for which to get the trace levels.
Returns:
An unmodifiable map of trace levels keyed by method name, or null if no method-level tracing is configured for the scope.

getClassSettings

public final TraceSettings getClassSettings(java.lang.String className)
Get the trace settings for a specified class.

Parameters:
className - The fully-qualified name of the class for which to get the trace levels.
Returns:
The current trace settings for the class.

addTraceSettings

public final void addTraceSettings(java.lang.String scope,
                                   TraceSettings settings)
Adds a trace settings to the current set for a specified scope. If a scope is not specified, the settings will be set for the global scope. The global scope settings are used when no other scope matches.

Parameters:
scope - The scope for which to set the trace settings. This should be a fully-qualified class name, or null to set the trace settings for the global scope.
settings - The trace settings for the specified scope.

getTraceSettings

public final TraceSettings getTraceSettings(java.lang.String scope)
Determine whether a trace setting is already defined for a particular scope.

Parameters:
scope - The scope for which to make the determination. This should be a fully-qualified class name, or null to make the determination for the global scope.
Returns:
The trace settings for the specified scope, or null if no trace setting is defined for that scope.

removeTraceSettings

public final TraceSettings removeTraceSettings(java.lang.String scope)
Remove a trace setting by scope.

Parameters:
scope - The scope for which to remove the trace setting. This should be a fully-qualified class name, or null to remove the trace setting for the global scope.
Returns:
The trace settings for the specified scope, or null if no trace setting is defined for that scope.

traceConstructor

public abstract void traceConstructor(LogLevel level,
                                      TraceSettings settings,
                                      java.lang.String signature,
                                      java.lang.String sourceLocation,
                                      java.lang.Object[] args,
                                      java.lang.StackTraceElement[] stackTrace)
Log a constructor entry.

Parameters:
level - The log level for the message.
settings - The current trace settings in effect.
signature - The constuctor signature.
sourceLocation - The location of the method in the source.
args - The parameters provided to the constructor.
stackTrace - The stack trace at the time the constructor is executed or null if its not available.

traceMethodEntry

public abstract void traceMethodEntry(LogLevel level,
                                      TraceSettings settings,
                                      java.lang.String signature,
                                      java.lang.String sourceLocation,
                                      java.lang.Object obj,
                                      java.lang.Object[] args,
                                      java.lang.StackTraceElement[] stackTrace)
Log a non-static method entry.

Parameters:
level - The log level for the message.
settings - The current trace settings in effect.
signature - The method signature.
sourceLocation - The location of the method in the source.
obj - The object instance on which the method has been invoked.
args - The parameters provided to the method.
stackTrace - The stack trace at the time the method is executed or null if its not available.

traceStaticMethodEntry

public abstract void traceStaticMethodEntry(LogLevel level,
                                            TraceSettings settings,
                                            java.lang.String signature,
                                            java.lang.String sourceLocation,
                                            java.lang.Object[] args,
                                            java.lang.StackTraceElement[] stackTrace)
Log a static method entry.

Parameters:
level - The log level for the message.
settings - The current trace settings in effect.
signature - The method signature.
sourceLocation - The location of the method in the source.
args - The parameters provided to the method.
stackTrace - The stack trace at the time the method is executed or null if its not available.

traceReturn

public abstract void traceReturn(LogLevel level,
                                 TraceSettings settings,
                                 java.lang.String signature,
                                 java.lang.String sourceLocation,
                                 java.lang.Object ret,
                                 java.lang.StackTraceElement[] stackTrace)
Log a method return.

Parameters:
level - The log level for the message.
settings - The current trace settings in effect.
signature - The method signature.
sourceLocation - The location of the method in the source.
ret - The return value for the method.
stackTrace - The stack trace at the time the method is returned or null if its not available.

traceMessage

public abstract void traceMessage(LogLevel level,
                                  TraceSettings settings,
                                  java.lang.String signature,
                                  java.lang.String sourceLocation,
                                  java.lang.String msg,
                                  java.lang.StackTraceElement[] stackTrace)
Log an arbitrary event in a method.

Parameters:
level - The log level for the message.
settings - The current trace settings in effect.
signature - The method signature.
sourceLocation - The location of the method in the source.
msg - The message to be logged.
stackTrace - The stack trace at the time the message is logged or null if its not available.

traceThrown

public abstract void traceThrown(LogLevel level,
                                 TraceSettings settings,
                                 java.lang.String signature,
                                 java.lang.String sourceLocation,
                                 java.lang.Throwable ex,
                                 java.lang.StackTraceElement[] stackTrace)
Log a thrown exception in a method.

Parameters:
level - The log level for the message.
settings - The current trace settings in effect.
signature - The method signature.
sourceLocation - The location of the method in the source.
ex - The exception that was thrown.
stackTrace - The stack trace at the time the exception is thrown or null if its not available.

traceCaught

public abstract void traceCaught(LogLevel level,
                                 TraceSettings settings,
                                 java.lang.String signature,
                                 java.lang.String sourceLocation,
                                 java.lang.Throwable ex,
                                 java.lang.StackTraceElement[] stackTrace)
Log a caught exception in a method.

Parameters:
level - The log level for the message.
settings - The current trace settings in effect.
signature - The method signature.
sourceLocation - The location of the method in the source.
ex - The exception that was caught.
stackTrace - The stack trace at the time the exception is caught or null if its not available.

traceJEAccess

public abstract void traceJEAccess(LogLevel level,
                                   TraceSettings settings,
                                   java.lang.String signature,
                                   java.lang.String sourceLocation,
                                   com.sleepycat.je.OperationStatus status,
                                   com.sleepycat.je.Database database,
                                   com.sleepycat.je.Transaction txn,
                                   com.sleepycat.je.DatabaseEntry key,
                                   com.sleepycat.je.DatabaseEntry data,
                                   java.lang.StackTraceElement[] stackTrace)
Log an JE database access in a method.

Parameters:
level - The log level for the message.
settings - The current trace settings in effect.
signature - The method signature.
sourceLocation - The location of the method in the source.
status - The status of the JE operation.
database - The database handle.
txn - The transaction handle (may be null).
key - The key to dump.
data - The data to dump.
stackTrace - The stack trace at the time the access occurred or null if its not available.

traceData

public abstract void traceData(LogLevel level,
                               TraceSettings settings,
                               java.lang.String signature,
                               java.lang.String sourceLocation,
                               byte[] data,
                               java.lang.StackTraceElement[] stackTrace)
Log raw data in a method.

Parameters:
level - The log level for the message.
settings - The current trace settings in effect.
signature - The method signature.
sourceLocation - The location of the method in the source.
data - The data to dump.
stackTrace - The stack trace at the time the data is logged or null if its not available.

traceProtocolElement

public abstract void traceProtocolElement(LogLevel level,
                                          TraceSettings settings,
                                          java.lang.String signature,
                                          java.lang.String sourceLocation,
                                          ProtocolElement element,
                                          java.lang.StackTraceElement[] stackTrace)
Log a protocol element in a method.

Parameters:
level - The log level for the message.
settings - The current trace settings in effect.
signature - The method signature.
sourceLocation - The location of the method in the source.
element - The protocol element to dump.
stackTrace - The stack trace at the time the protocol element is logged or null if its not available.

close

public abstract void close()
Close this publisher.


getDN

public abstract DN getDN()
Gets the DN of the configuration entry for this debug log publisher.

Returns:
The configuration entry DN.