public class Category extends Object
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 document entitled preparing for log4j 1.3 for a more detailed discussion.
Modifier and Type | Field and Description |
---|---|
protected static org.tinylog.provider.LoggingProvider |
provider |
protected static int |
STACKTRACE_DEPTH |
Modifier | Constructor and Description |
---|---|
protected |
Category(String name) |
Modifier and Type | Method and Description |
---|---|
void |
addAppender(Appender newAppender)
Add
newAppender to the list of appenders of this Category instance. |
void |
assertLog(boolean assertion,
String msg)
|
void |
callAppenders(LoggingEvent event)
Call the appenders in the hierarchy 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. |
Level |
getEffectiveLevel()
Starting from this category, search the category hierarchy for a non-null level and return it.
|
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. |
String |
getName()
Retrieves 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. |
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?
|
protected static boolean |
isCoveredByMinimumLevel(org.tinylog.Level level)
Checks if a given severity level is covered by the logging provider's minimum level.
|
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)
|
protected static final int STACKTRACE_DEPTH
protected static final org.tinylog.provider.LoggingProvider provider
protected Category(String name)
name
- Name for the category (typically the name of the class that will use this category)public void addAppender(Appender newAppender)
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.
newAppender
- Appender to registerpublic void assertLog(boolean assertion, String msg)
assertion
parameter is false
, then logs msg
as an error
statement.
The assert
method has been renamed to assertLog
because assert
is a language reserved
word in JDK 1.4.
assertion
- true
for dropping the passed message, false
for outputtingmsg
- The message to print if assertion
is false.public void callAppenders(LoggingEvent event)
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.
event
- the event to log.public void debug(Object message)
DEBUG
level.
This method first checks if this category is DEBUG
enabled by comparing the level of this category with
the DEBUG
level. If this category is DEBUG
enabled, then it converts the message
object (passed as parameter) to a string. 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.
message
- the message object to log.public void debug(Object message, Throwable t)
DEBUG
level including the stack trace of the Throwable
t
passed as parameter.
See debug(Object)
form for more detailed information.
message
- the message object to log.t
- the exception to log, including its stack trace.public void error(Object message)
ERROR
Level.
This method first checks if this category is ERROR
enabled by comparing the level of this category with
ERROR
Level. If this category is ERROR
enabled, then it converts the message object
passed as parameter to a string. 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.
message
- the message object to logpublic void error(Object message, Throwable t)
ERROR
level including the stack trace of the Throwable
t
passed as parameter.
See error(Object)
form for more detailed information.
message
- the message object to log.t
- the exception to log, including its stack trace.@Deprecated public static Logger exists(String name)
LogManager.exists(java.lang.String)
instead.null
.name
- Name of the categorynull
public void fatal(Object message)
FATAL
Level.
This method first checks if this category is FATAL
enabled by comparing the level of this category with
FATAL
Level. If the category is FATAL
enabled, then it converts the message object
passed as parameter to a string. 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.
message
- the message object to logpublic void fatal(Object message, Throwable t)
FATAL
level including the stack trace of the Throwable
t
passed as parameter.
See fatal(Object)
for more detailed information.
message
- the message object to log.t
- the exception to log, including its stack trace.protected void forcedLog(String fqcn, Priority level, Object message, Throwable t)
fqcn
- Fully-qualified class name of the category or logger instancelevel
- Priority to logmessage
- Message to logt
- Exception to logpublic boolean getAdditivity()
true
public Enumeration getAllAppenders()
Enumeration
. If no appenders can be found, then a
empty enumeration is returned.public Appender getAppender(String name)
name
.name
- Name of the appendernull
otherwise.public Level getEffectiveLevel()
The Category class is designed so that this method executes as quickly as possible.
@Deprecated public Priority getChainedPriority()
getEffectiveLevel()
method instead.@Deprecated public static Enumeration getCurrentCategories()
LogManager.getCurrentLoggers()
instead.Enumeration
.
The root category is not included in the returned Enumeration
.
@Deprecated public static Category getInstance(String name)
Logger.getLogger(String)
instead.name
- Name of the category@Deprecated public static Category getInstance(Class clazz)
Logger.getLogger(Class)
instead.clazz
- Class to logpublic final String getName()
public final Category getParent()
The root category will return null
.
public final Level getLevel()
Level
, if any, for this Category.@Deprecated public final Level getPriority()
getLevel()
instead.@Deprecated public static final Category getRoot()
Logger.getRootLogger()
instead.public ResourceBundle getResourceBundle()
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.
public void info(Object message)
INFO
Level.
This method first checks if this category is INFO
enabled by comparing the level of this category with
INFO
Level. If the category is INFO
enabled, then it converts the message object
passed as parameter to a string. 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.
message
- the message object to logpublic void info(Object message, Throwable t)
INFO
level including the stack trace of the Throwable
t
passed as parameter.
See info(Object)
for more detailed information.
message
- the message object to log.t
- the exception to log, including its stack trace.public boolean isAttached(Appender appender)
appender
- Appender to checkfalse
public boolean isDebugEnabled()
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 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.
true
if this category is debug enabled, false
otherwise.public boolean isEnabledFor(Priority level)
Level
passed as parameter.
See also isDebugEnabled()
.
level
- Priority to check whether enabledlevel
.public boolean isInfoEnabled()
isDebugEnabled()
.true
if this category is enabled for level info, false
otherwise.public void l7dlog(Priority priority, String key, Throwable t)
key
is replaced by its localized version from the
resource bundle.priority
- Priority for log entrykey
- Resource key for translationt
- Exception to logsetResourceBundle(java.util.ResourceBundle)
public void l7dlog(Priority priority, String key, Object[] params, Throwable t)
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
.priority
- Priority for log entrykey
- Resource key for translationparams
- Arguments for messaget
- Exception to logpublic void log(Priority priority, Object message, Throwable t)
priority
- Priority for log entrymessage
- Message to logt
- Exception to logpublic void log(Priority priority, Object message)
priority
- Priority for log entrymessage
- Message to logpublic void log(String callerFQCN, Priority level, Object message, Throwable t)
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.public void removeAllAppenders()
This is useful when re-reading configuration information.
public void removeAppender(Appender appender)
appender
- Appender to removepublic void removeAppender(String name)
name
- Name of appender to removepublic void setAdditivity(boolean additive)
additive
- Additivity flag (will be ignored)public void setLevel(Level level)
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.
level
- New level (will be ignored)@Deprecated public void setPriority(Priority priority)
setLevel(org.apache.log4j.Level)
instead.Null values are admitted.
priority
- New priority (will be ignored)public void setResourceBundle(ResourceBundle bundle)
l7dlog(Priority,String,Throwable)
and
l7dlog(Priority,String,Object[],Throwable)
.bundle
- New resource bundle for translations@Deprecated public static void shutdown()
LogManager.shutdown()
instead.
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.
public void warn(Object message)
WARN
Level.
This method first checks if this category is WARN
enabled by comparing the level of this category with
WARN
Level. If the category is WARN
enabled, then it converts the message object
passed as parameter to a string. 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 warn(Object, Throwable)
form instead.
message
- the message object to log.public void warn(Object message, Throwable t)
WARN
level including the stack trace of the Throwable
t
passed as
parameter.
See warn(Object)
for more detailed information.
message
- the message object to log.t
- the exception to log, including its stack trace.protected static boolean isCoveredByMinimumLevel(org.tinylog.Level level)
level
- Severity level to checktrue
if given severity level is covered, otherwise false
Copyright © 2020. All rights reserved.