com.neeve.trace
Class TraceLoggerFactory

java.lang.Object
  com.neeve.trace.TraceLoggerFactory

public final class TraceLoggerFactory
extends Object

Factory class used to manage trace loggers and handlers.

Threading:

This class is safe for concurrent access by multiple threads.

Nested Class Summary

static class	TraceLoggerFactory.ForkHandler Implements a 'fork' trace handler.
static class	TraceLoggerFactory.NullHandler Implements a 'null' handler.
static class	TraceLoggerFactory.StderrHandler Implements the 'stderr' trace handler This handler directs all trace to System.err
static class	TraceLoggerFactory.StdoutHandler Implements a 'stdout' trace handler.

Field Summary

static String

DEFAULT_HANDLER_NAME The name of the default handler.

Method Summary

Handler	createHandler(String handlerName, String descriptorStr) Create/update a handler.
Logger	createLogger(String loggerName, String levelStr, String handlersStr) Create/update a logger.
Handler	getHandler(String handlerName) Get a handler.
static TraceLoggerFactory	getInstance() Return the singleton log factory instance.
Logger	getLogger(String loggerName, boolean create) Get a logger.
void	registerWatcher(Handler handler) Install a trace watcher.
static void	setDefaultHandler(Handler handler) Set the default handler.
static void	setFormatter(Formatter formatter) Set the trace formatter.
void	setHandler(String handlerName, Handler handler) Set a handler.

Methods inherited from class java.lang.Object

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

Field Detail

DEFAULT_HANDLER_NAME

public static final String DEFAULT_HANDLER_NAME

The name of the default handler.

See Also:

Constant Field Values

Method Detail

getInstance

public static TraceLoggerFactory getInstance()

Return the singleton log factory instance.

Returns:

Returns the log factory instance.

Threading:

This method is safe for concurrent access by multiple threads

setDefaultHandler

public static void setDefaultHandler(Handler handler)

Set the default handler.

The handler set using this method is used as the default handler. If not set using this method, then the logger factory instantiates the default handler using the "nv.logger.defaulthandler" application property. If the "nv.logger.defaulthandler" property is not set, then the default handler is created using "stdout://level=finest" logger descriptor.

setFormatter

public static void setFormatter(Formatter formatter)

Set the trace formatter.

Parameters:

formatter - The formatter to use.

This method sets the trace formatter to attach to handlers attached to loggers created using this logger factory. The factory uses the platform's default trace handler - TraceFormatter - in case a user supplied formatter is not supplied using this method.

createHandler

public final Handler createHandler(String handlerName,
                                   String descriptorStr)

Create/update a handler.

Parameters:

handlerName - The name of the handler to create.

descriptorStr - This parameter contains a structured string of the form [handler type]://prop=name&prop=name&...&prop=name that describes what and how to create the handler. The handler type specifies the type of handler to create. The supported handler types are 'stdout', 'stderr', 'memory', 'file' and 'network'. The handler type defines the properties that can be specified in the remaining portion of the descriptor. For example, to specify a file handler that uses 5 log files with a maximum size of 100000 bytes per file with names starting with test.log in append mode, use the following descriptor:

file://filename=test.log&size=10000&count=5

The following are the various properties for the different handler types:

Stdout
No type specific properties

Stderr
No type specific properties

Memory
'target': Specifies the handler to which messages held by the memory handler will be pushed when a message with the level equal or greater than pushLevel level is received by the handler. The value for this property should be the name of the target handler e.g. specify target=default&pushLevel=SEVERE to direct messages to the default handler when a SEVERE message is received. This parameter is mandatory.
'size' Specifies the maximum number of log records to buffer in memory. For example, specify size=100 to hols a maximum of 100 records in memory. This property is optional with default=1000
'pushLevel' See 'target'. This property is optional with default=SEVERE

