Log4j 1.1.3

org.apache.log4j
Class Category

java.lang.Object
  |
  +--org.apache.log4j.Category
All Implemented Interfaces:
AppenderAttachable
Direct Known Subclasses:
AppServerCategory, 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 hierarchical categories and their evaluation.

See the user manual for an introduction on this class.

Author:
Ceki Gülcü, Anders Kristensen

Field Summary
protected  boolean additive
          Additivity is set to true by default, that is children inherit the appenders of their ancestors by default.
static String DEFAULT_CONFIGURATION_FILE
          This string constant is set to log4j.properties the name of the file that will be searched by default in classpath.
static String DEFAULT_CONFIGURATION_KEY
          This string constant is set to log4j.configuration.
static String DEFAULT_INIT_OVERRIDE_KEY
          Setting the system property log4j.defaultInitOverride to "true" or any other value than "false" will skip default configuration process.
static Hierarchy defaultHierarchy
          The hierarchy where categories are attached to by default.
protected  Hierarchy hierarchy
           
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 a message object with the DEBUG priority.
 void debug(Object message, Throwable t)
          Log a message object with the DEBUG priority including the stack trace of the Throwable t passed as parameter.
 void error(Object message)
          Log a message object with the ERROR priority.
 void error(Object message, Throwable t)
          Log a message object with the ERROR priority including the stack trace of the Throwable t passed as parameter.
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.
 void fatal(Object message)
          Log a message object with the FATAL priority.
 void fatal(Object message, Throwable t)
          Log a message object with the FATAL priority including the stack trace of the Throwable t passed as parameter.
protected  void forcedLog(String fqcn, Priority priority, Object message, Throwable t)
          This method creates a new logging event and logs the event without further checks.
 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 Hierarchy getDefaultHierarchy()
          Return the default Hierarchy instance.
 Hierarchy getHierarchy()
          Return the the Hierarchy where this Category instance is attached.
static Category getInstance(Class clazz)
          Shorthand for getInstance(clazz.getName()).
static Category getInstance(String name)
          Retrieve a category with named as the name parameter.
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 inherited ResourceBundle for this category.
protected  String getResourceBundleString(String key)
          Returns the string resource coresponding to key in this category's inherited resource bundle.
static Category getRoot()
          Return the root of the default category hierrachy.
 void info(Object message)
          Log a message object with the INFO priority.
 void info(Object message, Throwable t)
          Log a message object with the INFO priority including the stack trace of the Throwable t passed as parameter.
 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 info 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, Object message)
          This generic form is intended to be used by wrappers.
 void log(Priority priority, Object message, Throwable t)
          This generic form is intended to be used by wrappers.
 void log(String callerFQCN, Priority priority, Object message, Throwable t)
          This is the most generic printing method.
 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 shutdown()
          Calling this method will safely close and remove all appenders in all the categories including root contained in the default hierachy.
 void warn(Object message)
          Log a message object with the WARN priority.
 void warn(Object message, Throwable t)
          Log a message with the WARN priority including the stack trace of the Throwable t passed as parameter.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

defaultHierarchy

public static final Hierarchy defaultHierarchy
The hierarchy where categories are attached to by default.

DEFAULT_CONFIGURATION_FILE

public static final String DEFAULT_CONFIGURATION_FILE
This string constant is set to log4j.properties the name of the file that will be searched by default in classpath. If the file can be found, then it is fed to the PropertyConfigurator. See also DEFAULT_CONFIGURATION_KEY for a more general alternative.

See also the full description of default intialization procedure.

Since:
0.8.5

DEFAULT_CONFIGURATION_KEY

public static final String DEFAULT_CONFIGURATION_KEY
This string constant is set to log4j.configuration.

It corresponds to name of a system property that, if set, specifies the name of the resource containing the properties file or URL with which log4j should configure itself. See OptionConverter.selectAndConfigure(java.net.URL, org.apache.log4j.Hierarchy) for more detailed information on the processing of this option.

Setting the log4j.configuration system property overrides the default search for the file log4j.properties.

Note that all property keys are case sensitive.

See also the full description of default intialization procedure.

Since:
1.0

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 process.

The current value of the DEFAULT_INIT_OVERRIDE_KEY string constant is log4j.defaultInitOverride.

See also the full description of default intialization procedure.

Note that all property keys are case sensitive.

Since:
0.8.5

name

protected String name
The name of this category.

priority

protected volatile Priority priority
The assigned priority of this category. The priority variable need not be assined a value in which case it is inherited form the hierarchy.

parent

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

resourceBundle

protected ResourceBundle resourceBundle

hierarchy

protected Hierarchy hierarchy

additive

protected boolean additive
Additivity is set to true by default, that is children inherit the appenders of their ancestors by default. If this variable is set to false then the appenders found in the ancestors of this category are not used. However, the children of this category will inherit its appenders, unless the children have their additivity flag set to false too. See the user manual for more details.
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. You should not create categories directly.

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 calls all the appenders inherited from 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 a message object with the DEBUG priority.

This method first checks if this category is DEBUG enabled by comparing the priority of this category with the DEBUG priority. If this category is DEBUG enabled, then it converts the message object (passed as parameter) to a string by invoking the appropriate ObjectRenderer. It then proceeds to call all the registered appenders in this category and also higher in the hierarchy depending on the value of the additivity flag.

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 debug(Object, Throwable) form instead.

Parameters:
message - the message object to log.

debug

public void debug(Object message,
                  Throwable t)
Log a message object with the DEBUG priority including the stack trace of the Throwable t passed as parameter.

See debug(Object) form for more detailed information.

