momelog
Class Logger

java.lang.Object
  extended by momelog.Logger

public class Logger
extends Object

Main class of MoMELog logging framework. It is intended to generate logging events on user request. It provides static factory methods for obtaining it's instances and static methods for general framework configuration.

Loggers are distinguished by categories, that are the case-sensitive identification strings. Category can be obtained by calling getCategory() method. It is a readonly property set when logger is obtained. Logger instance can be obtained by using one of three static factory methods getLogger(String), getLogger(Class) and getLogger(). The first method returns Logger instance with specified category. In the second case category is the name of the given class (like from Class.getName() method). The last convenient getLogger() method returns Logger instance of default category, that is a slash (/). The same Logger instance is returned for the same category (case is significant).

There are two methods intended to generate logging events with specified message and/or error log(String) and log(String, Throwable). First of them logs just the specified message and last - message and error. Any of the parameters can be null, of course.

General framework configuration can be performed by using static methods of Logger class. Instance of LogListener implementation to be used for making logging information accessible to the developer can be set by using setLogListener(momelog.LogListener) static method. Invoking this method with null unsets LogListener. MoMELog is preset with no LogListener implementation. Developers need to set it or no logging events will be generated. Configured LogListener can be obtained by calling getLogListener() static method. Instance of Formatter implementation to be used for converting logging events to strings or any other objects can be set by using setFormatter(momelog.Formatter) static method. This method throws NullPointerException on null parameter. MoMELog is preset with PatternFormatter initialized with default pattern. Configured Formatter can be obtained by calling getFormatter() static method.

To control logging of different loggers MoMELog defines notions of allowed categories, disallowed categories and onlywitherror categories. They are a comma separated lists of patterns. Logger instance can only log, if it's category matches any pattern in allowed list and none in disallowed. If category of the Logger instance matches any of the patterns in onlywitherror list, it is allowed only to log events with errors. If any list is set to an empty string (default), it is not considered.

Pattern can contain any text and only one type of special character - asterisk (*). Asterisk, like in file regular expression, designates any number of any characters. Of course, pattern can contain zero or more asterisks. For example pattern "somepackage.*Screen", specifies categories that start with "somepackage." and ends with "Screen".

Allowed categories, disallowed categories and onlywitherror categories lists can be set by invoking setAllowedCategories(String), setDisallowedCategories(String) and setOnlyWithErrorCategories(String) static methods respectively. Allowed categories, disallowed categories and onlywitherror categories lists can be obtained by calling getAllowedCategories(), getDisallowedCategories() and getOnlyWithErrorCategories() static methods respectively. It is posiible to test logger's allowance by calling method isAllowed(). By using isOnlyWithError() it is possible to test, can logger generate logging events with null error property.

Logging event contains the property of timestamp, that is the long integer indicating time of issuing of this logging event. Actually, it is the number of milliseconds from some base time point till logging event generation. By default, this base time point is set to Logger class loading time. By calling resetBaseTime() static method base time point can be set to now.

Version:
1.0
Author:
Sergio Morozov

Field Summary
static String DEFAULT_CATEGORY
          Default category (/).
 
Method Summary
static String getAllowedCategories()
          Returns comma separated list of patterns, that designate allowed loggers.
 String getCategory()
          Returns category of this logger.
static String getDisallowedCategories()
          Returns comma separated list of patterns, that designate disallowed loggers.
static Formatter getFormatter()
          Returns Formatter, that converts logging events to formatted strings.
static Logger getLogger()
          Returns Logger instance of default category ("/").
static Logger getLogger(Class clazz)
          Returns Logger instance initialized with category of name of given class (as returned from Class.getName()).
static Logger getLogger(String category)
          Returns Logger instance initialized with the given category.
static LogListener getLogListener()
          Returns LogListener, that listens for logging events.
static String getOnlyWithErrorCategories()
          Returns comma separated list of patterns, that designate loggers allowed to log only error events.
 boolean isAllowed()
          Returns allowance of this logger.
 boolean isOnlyWithError()
          Returns false, if this Logger instance can log events with null error, true otherwise.
 void log(String message)
          Logs specified message to MoMELog logging framework.
 void log(String message, Throwable error)
          Logs specified message and error to MoMELog logging framework.
