Log4j 0.9.1

org.log4j
Class Category

java.lang.Object
  |
  +--org.log4j.Category
All Implemented Interfaces:
AppenderAttachable
Direct Known Subclasses:
MyCategory, RootCategory, XCategory

public class Category
extends Object
implements AppenderAttachable

This is the central class in the log4j package. One of the distintive features of log4j are hierarchal categories and their evaluation.

See the user manual for an introduction on this class.

Since:
version 0.6.0
Author:
Ceki Gülcü

Field Summary
protected  boolean additive
          Additivity is set to true by default, i.e.
static String DEFAULT_INIT_OVERRIDE_KEY
          Setting the system property log4j.defaultInitOverride to "true" or any other value than "false" will skip default configuration from the log4j.properties file.
static String DEFAULT_PROPERTIES_FILE
          At class initialization, the log4j.properties file is searched from the search path used to load classes.
protected static int disable
           
protected static String instanceFQN
           
protected  String name
          The name of this category.
protected  Category parent
          The parent of this category.
protected  Priority priority
          The assigned priority of this category.
protected  ResourceBundle resourceBundle
           
 
Constructor Summary
protected Category(String name)
          This constructor created a new Category instance and sets its name.
 
Method Summary
 void addAppender(Appender newAppender)
          Add newAppender to the list of appenders of this Category instance.
 void assert(boolean assertion, String msg)
          If assertion parameter is false, then logs msg as an error statement.
 void callAppenders(LoggingEvent event)
          Call the appenders in the hierrachy starting at this.
 void debug(Object message)
          Log an object with debug priority.
 void debug(String message)
          Log a message with debug priority.
 void debug(String message, Throwable t)
          Log a message with the debug priority.
 void error(Object message)
          Log an object with error priority.
 void error(String message)
          Log a message with error priority.
 void error(String message, Throwable t)
          Log a message with the error priority.
static Category exists(String name)
          If the named category exists (in the default hierarchy) then it returns a reference to the category, otherwise it returns null.
 boolean getAdditivity()
          Get the additivity flag for this Category instance.
 Enumeration getAllAppenders()
          Get the appenders contained in this category as an Enumeration.
 Appender getAppender(String name)
          Look for the appender named as name.
 Priority getChainedPriority()
          Starting from this category, search the category hierarchy for a non-null priority and return it.
static Enumeration getCurrentCategories()
          Returns all the currently defined categories in the default hierarchy as an Enumeration.
static Category getInstance(String name)
          Instantiate a category with name name.
static Category getInstance(String name, CategoryFactory factory)
          Like getInstance(String) except that the type of category instantiated depends on the type returned by the CategoryFactory.makeNewCategoryInstance(java.lang.String) method of the factory parameter.
 String getName()
          Return the category name.
 Priority getPriority()
          Returns the assigned Priority, if any, for this Category.
 ResourceBundle getResourceBundle()
          Return the ResourceBundle for this category.
protected  String getResourceBundleString(String key)
           
static Category getRoot()
          Return the root of the default category hierrachy.
static Priority getRootPriority()
          Deprecated. Use getRoot().getPriority() instead.
 void info(Object message)
          Log an object with INFO priority.
 void info(String message)
          Log a message with info priority.
 void info(String message, Throwable t)
          Log a message with the info priority.
 boolean isDebugEnabled()
          Check whether this category is enabled for the debug priority.
 boolean isEnabledFor(Priority priority)
          Check whether this category is enabled for a given Priority passed as parameter.
 boolean isInfoEnabled()
          Check whether this category is enabled for the debug priority.
 void l7dlog(Priority priority, String key, Object[] params, Throwable t)
          Log a localized and parameterized message.
 void l7dlog(Priority priority, String key, Throwable t)
          Log a localized message.
 void log(Priority priority, String message)
          Use this form for priorities which are not directly supported, namely Priority.NOTICE, Priority.ALERT, Priority.EMERG and Priority.CRIT.
 void log(Priority priority, String message, Throwable t)
          Use this form for priorities which are not directly supported, namely Priority.NOTICE, Priority.ALERT, Priority.EMERG and Priority.CRIT.
 void log(String callerFQN, Priority priority, String message, Throwable t)
          This method is intended to be invoked by wrapper classes.
 void removeAllAppenders()
          Remove all previously added appenders from this Category instance.
 void removeAppender(Appender appender)
          Remove the appender passed as parameter form the list of appenders.
 void removeAppender(String name)
          Remove the appender with the name passed as parameter form the list of appenders.
 void setAdditivity(boolean additive)
          Set the additivity flag for this Category instance.
 void setPriority(Priority priority)
          Set the priority of this Category.
 void setResourceBundle(ResourceBundle bundle)
          Set the resource bundle to be used with localized logging methods l7dlog(Priority,String,Throwable) and l7dlog(Priority,String,Object[],Throwable).
