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 boolean
Additivity is set to true by default, that is children inherit the appenders of their ancestors by default.protected Level
The assigned level of this category.protected String
The name of this category.protected Category
The parent of this category.protected LoggerRepository
protected ResourceBundle
-
Constructor Summary
Constructors -
Method Summary
Modifier and TypeMethodDescriptionvoid
addAppender
(Appender newAppender) AddnewAppender
to the list of appenders of this Category instance.void
void
callAppenders
(LoggingEvent event) Call the appenders in the hierrachy starting atthis
.void
Log a message object with theDEBUG
level.void
Log a message object with theDEBUG
level including the stack trace of theThrowable
t
passed as parameter.void
Log a message object with theERROR
Level.void
Log a message object with theERROR
level including the stack trace of theThrowable
t
passed as parameter.static Logger
Deprecated.void
Log a message object with theFATAL
Level.void
Log a message object with theFATAL
level including the stack trace of theThrowable
t
passed as parameter.protected void
This method creates a new logging event and logs the event without further checks.boolean
Get 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 Enumeration
Deprecated.Please useLogManager.getCurrentLoggers()
instead.static LoggerRepository
Deprecated.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 Category
getInstance
(Class clazz) Deprecated.Please make sure to useLogger.getLogger(Class)
instead.static Category
getInstance
(String name) Deprecated.Make sure to useLogger.getLogger(String)
instead.final Level
getLevel()
Returns the assignedLevel
, if any, for this Category.Return the theLoggerRepository
where thisCategory
is attached.final String
getName()
Return the category name.final Category
Returns the parent of this category.final Level
Deprecated.Please usegetLevel()
instead.Return the inheritedResourceBundle
for this category.protected String
Returns the string resource coresponding tokey
in this category's inherited resource bundle.static final Category
getRoot()
Deprecated.Please useLogger.getRootLogger()
instead.void
Log a message object with theINFO
Level.void
Log a message object with theINFO
level including the stack trace of theThrowable
t
passed as parameter.boolean
isAttached
(Appender appender) Is the appender passed as parameter attached to this category?boolean
Check whether this category is enabled for theDEBUG
Level.boolean
isEnabledFor
(Priority level) Check whether this category is enabled for a givenLevel
passed as parameter.boolean
Check whether this category is enabled for the info Level.void
Log a localized and parameterized message.void
Log a localized message.void
This is the most generic printing method.void
This generic form is intended to be used by wrappers.void
This generic form is intended to be used by wrappers.void
Remove all previously added appenders from this Category instance.void
removeAppender
(String name) Remove the appender with the name passed as parameter form the list of appenders.void
removeAppender
(Appender appender) Remove the appender passed as parameter form the list of appenders.void
setAdditivity
(boolean additive) Set the additivity flag for this Category instance.void
Set the level of this Category.void
setPriority
(Priority priority) Deprecated.Please usesetLevel(org.apache.log4j.Level)
instead.void
setResourceBundle
(ResourceBundle bundle) Set the resource bundle to be used with localized logging methodsl7dlog(Priority,String,Throwable)
andl7dlog(Priority,String,Object[],Throwable)
.static void
shutdown()
Deprecated.Please useLogManager.shutdown()
instead.void
Log a message object with theWARN
Level.void
-
Field Details
-
name
The name of this category. -
level
The assigned level of this category. Thelevel
variable 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 tofalse
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 tofalse
too. See the user manual for more details.
-
-
Constructor Details
-
Category
This constructor created a newCategory
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 Details
-
addAppender
AddnewAppender
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 interfaceAppenderAttachable
-
assertLog
Ifassertion
parameter isfalse
, then logsmsg
as anerror
statement.The
assert
method has been renamed toassertLog
becauseassert
is a language reserved word in JDK 1.4.- Parameters:
assertion
-msg
- The message to print ifassertion
is 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 theDEBUG
level.This method first checks if this category is
DEBUG
enabled by comparing the level of this category with theDEBUG
level. If this category isDEBUG
enabled, 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
Throwable
to this method will print the name of theThrowable
but 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 theDEBUG
level including the stack trace of theThrowable
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
Log a message object with theERROR
Level.This method first checks if this category is
ERROR
enabled by comparing the level of this category withERROR
Level. If this category isERROR
enabled, 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
Throwable
to this method will print the name of theThrowable
but 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 theERROR
level including the stack trace of theThrowable
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
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 theFATAL
Level.This method first checks if this category is
FATAL
enabled by comparing the level of this category withFATAL
Level. If the category isFATAL
enabled, 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
Throwable
to 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 theFATAL
level including the stack trace of theThrowable
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
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 aNullEnumeration
is returned.- Specified by:
getAllAppenders
in 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
null
otherwise.- Specified by:
getAppender
in 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 theHierarchy
where thisCategory
instance is attached.- Since:
- 1.1
-
getLoggerRepository
Return the theLoggerRepository
where thisCategory
is 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 inheritedResourceBundle
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
Returns the string resource coresponding tokey
in this category's inherited resource bundle. See alsogetResourceBundle()
.If the resource cannot be found, then an
error
message will be logged complaining about the missing resource. -
info
Log a message object with theINFO
Level.This method first checks if this category is
INFO
enabled by comparing the level of this category withINFO
Level. If the category isINFO
enabled, 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
Throwable
to 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 theINFO
level including the stack trace of theThrowable
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.
-
isAttached
Is the appender passed as parameter attached to this category?- Specified by:
isAttached
in interfaceAppenderAttachable
-
isDebugEnabled
public boolean isDebugEnabled()Check whether this category is enabled for theDEBUG
Level.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 thecat
is debug enabled, you will incur the cost of evaluating whether the category is debug enabled twice. Once inisDebugEnabled
and 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 -
true
if this category is debug enabled,false
otherwise.
-
isEnabledFor
Check whether this category is enabled for a givenLevel
passed as parameter. See alsoisDebugEnabled()
.- 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 -
true
if this category is enabled for level info,false
otherwise.
-
l7dlog
Log a localized message. The user supplied parameterkey
is 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 suppliedkey
is 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:
removeAllAppenders
in interfaceAppenderAttachable
-
removeAppender
Remove the appender passed as parameter form the list of appenders.- Specified by:
removeAppender
in interfaceAppenderAttachable
- Since:
- 0.8.2
-
removeAppender
Remove the appender with the name passed as parameter form the list of appenders.- Specified by:
removeAppender
in 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.FATAL
as 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
SocketAppender
andAsyncAppender
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
Log a message object with theWARN
Level.This method first checks if this category is
WARN
enabled by comparing the level of this category withWARN
Level. If the category isWARN
enabled, 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
Throwable
to 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 theWARN
level including the stack trace of theThrowable
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.
-
LogManager.exists(java.lang.String)
instead.