static void resetBaseTime()
          Sets base time point of timestamps of new logging events to now.
static void setAllowedCategories(String categories)
           Sets comma separated list of patterns, that designate allowed loggers.
static void setDisallowedCategories(String categories)
           Sets comma separated list of patterns, that designate disallowed loggers.
static void setFormatter(Formatter formatter)
          Sets Formatter instance to convert logging events to strings.
static void setLogListener(LogListener newListener)
          Sets LogListener instance to listen for and process logging events.
static void setOnlyWithErrorCategories(String categories)
           Sets comma separated list of patterns, that designate loggers allowed to log only error events.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

DEFAULT_CATEGORY

public static final String DEFAULT_CATEGORY
Default category (/).

Since:
1.0
See Also:
Constant Field Values
Method Detail

getLogger

public static Logger getLogger()
Returns Logger instance of default category ("/").

Returns:
Logger instance of DEFAULT_CATEGORY.
Since:
1.0

getLogger

public static Logger getLogger(Class clazz)
Returns Logger instance initialized with category of name of given class (as returned from Class.getName()). If clazz is null, this method returns logger initialized with DEFAULT_CATEGORY.

Parameters:
clazz - Class, which name designates the category of Logger.
Returns:
Logger instance initialized with name of given class or DEFAULT_CATEGORY, if clazz is null.
Since:
1.0

getLogger

public static Logger getLogger(String category)
Returns Logger instance initialized with the given category. If category is null, this method returns logger initialized with DEFAULT_CATEGORY.

Parameters:
category - category of Logger to return.
Returns:
Logger instance of given category or DEFAULT_CATEGORY, if category is null.
Since:
1.0

setAllowedCategories

public static void setAllowedCategories(String categories)

Sets comma separated list of patterns, that designate allowed loggers. Logger can only log it's events, if it's category matches any pattern from this list. If this list is set to an empty string (the default), it is not considered (all loggers are allowed). This method updates allowance of loggers obtained before.

Pattern can contain any text and only one type of special character - asterisk (*). Asterisk, like in file regular expression, designates any number of any characters. Of course, pattern can contain zero or more asterisks. For example pattern "somepackage.*Screen", specifies categories that start with "somepackage." and ends with "Screen". Spaces around patterns and empty patterns are allowed and ignored.

Note: Specifying null as list sets it to an empty string.

Parameters:
categories - comma separated list of patterns.
Since:
1.0

setDisallowedCategories

public static void setDisallowedCategories(String categories)

Sets comma separated list of patterns, that designate disallowed loggers. Logger can only log it's events, if it's category matches no pattern from this list. If this list is set to an empty string (the default), it is not considered (all loggers are allowed). This method updates allowance of loggers obtained before.

Pattern can contain any text and only one type of special character - asterisk (*). Asterisk, like in file regular expression, designates any number of any characters. Of course, pattern can contain zero or more asterisks. For example pattern "somepackage.*Screen", specifies categories that start with "somepackage." and ends with "Screen". Spaces around patterns and empty patterns are allowed and ignored.

Note: Specifying null as list sets it to an empty string.

Parameters:
categories - comma separated list of patterns.
Since:
1.0

setOnlyWithErrorCategories

public static void setOnlyWithErrorCategories(String categories)

Sets comma separated list of patterns, that designate loggers allowed to log only error events. If logger's category matches any pattern from this list, it generates only logging event with not-null error. If this list is set to an empty string (the default), it is not considered (all logging events are allowed). This method updates state of loggers obtained before.

Pattern can contain any text and only one type of special character - asterisk (*). Asterisk, like in file regular expression, designates any number of any characters. Of course, pattern can contain zero or more asterisks. For example pattern "somepackage.*Screen", specifies categories that start with "somepackage." and ends with "Screen". Spaces around patterns and empty patterns are allowed and ignored.

Note: Specifying null as list sets it to an empty string.

Parameters:
categories - comma separated list of patterns.
Since:
1.0