static void setRootPriority(Priority priority)
          Set the priority of the root category.
 void warn(Object message)
          Log an object with warn priority.
 void warn(String message)
          Log a message with warn priority.
 void warn(String message, Throwable t)
          Log a message with the warn priority.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

instanceFQN

protected static String instanceFQN

disable

protected static int disable

resourceBundle

protected ResourceBundle resourceBundle

DEFAULT_PROPERTIES_FILE

public static final String DEFAULT_PROPERTIES_FILE
At class initialization, the log4j.properties file is searched from the search path used to load classes. If the file can be found, then it is fed to the PropertyConfigurator. The DEFAULT_PROPERTIES_FILE string constant holds the value log4j.properties.
Since:
0.8.5

DEFAULT_INIT_OVERRIDE_KEY

public static final String DEFAULT_INIT_OVERRIDE_KEY
Setting the system property log4j.defaultInitOverride to "true" or any other value than "false" will skip default configuration from the log4j.properties file. The current value of the DEFAULT_INIT_OVERRIDE_KEY string constant is log4j.defaultInitOverride.

Note that property keys are case sensitive.

Since:
0.8.5

name

protected String name
The name of this category.

priority

protected Priority priority
The assigned priority of this category. Note that the value of this variable may be null.

parent

protected Category parent
The parent of this category. All categories have al least one ancestor which is the root category.

additive

protected boolean additive
Additivity is set to true by default, i.e. a child inherits its ancestor's appenders by default.
Constructor Detail

Category

protected Category(String name)
This constructor created a new Category instance and sets its name.

It is intended to be used by sub-classes only.

Parameters:
name - The name of the category.
Method Detail

addAppender

public void addAppender(Appender newAppender)
Add newAppender to the list of appenders of this Category instance.

If newAppender is already in the list of appenders, then it won't be added again.

Specified by:
addAppender in interface AppenderAttachable

assert

public void assert(boolean assertion,
                   String msg)
If assertion parameter is false, then logs msg as an error statement.
Parameters:
assertion -  
msg - The message to print if assertion is false.
Since:
0.8.1

callAppenders

public void callAppenders(LoggingEvent event)
Call the appenders in the hierrachy starting at this. If no appenders could be found, emit a warning.

This method always calls all the appenders inherited form the hierarchy circumventing any evaluation of whether to log or not to log the particular log request.

Parameters:
LoggingEvent - the event to log.

debug

public void debug(Object message)
Log an object with debug priority. This method converts the (Object) passed as parameter to String using String.valueOf(Object) before logging it exactly in the same way as debug(String).

WARNING Note that passing a Throwable to this method will print the name of the Throwable but no stack trace. To print a stack trace use debug(String, Throwable) form instead.

Parameters:
message - object to convert to String before writing into the log file
Since:
version 0.8.0

debug

public void debug(String message)
Log a message with debug priority.
Parameters:
message - string to write in the log file
Since:
version 0.8.0

debug

public void debug(String message,
                  Throwable t)
Log a message with the debug priority.
Parameters:
message - string to append
exception - the exception to log, including a stack trace

error

public void error(Object message)
Log an object with error priority. This method converts the (Object) passed as parameter to String using String.valueOf(Object) before logging it exactly in the same way as error(String).

WARNING Note that passing a Throwable to this method will print the name of the Throwable but no stack trace. To print a stack trace use the error(String, Throwable) form instead.