Parameters:
message - the message object to log.
t - the exception to log, including its stack trace.

error

public void error(Object message)
Log a message object with the ERROR priority.

This method first checks if this category is ERROR enabled by comparing the priority of this category with ERROR priority. If this category is ERROR enabled, then it converts the message object passed as parameter to a string by invoking the appropriate ObjectRenderer. It proceeds to call all the registered appenders in this category and also higher in the hierarchy depending on the value of the additivity flag.

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(Object, Throwable) form instead.

Parameters:
message - the message object to log

error

public void error(Object message,
                  Throwable t)
Log a message object with the ERROR priority including the stack trace of the Throwable t passed as parameter.

See error(Object) form for more detailed information.

Parameters:
message - the message object to log.
t - the exception to log, including its 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


fatal

public void fatal(Object message)
Log a message object with the FATAL priority.

This method first checks if this category is FATAL enabled by comparing the priority of this category with FATAL priority. If the category is FATAL enabled, then it converts the message object passed as parameter to a string by invoking the appropriate ObjectRenderer. It proceeds to call all the registered appenders in this category and also higher in the hierarchy depending on the value of the additivity flag.

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 fatal(Object, Throwable) form instead.

Parameters:
message - the message object to log

fatal

public void fatal(Object message,
                  Throwable t)
Log a message object with the FATAL priority including the stack trace of the Throwable t passed as parameter.

See fatal(Object) for more detailed information.

Parameters:
message - the message object to log.
t - the exception to log, including its stack trace.

forcedLog

protected void forcedLog(String fqcn,
                         Priority priority,
                         Object message,
                         Throwable t)
This method creates a new logging event and logs the event without further checks.

getAdditivity

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

getAllAppenders

public Enumeration getAllAppenders()
Get the appenders contained in this category as an Enumeration. If no appenders can be found, then a NullEnumeration 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.


getDefaultHierarchy

public static Hierarchy getDefaultHierarchy()
Return the default Hierarchy instance.
Since:
1.0

getHierarchy

public Hierarchy getHierarchy()
Return the the Hierarchy where this Category instance is attached.
Since:
1.1

getInstance

public static Category getInstance(String name)
Retrieve a category with named as the name parameter. If the named category already exists, then the existing instance will be reutrned. Otherwise, a new instance is created. By default, categories do not have a set priority but inherit it from the hierarchy. This is one of the central features of log4j.
Parameters:
name - The name of the category to retrieve.

getInstance

public static Category getInstance(Class clazz)
Shorthand for getInstance(clazz.getName()).
Parameters:
clazz - The name of clazz will be used as the name of the category to retrieve. See getInstance(String) for more detailed information.
Since:
1.0

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".


getResourceBundle

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

This method walks the hierarchy to find the appropriate resource bundle. It will return the resource bundle attached to the closest ancestor of this category, much like the way priorities are searched. In case there is no bundle in the hierarchy then null is returned.

Since:
0.9.0

getResourceBundleString

protected String getResourceBundleString(String key)
Returns the string resource coresponding to key in this category's inherited resource bundle. See also getResourceBundle().

If the resource cannot be found, then an error message will be logged complaining about the missing resource.


info

public void info(Object message)
Log a message object with the INFO priority.

This method first checks if this category is INFO enabled by comparing the priority of this category with INFO priority. If the category is INFO enabled, then it converts the message object passed as parameter to a string by invoking the appropriate ObjectRenderer. It proceeds to call all the registered appenders in this category and also higher in the hierarchy depending on the value of the additivity flag.

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 info(Object, Throwable) form instead.

Parameters:
message - the message object to log

info

public void info(Object message,
                 Throwable t)
Log a message object with the INFO priority including the stack trace of the Throwable t passed as parameter.

See info(Object) for more detailed information.

Parameters:
message - the message object to log.
t - the exception to log, including its 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 disabled log debug statements.

For some cat Category object, when you write,

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

You incur the cost constructing the message, concatenatiion in this case, regardless of whether the message is logged or not.

If you are worried about speed, then you should write

 	 if(cat.isDebugEnabled()) { 
 	   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 info 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,
                Object message,
                Throwable t)
This generic form is intended to be used by wrappers.

log

public void log(Priority priority,
                Object message)
This generic form is intended to be used by wrappers.

log

public void log(String callerFQCN,
                Priority priority,
                Object message,
                Throwable t)
This is the most generic printing method. It is intended to be invoked by wrapper classes.
Parameters:
callerFQCN - 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.

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

shutdown

public static void shutdown()
Calling this method will safely close and remove all appenders in all the categories including root contained in the default hierachy.

Some appenders such as SocketAppender and AsyncAppender need to be closed before the application exists. Otherwise, pending logging events might be lost.

The shutdown method is careful to close nested appenders before closing regular appenders. This is allows configurations where a regular appender is attached to a category and again to a nested appender.

Since:
1.0

warn

public void warn(Object message)
Log a message object with the WARN priority.

This method first checks if this category is WARN enabled by comparing the priority of this category with WARN priority. If the category is WARN enabled, then it converts the message object passed as parameter to a string by invoking the appropriate ObjectRenderer. It proceeds to call all the registered appenders in this category and also higher in the hieararchy depending on the value of the additivity flag.

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(Object, Throwable) form instead.

Parameters:
message - the message object to log.

warn

public void warn(Object message,
                 Throwable t)
Log a message with the WARN priority including the stack trace of the Throwable t passed as parameter.

See warn(Object) for more detailed information.

Parameters:
message - the message object to log.
t - the exception to log, including its stack trace.

Log4j 1.1.3

Please notify me about new log4j releases.