File
'filename' Specifies the pattern for the file to which the messages will be logged. The file handler logs messages cycling through a set of log files named by suffixing the value of the this property with the log file number i.e. successively older log files are named by adding 0, 1, 2 etc to the base filename specified by this property. This property is optional with default='neeve.log'.
'limit' Specifies the maximum size of a log file. When a log file exceeds this size, message are rolled to a new file. For example, specifying limit=1024 will cause a new log file to be used when the current log file has exceeded 1Kb. This property is optional with default=100Mb.
'count' Specifies the maximum number of log files to cycle through. This property is optional with default=10
'append' Specifies whether the log is opened in append mode or not. This property is optional with default=true.

Network
'host' Specifies the host name to which the hander will establish a TCP connection to send the log messages. This property is optional and default=localhost.
'port' Specifies the TCP port to which the hander will establish a TCP connection to send the log messages. This property is mandatory.

In addition to the above, the following properties apply to all handler types:
'level' Specifies the level to be associated with the handler. Messages with level less than the handler level are suppressed. This property is optional with default=FINEST.

Currently, fork and history handlers cannot be created using this method

This method creates a new handler with the supplied name using the supplied descriptor. Refer to the descriptorStr parameter documentation on how the parameter is used in the creation of the handler. In case the handler with the supplied name already exists, this method will replace the existing handler with the new handler.

Upon class initialization, this class creates a 'default' handler using 'stdout://level=finest' unless the nv.logger.defaulthandler application property is set and contains a valid handler descriptor in which case the value set in the property is used to create the default handler. The default handler is used during the creation of a logger with no specified handlers.

setHandler

public final void setHandler(String handlerName,
                             Handler handler)

Set a handler.

Parameters:

handlerName - The name of the handler to set.

handler - The handler to set.

This method sets/replaces a handler of the specified name.

Threading:

This method is safe for concurrent access by multiple threads

getHandler

public final Handler getHandler(String handlerName)

Get a handler.

Parameters:

handlerName - The name of the handler to get.

This method returns a handler with the specified name. A value of null is returned in case a handler with the specified name could not be found.

Threading:

This method is safe for concurrent access by multiple threads

createLogger

public final Logger createLogger(String loggerName,
                                 String levelStr,
                                 String handlersStr)

Create/update a logger.

Parameters:

loggerName - The name of the logger to create.

levelStr - In order to determine the level to be set for the logger being created, this method first checks if there exists the '.logger.level' property in the application property set. If present and valid, that value is used. If not, the value supplied in this parameter is checked. If non-null and valid, this one is used. Otherwise, finally, the level is set to Level.FINEST

handlersStr - This string (a comma separated set of string names) specifies the names of the handlers to associated with the logger. In case this parameter is null, the method checks if there exists the '.logger.handlers' property in the application property set. If present, that value is selected for use. If not, the value supplied in this parameter is checked. If non-null, it is selected for use. Otherwise, finally, the 'default' handler string is selected for use (see createHandler(java.lang.String, com.neeve.util.UtlPropsDescriptor). Once the appropriate handler string has been selected, the method associates handlers corresponding to the names in this string. Names for which there do not exist any handlers are ignored.

This method creates a new logger with the supplied name using the supplied level and handler names to associate with it. Refer to the levelStr and handlersStr parameter documentation on how those parameters are used in the association of level and handlers with the newly created logger. In case the logger with the supplied name already exists, this method will replace the existing level and handlers with the new set.

Threading:

This method is safe for concurrent access by multiple threads.

getLogger

public final Logger getLogger(String loggerName,
                              boolean create)

Get a logger.

Parameters:

loggerName - The name of the logger to get.

create - Specifies in a new logger should be created in case a logger with the specified name cannot be found. In this case, the new logger is created using createLogger(loggerName, null, null)

This method returns a logger with the specified name. In case the logger is not present and the user requests for creation, a new logger is created using createLogger(loggerName, null, null) and returned to the user.

Threading:

This method is safe for concurrent access by multiple threads

registerWatcher

public final void registerWatcher(Handler handler)

Install a trace watcher.

Parameters:

handler - The watcher handler.

This method enables a user to install a global trace watcher. If installed all trace flowing through the system is published to the trace watcher handler in addition to the regular trace handlers.

Threading:

This method is safe for concurrent access by multiple threads