|
Log4j 1.2.14 | |||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
org.apache.log4j Class Category
java.lang.Object | +--org.apache.log4j.Category
- All Implemented Interfaces:
- AppenderAttachable
- Direct Known Subclasses:
- Logger
- public class Category
- extends Object
- implements AppenderAttachable
This class has been deprecated and
replaced by the 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 | |
protected boolean |
additive
Additivity is set to true by default, that is children inherit the appenders of their ancestors by default. |
protected Level |
level
The assigned level of this category. |
protected String |
name
The name of this category. |
protected Category |
parent
The parent of this category. |
protected LoggerRepository |
repository
|
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 |
assertLog(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 level. |
void |
debug(Object message,
Throwable t)
Log a message object with the DEBUG level including
the stack trace of the Throwable t passed as
parameter. |
void |
error(Object message)
Log a message object with the ERROR Level. |
void |
error(Object message,
Throwable t)
Log a message object with the ERROR level including
the stack trace of the Throwable t passed as
parameter. |
static Logger |
exists(String name)
Deprecated. Please use LogManager.exists(java.lang.String) instead. |
void |
fatal(Object message)
Log a message object with the FATAL Level. |
void |
fatal(Object message,
Throwable t)
Log a message object with the FATAL level including
the stack trace of the Throwable t passed as
parameter. |
protected void |
forcedLog(String fqcn,
Priority level,
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()
Deprecated. Please use the the getEffectiveLevel() method
instead. |
static Enumeration |
getCurrentCategories()
Deprecated. Please use LogManager.getCurrentLoggers() instead. |
static LoggerRepository |
getDefaultHierarchy()
Deprecated. Please use LogManager.getLoggerRepository() instead. |
Level |
getEffectiveLevel()
Starting from this category, search the category hierarchy for a non-null level and return it. |
LoggerRepository |
getHierarchy()
Deprecated. Please use getLoggerRepository() instead. |
static Category |
getInstance(Class clazz)
Deprecated. Please make sure to use Logger.getLogger(Class) instead. |
static Category |
getInstance(String name)
Deprecated. Make sure to use Logger.getLogger(String) instead. |
Level |
getLevel()
Returns the assigned Level , if any, for this Category. |
LoggerRepository |
getLoggerRepository()
Return the the LoggerRepository where this
Category is attached. |
String |
getName()
Return the category name. |
Category |
getParent()
Returns the parent of this category. |
Level |
getPriority()
Deprecated. Please use getLevel() instead. |
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()
Deprecated. Please use Logger.getRootLogger() instead. |
void |
info(Object message)
Log a message object with the INFO Level. |
void |
info(Object message,
Throwable t)
Log a message object with the INFO level including
the stack trace of the Throwable t passed as
parameter. |
boolean |
isAttached(Appender appender)
Is the appender passed as parameter attached to this category? |
boolean |
isDebugEnabled()
Check whether this category is enabled for the DEBUG
Level. |
boolean |
isEnabledFor(Priority level)
Check whether this category is enabled for a given Level passed as parameter. |
boolean |
isInfoEnabled()
Check whether this category is enabled for the info Level. |
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 level,
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 |
setLevel(Level level)
Set the level of this Category. |
void |
setPriority(Priority priority)
Deprecated. Please use setLevel(org.apache.log4j.Level) instead. |
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()
Deprecated. Please use LogManager.shutdown() instead. |
void |
warn(Object message)
Log a message object with the WARN Level. |
void |
warn(Object message,
Throwable t)
Log a message with the WARN level 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 |
name
protected String name
- The name of this category.
level
protected volatile Level level
- The assigned level of this category. The
level
variable need not be assigned 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
repository
protected LoggerRepository repository
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 tofalse
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 interfaceAppenderAttachable
assertLog
public void assertLog(boolean assertion, String msg)
- If
assertion
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
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:
event
- the event to log.
debug
public void debug(Object message)
- Log a message object with the
DEBUG
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
public void debug(Object message, Throwable t)
- Log a message object with the
DEBUG
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
public void error(Object message)
- Log a message object with the
ERROR
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
public void error(Object message, Throwable t)
- Log a message object with the
ERROR
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
public static Logger exists(String name)
- Deprecated. Please use
LogManager.exists(java.lang.String)
instead. - If the named category exists (in the default hierarchy) then it
returns a reference to the category, otherwise it returns
null
. - Since:
- 0.8.5
fatal
public void fatal(Object message)
- Log a message object with the
FATAL
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
public void fatal(Object message, Throwable t)
- Log a message object with the
FATAL
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
protected void forcedLog(String fqcn, Priority level, 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 aNullEnumeration
is returned. - Specified by:
getAllAppenders
in interfaceAppenderAttachable
- 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 interfaceAppenderAttachable
getEffectiveLevel
public Level 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
public Priority getChainedPriority()
- Deprecated. Please use the the
getEffectiveLevel()
method instead.
getCurrentCategories
public static Enumeration getCurrentCategories()
- Deprecated. Please use
LogManager.getCurrentLoggers()
instead. - 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 LoggerRepository getDefaultHierarchy()
- Deprecated. Please use
LogManager.getLoggerRepository()
instead. - Return the default Hierarchy instance.
- Since:
- 1.0
getHierarchy
public LoggerRepository getHierarchy()
- Deprecated. Please use
getLoggerRepository()
instead. - Return the the
Hierarchy
where thisCategory
instance is attached. - Since:
- 1.1
getLoggerRepository
public LoggerRepository getLoggerRepository()
- Return the the
LoggerRepository
where thisCategory
is attached. - Since:
- 1.2
getInstance
public static Category getInstance(String name)
- Deprecated. Make sure to use
Logger.getLogger(String)
instead.
getInstance
public static Category getInstance(Class clazz)
- Deprecated. Please make sure to use
Logger.getLogger(Class)
instead.
getName
public final String getName()
- Return the category name.
getParent
public final Category 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
public final Level getLevel()
- Returns the assigned
Level
, if any, for this Category. - Returns:
- Level - the assigned Level, can be
null
.
getPriority
public final Level getPriority()
- Deprecated. Please use
getLevel()
instead.
getRoot
public static final Category getRoot()
- Deprecated. Please use
Logger.getRootLogger()
instead.
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 alsogetResourceBundle()
.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
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
public void info(Object message, Throwable t)
- Log a message object with the
INFO
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
public boolean isAttached(Appender appender)
- 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 the
DEBUG
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
public boolean isEnabledFor(Priority level)
- Check whether this category is enabled for a given
Level
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 also
isDebugEnabled()
. - Returns:
- boolean -
true
if this category is enabled for level 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 usingMessageFormat.format(String,Object[])
method with the user supplied object arrayparams
. - 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 level, 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.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
public void removeAppender(Appender appender)
- Remove the appender passed as parameter form the list of appenders.
- Specified by:
removeAppender
in interfaceAppenderAttachable
- 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 interfaceAppenderAttachable
- Since:
- 0.8.2
setAdditivity
public void setAdditivity(boolean additive)
- Set the additivity flag for this Category instance.
- Since:
- 0.8.1
setLevel
public void setLevel(Level level)
- Set the level of this Category. If you are passing any of
Level.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
public void setPriority(Priority priority)
- Deprecated. Please use
setLevel(org.apache.log4j.Level)
instead. - Set the level 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)
andl7dlog(Priority,String,Object[],Throwable)
. - Since:
- 0.8.4
shutdown
public static void shutdown()
- Deprecated. Please use
LogManager.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
public void warn(Object message)
- Log a message object with the
WARN
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
public void warn(Object message, Throwable t)
- Log a message with the
WARN
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.
|
Log4j 1.2.14 | |||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
Copyright 2000-2005 Apache Software Foundation.