Parameters:
message - object to convert to String before writing into the log file
Since:
version 0.8.0

error

public void error(String message)
Log a message with error priority.
Parameters:
message - string to write in the log file
Since:
version 0.8.0

error

public void error(String message,
                  Throwable t)
Log a message with the error priority.
Parameters:
message - string to append
exception - the exception to log, including a stack trace

exists

public static Category exists(String name)
If the named category exists (in the default hierarchy) then it returns a reference to the category, otherwise it returns null.

Contributed by Ciaran Treanor - ciaran@xelector.com


getAdditivity

public boolean getAdditivity()
Get the additivity flag for this Category instance.
Since:
0.9.0

getAllAppenders

public Enumeration getAllAppenders()
Get the appenders contained in this category as an Enumeration. If there are no appenders in this category null is returned.
Specified by:
getAllAppenders in interface AppenderAttachable
Returns:
Enumeration An enumeration of the appenders in this category.

getAppender

public Appender getAppender(String name)
Look for the appender named as name.

Return the appender with that name if in the list. Return null otherwise.

Specified by:
getAppender in interface AppenderAttachable

getChainedPriority

public Priority getChainedPriority()
Starting from this category, search the category hierarchy for a non-null priority and return it. Otherwise, return the priority of the root category.

The Category class is designed so that this method executes as quickly as possible.


getCurrentCategories

public static Enumeration getCurrentCategories()
Returns all the currently defined categories in the default hierarchy as an Enumeration.

The root category is not included in the returned Enumeration.

Since:
version 0.6.1

getInstance

public static Category getInstance(String name)
Instantiate a category with name name. This method does not set priority of the category which is by default null.
Parameters:
name - The name of the category to retrieve.

getInstance

public static Category getInstance(String name,
                                   CategoryFactory factory)
Like getInstance(String) except that the type of category instantiated depends on the type returned by the CategoryFactory.makeNewCategoryInstance(java.lang.String) method of the factory parameter.

This method is intended to be used by sub-classes.

Parameters:
name - The name of the category to retrieve.
factory - A CategoryFactory implementation that will actually create a new Instance.
Since:
0.8.5

getName

public final String getName()
Return the category name.

getPriority

public final Priority getPriority()
Returns the assigned Priority, if any, for this Category.
Returns:
Priority - the assigned Priority, can be null.

getRoot

public static final Category getRoot()
Return the root of the default category hierrachy.

The root category is always instantiated and available. It's name is "root".

Nevertheless, calling Category.getInstance("root") does not retrieve the root category but a category just under root named "root".


getRootPriority

public static Priority getRootPriority()
Deprecated. Use getRoot().getPriority() instead.

Get the priority of the root category.
Since:
version 0.6.1

getResourceBundle

public ResourceBundle getResourceBundle()
Return the ResourceBundle for this category.

This method walks the hierarchy to find the appropriate resource bundle.

In case there is no bundle in the hierarchy then null is returned.

Since:
0.9.0

getResourceBundleString

protected String getResourceBundleString(String key)

info

public void info(Object message)
Log an object with INFO priority. This method converts the (Object) passed as parameter to String using String.valueOf(Object) before logging it exactly in the same way as info(String).

WARNING Note that passing a Throwable to this method will print the name of the Throwable but no stack trace. To print a stack trace use info(String, Throwable) form instead.

Parameters:
message - object to convert to String before writing into the log file
Since:
version 0.8.0

info

public void info(String message)
Log a message with info priority.
Parameters:
message - string to write in the log file
Since:
version 0.8.0

info

public void info(String message,
                 Throwable t)
Log a message with the info priority.
Parameters:
message - string to append
exception - the exception to log, including a stack trace

isDebugEnabled

public boolean isDebugEnabled()
Check whether this category is enabled for the debug priority.

This function is intended to lessen the computational cost of (not) logging debug statements.

For some cat Category object, when you write,

cat.debug("This is entry number: " + i );

You incur the cost constructing the message, concatenating in this case, regardless of whether the message will be logged or not.

If you are worried about speed, then you can write

