org.apache.log4j
public class Category extends Object implements AppenderAttachable
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.
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 {@link #error(Object) 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 {@link Level#DEBUG DEBUG} level.
|
void | debug(Object message, Throwable t)
Log a message object with the DEBUG level including
the stack trace of the {@link Throwable} t passed as
parameter.
|
void | error(Object message)
Log a message object with the {@link Level#ERROR ERROR} Level.
|
void | error(Object message, Throwable t)
Log a message object with the ERROR level including
the stack trace of the {@link Throwable} t passed as
parameter.
|
static Logger | 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 {@link Level#FATAL FATAL} Level.
|
void | fatal(Object message, Throwable t)
Log a message object with the FATAL level including
the stack trace of the {@link 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 {@link
Enumeration}. |
Appender | getAppender(String name)
Look for the appender named as name .
|
Priority | getChainedPriority() |
static Enumeration | getCurrentCategories()
Returns all the currently defined categories in the default
hierarchy as an {@link java.util.Enumeration Enumeration}.
|
static LoggerRepository | getDefaultHierarchy()
Return the default Hierarchy instance. |
Level | getEffectiveLevel()
Starting from this category, search the category hierarchy for a
non-null level and return it. |
LoggerRepository | getHierarchy()
Return the the {@link Hierarchy} where this Category
instance is attached. |
static Category | getInstance(String name) |
static Category | getInstance(Class clazz) |
Level | getLevel()
Returns the assigned {@link Level}, if any, for this Category. |
LoggerRepository | getLoggerRepository()
Return the the {@link LoggerRepository} where this
Category is attached. |
String | getName()
Return the category name. |
Category | getParent()
Returns the parent of this category. |
Level | getPriority() |
ResourceBundle | getResourceBundle()
Return the inherited {@link 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() |
void | info(Object message)
Log a message object with the {@link Level#INFO INFO} Level.
|
void | info(Object message, Throwable t)
Log a message object with the INFO level including
the stack trace of the {@link 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 {@link
Level} passed as parameter.
|
boolean | isInfoEnabled()
Check whether this category is enabled for the info Level.
|
void | l7dlog(Priority priority, String key, Throwable t)
Log a localized message. |
void | l7dlog(Priority priority, String key, Object[] params, Throwable t)
Log a localized and parameterized message. |
void | log(Priority priority, Object message, Throwable t)
This generic form is intended to be used by wrappers. |
void | log(Priority priority, Object message)
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)
Set the level of this Category.
|
void | setResourceBundle(ResourceBundle bundle)
Set the resource bundle to be used with localized logging
methods {@link #l7dlog(Priority,String,Throwable)} and {@link
#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 {@link Level#WARN WARN} Level.
|
void | warn(Object message, Throwable t)
Log a message with the WARN level including the
stack trace of the {@link Throwable} t passed as
parameter.
|
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.level
variable need not be assigned a value in
which case it is inherited form the hierarchy.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.
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.
assertion
parameter is false
, then
logs msg
as an {@link #error(Object) error} statement.
The assert
method has been renamed to
assertLog
because assert
is a language
reserved word in JDK 1.4.
Parameters: assertion msg The message to print if assertion
is
false.
Since: 1.2
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.
This method first checks if this category is DEBUG
enabled by comparing the level of this category with the {@link
Level#DEBUG DEBUG} level. If this category is
DEBUG
enabled, then it converts the message object
(passed as parameter) to a string by invoking the appropriate
{@link org.apache.log4j.or.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 {@link Throwable} to this
method will print the name of the Throwable
but no
stack trace. To print a stack trace use the {@link #debug(Object,
Throwable)} form instead.
Parameters: message the message object to log.
DEBUG
level including
the stack trace of the {@link Throwable} t
passed as
parameter.
See {@link #debug(Object)} form for more detailed information.
Parameters: message the message object to log. t the exception to log, including its stack trace.
This method first checks if this category is ERROR
enabled by comparing the level of this category with {@link
Level#ERROR ERROR} Level. If this category is ERROR
enabled, then it converts the message object passed as parameter
to a string by invoking the appropriate {@link
org.apache.log4j.or.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 {@link Throwable} to this
method will print the name of the Throwable
but no
stack trace. To print a stack trace use the {@link #error(Object,
Throwable)} form instead.
Parameters: message the message object to log
ERROR
level including
the stack trace of the {@link Throwable} t
passed as
parameter.
See {@link #error(Object)} form for more detailed information.
Parameters: message the message object to log. t the exception to log, including its stack trace.
Deprecated: Please use {@link LogManager#exists} 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
This method first checks if this category is FATAL
enabled by comparing the level of this category with {@link
Level#FATAL FATAL} Level. If the category is FATAL
enabled, then it converts the message object passed as parameter
to a string by invoking the appropriate
{@link org.apache.log4j.or.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 {@link Throwable} to this method will print the name of the Throwable but no stack trace. To print a stack trace use the {@link #fatal(Object, Throwable)} form instead.
Parameters: message the message object to log
FATAL
level including
the stack trace of the {@link Throwable} t
passed as
parameter.
See {@link #fatal(Object)} for more detailed information.
Parameters: message the message object to log. t the exception to log, including its stack trace.
Returns: Enumeration An enumeration of the appenders in this category.
name
.
Return the appender with that name if in the list. Return
null
otherwise.
Deprecated: Please use the the {@link #getEffectiveLevel} method instead.
Deprecated: Please use {@link LogManager#getCurrentLoggers()} instead.
Returns all the currently defined categories in the default hierarchy as an {@link java.util.Enumeration Enumeration}.The root category is not included in the returned {@link Enumeration}.
Deprecated: Please use {@link LogManager#getLoggerRepository()} instead.
Return the default Hierarchy instance.Since: 1.0
The Category class is designed so that this method executes as quickly as possible.
Deprecated: Please use {@link #getLoggerRepository} instead.
Return the the {@link Hierarchy} where thisCategory
instance is attached.Since: 1.1
Deprecated: Make sure to use {@link Logger#getLogger(String)} instead.
Deprecated: Please make sure to use {@link Logger#getLogger(Class)} instead.
Returns: Level - the assigned Level, can be null
.
Category
is attached.Since: 1.2
The root category will return null
.
Since: 1.2
Deprecated: Please use {@link #getLevel} instead.
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
key
in
this category's inherited resource bundle. See also {@link
#getResourceBundle}.
If the resource cannot be found, then an {@link #error error} message will be logged complaining about the missing resource.
Deprecated: Please use {@link Logger#getRootLogger()} instead.
This method first checks if this category is INFO
enabled by comparing the level of this category with {@link
Level#INFO INFO} Level. If the category is INFO
enabled, then it converts the message object passed as parameter
to a string by invoking the appropriate
{@link org.apache.log4j.or.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 {@link Throwable} to this method will print the name of the Throwable but no stack trace. To print a stack trace use the {@link #info(Object, Throwable)} form instead.
Parameters: message the message object to log
INFO
level including
the stack trace of the {@link Throwable} t
passed as
parameter.
See {@link #info(Object)} for more detailed information.
Parameters: message the message object to log. t the exception to log, including its stack trace.
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.
Returns: boolean - true
if this category is debug
enabled, false
otherwise.
Returns: boolean True if this category is enabled for level
.
Returns: boolean - true
if this category is enabled
for level info, false
otherwise.
key
is replaced by its localized version from the
resource bundle.Since: 0.8.4
See Also: Category
key
is searched in the resource
bundle. Next, the resulting pattern is formatted using
{@link java.text.MessageFormat#format(String,Object[])} method with the
user supplied object array params
.Since: 0.8.4
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.
This is useful when re-reading configuration information.
Since: 0.8.2
Since: 0.8.2
Since: 0.8.1
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.
Deprecated: Please use {@link #setLevel} instead.
Set the level of this Category.Null values are admitted.
Since: 0.8.4
Deprecated: Please use {@link 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 {@link org.apache.log4j.net.SocketAppender} and {@link 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
This method first checks if this category is WARN
enabled by comparing the level of this category with {@link
Level#WARN WARN} Level. If the category is WARN
enabled, then it converts the message object passed as parameter
to a string by invoking the appropriate
{@link org.apache.log4j.or.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 {@link Throwable} to this method will print the name of the Throwable but no stack trace. To print a stack trace use the {@link #warn(Object, Throwable)} form instead.
Parameters: message the message object to log.
WARN
level including the
stack trace of the {@link Throwable} t
passed as
parameter.
See {@link #warn(Object)} for more detailed information.
Parameters: message the message object to log. t the exception to log, including its stack trace.