getAllowedCategories

public static String getAllowedCategories()
Returns comma separated list of patterns, that designate allowed loggers. Logger can only log it's events, if it's category matches any pattern from this list. If this list is set to an empty string (the default), it is not considered (all loggers are allowed).

Returns:
comma separated list of patterns.
Since:
1.0

getDisallowedCategories

public static String getDisallowedCategories()
Returns comma separated list of patterns, that designate disallowed loggers. Logger can only log it's events, if it's category matches no pattern from this list. If this list is set to an empty string (the default), it is not considered (all loggers are allowed).

Returns:
comma separated list of patterns.
Since:
1.0

getOnlyWithErrorCategories

public static String getOnlyWithErrorCategories()
Returns comma separated list of patterns, that designate loggers allowed to log only error events. If logger's category matches any pattern from this list, it generates only logging event with not-null error. If this list is set to an empty string (the default), it is not considered (all logging events are allowed).

Returns:
comma separated list of patterns.
Since:
1.0

setLogListener

public static void setLogListener(LogListener newListener)
Sets LogListener instance to listen for and process logging events. Supplying null to this method removes LogListener (or sets it to null). If LogListener is set to null no logging events are generated. After this method returns, all new logging events will be processed by supplied LogListener.

Parameters:
newListener - LogListener to listen for and process logging events.
Since:
1.0

getLogListener

public static LogListener getLogListener()
Returns LogListener, that listens for logging events.

Returns:
LogListener, that listens for logging events.

setFormatter

public static void setFormatter(Formatter formatter)
Sets Formatter instance to convert logging events to strings. MoMELog is preset with PatternFormatter instance initialized with default pattern. After this method returns, all new logging events will be formatted by supplied Formatter.

Parameters:
formatter - Formatter to convert logging events to formatted strings.
Throws:
NullPointerException - if formatter is null.

getFormatter

public static Formatter getFormatter()
Returns Formatter, that converts logging events to formatted strings.

Returns:
Formatter, that converts logging events to formatted strings.

resetBaseTime

public static void resetBaseTime()
Sets base time point of timestamps of new logging events to now. Logging event contains the property of timestamp, that is the long integer indicating time of issuing of this logging event. It is the number of milliseconds from some base time point till logging event generation. By default, this base time point is set to Logger class loading time. After this method returns, timestamps of new logging events will be relative to this method execution time.

Since:
1.0

log

public void log(String message,
                Throwable error)
Logs specified message and error to MoMELog logging framework. This method generates logging event, if logger is allowed (depends on values supplied to setAllowedCategories(String), setDisallowedCategories(String) methods) and, if category matches any pattern from onlywitherror categories list, if error is not null.

Parameters:
message - message to log.
error - Throwable to log.
Since:
1.0

log

public void log(String message)
Logs specified message to MoMELog logging framework. This method only generates logging event, if logger is allowed (depends on values supplied to setAllowedCategories(String), setDisallowedCategories(String) methods) and if category matches no pattern from onlywitherror categories list.

Parameters:
message - message to log.
Since:
1.0

getCategory

public String getCategory()
Returns category of this logger. Category is a readonly case sensitive string property of Logger instance, that uniquely identifies it. It is set when Logger instance is obtained.

Returns:
the category of this logger.
Since:
1.0

isAllowed

public boolean isAllowed()
Returns allowance of this logger. Logger is allowed, if it's category matches any pattern from allowed list and none from disallowed. Value of this property depends on values supplied to setAllowedCategories(String) and setDisallowedCategories(String) methods and can be changed, when new values are supplied to the above methods.

Returns:
true if this logger is allowed, false otherwise.
Since:
1.0

isOnlyWithError

public boolean isOnlyWithError()
Returns false, if this Logger instance can log events with null error, true otherwise. Logger can generate logging events with null error property, if it's category matches no pattern from onlywitherror categories list. Value of this property depends on value supplied to setOnlyWithErrorCategories(String) method and can be changed, when new value is supplied to the above method.

Returns:
false if this logger can log events with null error property, true otherwise.
Since:
1.0