if(cat.isDebugEnabled("some category") {
cat.debug("This is entry number: " + i );
}

This way you will not incur the cost of parameter construction if debugging is disabled for cat. On the other hand, if the cat is debug enabled, you will incur the cost of evaluating whether the category is debug enabled twice. Once in isDebugEnabled and once in the debug. This is an insignificant overhead since evaluating a category takes about 1% of the time it takes to actually log.

Returns:
boolean - true if this category is debug enabled, false otherwise.

isEnabledFor

public boolean isEnabledFor(Priority priority)
Check whether this category is enabled for a given Priority passed as parameter. See also isDebugEnabled().
Returns:
boolean True if this category is enabled for priority.

isInfoEnabled

public boolean isInfoEnabled()
Check whether this category is enabled for the debug priority. See also isDebugEnabled().
Returns:
boolean - true if this category is enabled for priority info, false otherwise.

l7dlog

public void l7dlog(Priority priority,
                   String key,
                   Throwable t)
Log a localized message. The user supplied parameter key is replaced by its localized version from the resource bundle.
Since:
0.8.4
See Also:
setResourceBundle(java.util.ResourceBundle)

l7dlog

public void l7dlog(Priority priority,
                   String key,
                   Object[] params,
                   Throwable t)
Log a localized and parameterized message. First, the user supplied key is searched in the resource bundle. Next, the resulting pattern is formatted using MessageFormat.format(String,Object[]) method with the user supplied object array params.
Since:
0.8.4

log

public void log(Priority priority,
                String message,
                Throwable t)
Use this form for priorities which are not directly supported, namely Priority.NOTICE, Priority.ALERT, Priority.EMERG and Priority.CRIT. This method is requried for UNIX syslog compatibility and also for internationalized logging methods.
Since:
version 0.8.0

log

public void log(Priority priority,
                String message)
Use this form for priorities which are not directly supported, namely Priority.NOTICE, Priority.ALERT, Priority.EMERG and Priority.CRIT. This method is required for UNIX syslog compatibility.
Since:
version 0.8.0

log

public void log(String callerFQN,
                Priority priority,
                String message,
                Throwable t)
This method is intended to be invoked by wrapper classes.
Parameters:
callerFQN - The wrapper class' fully qualified class name.
priority - The priority of the logging request.
message - The message of the logging request.
t - The throwable of the logging request, may be null.
Since:
version 0.8.5

removeAllAppenders

public void removeAllAppenders()
Remove all previously added appenders from this Category instance.

This is useful when re-reading configuration information.

Specified by:
removeAllAppenders in interface AppenderAttachable

removeAppender

public void removeAppender(Appender appender)
Remove the appender passed as parameter form the list of appenders.
Specified by:
removeAppender in interface AppenderAttachable
Since:
0.8.2

removeAppender

public void removeAppender(String name)
Remove the appender with the name passed as parameter form the list of appenders.
Specified by:
removeAppender in interface AppenderAttachable
Since:
0.8.2

setAdditivity

public void setAdditivity(boolean additive)
Set the additivity flag for this Category instance.
Since:
0.8.1

setPriority

public void setPriority(Priority priority)
Set the priority of this Category.

Null values are admitted.


setResourceBundle

public void setResourceBundle(ResourceBundle bundle)
Set the resource bundle to be used with localized logging methods l7dlog(Priority,String,Throwable) and l7dlog(Priority,String,Object[],Throwable).
Since:
0.8.4

setRootPriority

public static void setRootPriority(Priority priority)
Set the priority of the root category.

warn

public void warn(Object message)
Log an object with warn priority. This method converts the (Object) passed as parameter to String using String.valueOf(Object) before logging it exactly in the same way as warn(String).

WARNING Note that passing a Throwable to this method will print the name of the Throwable but no stack trace. To print a stack trace use the warn(String, Throwable) form instead.

Parameters:
message - object to convert to String before writing into the log file
Since:
version 0.8.0

warn

public void warn(String message)
Log a message with warn priority.
Parameters:
message - string to write in the log file
Since:
version 0.8.0

warn

public void warn(String message,
                 Throwable t)
Log a message with the warn priority.
Parameters:
message - string to append
t - the exception to log, including a stack trace

Log4j 0.9.1

Please notify me about new log4j releases.