Class Category
- All Implemented Interfaces:
AppenderAttachable
- Direct Known Subclasses:
Logger
Logger subclass. It will be kept around to preserve backward compatibility until mid
2003.
Logger is a subclass of Category, i.e. it extends Category. In
other words, a logger is a category. Thus, all operations that can be performed on a category can be
performed on a logger. Internally, whenever log4j is asked to produce a Category object, it will instead produce a
Logger object. Log4j 1.2 will never produce Category objects but only
Logger instances. In order to preserve backward compatibility,
methods that previously accepted category objects still continue to accept category objects.
For example, the following are all legal and will work as expected.
// Deprecated form:
Category cat = Category.getInstance("foo.bar")
// Preferred form for retrieving loggers:
Logger logger = Logger.getLogger("foo.bar")
The first form is deprecated and should be avoided.
There is absolutely no need for new client code to use or refer to the
Category class. Whenever possible, please avoid referring to
it or using it.
See the short manual for an introduction on this class.
See the document entitled preparing for log4j 1.3 for a more detailed discussion.
- Author:
- Ceki Gülcü, Anders Kristensen
-
Field Summary
FieldsModifier and TypeFieldDescriptionprotected booleanAdditivity is set to true by default, that is children inherit the appenders of their ancestors by default.protected LevelThe assigned level of this category.protected StringThe name of this category.protected CategoryThe parent of this category.protected LoggerRepositoryprotected ResourceBundle -
Constructor Summary
Constructors -
Method Summary
Modifier and TypeMethodDescriptionvoidaddAppender(Appender newAppender) AddnewAppenderto the list of appenders of this Category instance.voidvoidcallAppenders(LoggingEvent event) Call the appenders in the hierrachy starting atthis.voidLog a message object with theDEBUGlevel.voidLog a message object with theDEBUGlevel including the stack trace of theThrowabletpassed as parameter.voidLog a message object with theERRORLevel.voidLog a message object with theERRORlevel including the stack trace of theThrowabletpassed as parameter.static LoggerDeprecated.voidLog a message object with theFATALLevel.voidLog a message object with theFATALlevel including the stack trace of theThrowabletpassed as parameter.protected voidThis method creates a new logging event and logs the event without further checks.booleanGet the additivity flag for this Category instance.Get the appenders contained in this category as anEnumeration.getAppender(String name) Look for the appender named asname.Deprecated.Please use the thegetEffectiveLevel()method instead.static EnumerationDeprecated.Please useLogManager.getCurrentLoggers()instead.static LoggerRepositoryDeprecated.Please useLogManager.getLoggerRepository()instead.Starting from this category, search the category hierarchy for a non-null level and return it.Deprecated.Please usegetLoggerRepository()instead.static CategorygetInstance(Class clazz) Deprecated.Please make sure to useLogger.getLogger(Class)instead.static CategorygetInstance(String name) Deprecated.Make sure to useLogger.getLogger(String)instead.final LevelgetLevel()Returns the assignedLevel, if any, for this Category.Return the theLoggerRepositorywhere thisCategoryis attached.final StringgetName()Return the category name.final CategoryReturns the parent of this category.final LevelDeprecated.Please usegetLevel()instead.Return the inheritedResourceBundlefor this category.protected StringReturns the string resource coresponding tokeyin this category's inherited resource bundle.static final CategorygetRoot()Deprecated.Please useLogger.getRootLogger()instead.voidLog a message object with theINFOLevel.voidLog a message object with theINFOlevel including the stack trace of theThrowabletpassed as parameter.booleanisAttached(Appender appender) Is the appender passed as parameter attached to this category?booleanCheck whether this category is enabled for theDEBUGLevel.booleanisEnabledFor(Priority level) Check whether this category is enabled for a givenLevelpassed as parameter.booleanCheck whether this category is enabled for the info Level.voidLog a localized and parameterized message.voidLog a localized message.voidThis is the most generic printing method.voidThis generic form is intended to be used by wrappers.voidThis generic form is intended to be used by wrappers.voidRemove all previously added appenders from this Category instance.voidremoveAppender(String name) Remove the appender with the name passed as parameter form the list of appenders.voidremoveAppender(Appender appender) Remove the appender passed as parameter form the list of appenders.voidsetAdditivity(boolean additive) Set the additivity flag for this Category instance.voidSet the level of this Category.voidsetPriority(Priority priority) Deprecated.Please usesetLevel(org.apache.log4j.Level)instead.voidsetResourceBundle(ResourceBundle bundle) Set the resource bundle to be used with localized logging methodsl7dlog(Priority, String, Throwable)andl7dlog(Priority, String, Object[], Throwable).static voidshutdown()Deprecated.Please useLogManager.shutdown()instead.voidLog a message object with theWARNLevel.void
-
Field Details
-
name
The name of this category. -
level
The assigned level of this category. Thelevelvariable need not be assigned a value in which case it is inherited form the hierarchy. -
parent
The parent of this category. All categories have at least one ancestor which is the root category. -
resourceBundle
-
repository
-
additive
protected boolean additiveAdditivity is set to true by default, that is children inherit the appenders of their ancestors by default. If this variable is set tofalsethen 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 tofalsetoo. See the user manual for more details.
-
-
Constructor Details
-
Category
This constructor created a newCategoryinstance 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 Details
-
addAppender
AddnewAppenderto the list of appenders of this Category instance.If
newAppenderis already in the list of appenders, then it won't be added again.- Specified by:
addAppenderin interfaceAppenderAttachable
-
assertLog
Ifassertionparameter isfalse, then logsmsgas anerrorstatement.The
assertmethod has been renamed toassertLogbecauseassertis a language reserved word in JDK 1.4.- Parameters:
assertion-msg- The message to print ifassertionis false.- Since:
- 1.2
-
callAppenders
Call the appenders in the hierrachy starting atthis. 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:
event- the event to log.
-
debug
Log a message object with theDEBUGlevel.This method first checks if this category is
DEBUGenabled by comparing the level of this category with theDEBUGlevel. If this category isDEBUGenabled, then it converts the message object (passed as parameter) to a string by invoking the appropriateObjectRenderer. 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
Throwableto this method will print the name of theThrowablebut no stack trace. To print a stack trace use thedebug(Object, Throwable)form instead.- Parameters:
message- the message object to log.
-
debug
Log a message object with theDEBUGlevel including the stack trace of theThrowabletpassed 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
Log a message object with theERRORLevel.This method first checks if this category is
ERRORenabled by comparing the level of this category withERRORLevel. If this category isERRORenabled, then it converts the message object passed as parameter to a string by invoking the appropriateObjectRenderer. 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
Throwableto this method will print the name of theThrowablebut no stack trace. To print a stack trace use theerror(Object, Throwable)form instead.- Parameters:
message- the message object to log
-
error
Log a message object with theERRORlevel including the stack trace of theThrowabletpassed 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
Deprecated.Please useLogManager.exists(java.lang.String)instead.If the named category exists (in the default hierarchy) then it returns a reference to the category, otherwise it returnsnull.- Since:
- 0.8.5
-
fatal
Log a message object with theFATALLevel.This method first checks if this category is
FATALenabled by comparing the level of this category withFATALLevel. If the category isFATALenabled, then it converts the message object passed as parameter to a string by invoking the appropriateObjectRenderer. 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
Throwableto this method will print the name of the Throwable but no stack trace. To print a stack trace use thefatal(Object, Throwable)form instead.- Parameters:
message- the message object to log
-
fatal
Log a message object with theFATALlevel including the stack trace of theThrowabletpassed 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
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
Get the appenders contained in this category as anEnumeration. If no appenders can be found, then aNullEnumerationis returned.- Specified by:
getAllAppendersin interfaceAppenderAttachable- Returns:
- Enumeration An enumeration of the appenders in this category.
-
getAppender
Look for the appender named asname.Return the appender with that name if in the list. Return
nullotherwise.- Specified by:
getAppenderin interfaceAppenderAttachable
-
getEffectiveLevel
Starting from this category, search the category hierarchy for a non-null level and return it. Otherwise, return the level of the root category.The Category class is designed so that this method executes as quickly as possible.
-
getChainedPriority
Deprecated.Please use the thegetEffectiveLevel()method instead. -
getCurrentCategories
Deprecated.Please useLogManager.getCurrentLoggers()instead.Returns all the currently defined categories in the default hierarchy as anEnumeration.The root category is not included in the returned
Enumeration. -
getDefaultHierarchy
Deprecated.Please useLogManager.getLoggerRepository()instead.Return the default Hierarchy instance.- Since:
- 1.0
-
getHierarchy
Deprecated.Please usegetLoggerRepository()instead.Return the theHierarchywhere thisCategoryinstance is attached.- Since:
- 1.1
-
getLoggerRepository
Return the theLoggerRepositorywhere thisCategoryis attached.- Since:
- 1.2
-
getInstance
Deprecated.Make sure to useLogger.getLogger(String)instead. -
getInstance
Deprecated.Please make sure to useLogger.getLogger(Class)instead. -
getName
Return the category name. -
getParent
Returns the parent of this category. Note that the parent of a given category may change during the lifetime of the category.The root category will return
null.- Since:
- 1.2
-
getLevel
Returns the assignedLevel, if any, for this Category.- Returns:
- Level - the assigned Level, can be
null.
-
getPriority
Deprecated.Please usegetLevel()instead. -
getRoot
Deprecated.Please useLogger.getRootLogger()instead. -
getResourceBundle
Return the inheritedResourceBundlefor 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
nullis returned.- Since:
- 0.9.0
-
getResourceBundleString
Returns the string resource coresponding tokeyin this category's inherited resource bundle. See alsogetResourceBundle().If the resource cannot be found, then an
errormessage will be logged complaining about the missing resource. -
info
Log a message object with theINFOLevel.This method first checks if this category is
INFOenabled by comparing the level of this category withINFOLevel. If the category isINFOenabled, then it converts the message object passed as parameter to a string by invoking the appropriateObjectRenderer. 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
Throwableto this method will print the name of the Throwable but no stack trace. To print a stack trace use theinfo(Object, Throwable)form instead.- Parameters:
message- the message object to log
-
info
Log a message object with theINFOlevel including the stack trace of theThrowabletpassed 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.
-
isAttached
Is the appender passed as parameter attached to this category?- Specified by:
isAttachedin interfaceAppenderAttachable
-
isDebugEnabled
public boolean isDebugEnabled()Check whether this category is enabled for theDEBUGLevel.This function is intended to lessen the computational cost of disabled log debug statements.
For some
catCategory 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 thecatis debug enabled, you will incur the cost of evaluating whether the category is debug enabled twice. Once inisDebugEnabledand once in thedebug. This is an insignificant overhead since evaluating a category takes about 1%% of the time it takes to actually log.- Returns:
- boolean -
trueif this category is debug enabled,falseotherwise.
-
isEnabledFor
Check whether this category is enabled for a givenLevelpassed as parameter.See also
isDebugEnabled().- Returns:
- boolean True if this category is enabled for
level.
-
isInfoEnabled
public boolean isInfoEnabled()Check whether this category is enabled for the info Level. See alsoisDebugEnabled().- Returns:
- boolean -
trueif this category is enabled for level info,falseotherwise.
-
l7dlog
Log a localized message. The user supplied parameterkeyis replaced by its localized version from the resource bundle.- Since:
- 0.8.4
- See Also:
-
l7dlog
Log a localized and parameterized message. First, the user suppliedkeyis searched in the resource bundle. Next, the resulting pattern is formatted usingMessageFormat.format(String, Object[])method with the user supplied object arrayparams.- Since:
- 0.8.4
-
log
This generic form is intended to be used by wrappers. -
log
This generic form is intended to be used by wrappers. -
log
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.level- The level 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:
removeAllAppendersin interfaceAppenderAttachable
-
removeAppender
Remove the appender passed as parameter form the list of appenders.- Specified by:
removeAppenderin interfaceAppenderAttachable- Since:
- 0.8.2
-
removeAppender
Remove the appender with the name passed as parameter form the list of appenders.- Specified by:
removeAppenderin interfaceAppenderAttachable- Since:
- 0.8.2
-
setAdditivity
public void setAdditivity(boolean additive) Set the additivity flag for this Category instance.- Since:
- 0.8.1
-
setLevel
Set the level of this Category. If you are passing any ofLevel.DEBUG,Level.INFO,Level.WARN,Level.ERROR,Level.FATALas a parameter, you need to case them as Level.As in
logger.setLevel((Level) Level.DEBUG);
Null values are admitted.
-
setPriority
Deprecated.Please usesetLevel(org.apache.log4j.Level)instead.Set the level of this Category.Null values are admitted.
-
setResourceBundle
Set the resource bundle to be used with localized logging methodsl7dlog(Priority, String, Throwable)andl7dlog(Priority, String, Object[], Throwable).- Since:
- 0.8.4
-
shutdown
public static void shutdown()Deprecated.Please useLogManager.shutdown()instead.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
SocketAppenderandAsyncAppenderneed to be closed before the application exists. Otherwise, pending logging events might be lost.The
shutdownmethod 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
Log a message object with theWARNLevel.This method first checks if this category is
WARNenabled by comparing the level of this category withWARNLevel. If the category isWARNenabled, then it converts the message object passed as parameter to a string by invoking the appropriateObjectRenderer. 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
Throwableto this method will print the name of the Throwable but no stack trace. To print a stack trace use thewarn(Object, Throwable)form instead.- Parameters:
message- the message object to log.
-
warn
Log a message with theWARNlevel including the stack trace of theThrowabletpassed 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.
-
LogManager.exists(java.lang.String)instead.