org.apache.log4j
Class Category

java.lang.Object
  org.slf4j.impl.MarkerIgnoringBase
      org.apache.log4j.Category

All Implemented Interfaces:

AppenderAttachable, Logger

Direct Known Subclasses:

Logger

public class Category
extends MarkerIgnoringBase
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) Deprecated. Please use debug(String) method instead.
void	debug(String message) Log a message string at the DEBUG level.
void	debug(String format, Object arg) Log a message at the DEBUG level with message formatting done according to the value of format and the arg parameters.
void	debug(String format, Object[] argArray) Log a message at the DEBUG level according to the specified format and arguments.
void	debug(String format, Object arg1, Object arg2) Log a message at the DEBUG level according to the specified format and arguments.
void	debug(String message, Throwable t) Log an exception (throwable) at the DEBUG level with an accompanying message.
void	error(Object message) Deprecated. Please use error(String) method instead.
void	error(String message) Log a message string at the ERROR level.
void	error(String format, Object arg) Log a message at the ERROR level with message formatting done according to the value of format and the arg parameters.
void	error(String format, Object[] argArray) Log a message at the ERROR level according to the specified format and arguments.
void	error(String format, Object arg1, Object arg2) Log a message at the ERROR level according to the specified format and arguments.
void	error(String message, Throwable t) Log an exception (throwable) at the ERROR level with an accompanying message.
static Logger	exists(String name) Deprecated. Please use LogManager.exists(java.lang.String) instead.
void	fatal(Object message) Deprecated. Please use fatal(String) method instead.
void	fatal(String message) Log a message string at the FATAL level.
void	fatal(String message, Throwable t) Log an exception (throwable) at the FATAL level with an accompanying message.
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) Deprecated. Please use info(String) method instead.
void	info(String message) Log a message object with the INFO Level.
void	info(String format, Object arg) Log a message at the INFO level with message formatting done according to the value of format and the arg parameters.
void	info(String format, Object[] argArray) Log a message at the INFO level according to the specified format and arguments.
void	info(String format, Object arg1, Object arg2) Log a message at the INFO level according to the specified format and arguments.
void	info(String message, Throwable t) Log an exception (throwable) at the INFO level with an accompanying message.
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	isErrorEnabled() Check whether this category is enabled for the info Level.
boolean	isInfoEnabled() Check whether this category is enabled for the info Level.
boolean	isWarnEnabled() 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, Throwable t) This generic form is intended to be used by wrappers.
void	log(Priority priority, String 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) 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) Deprecated. Please use warn(String) method instead.
void	warn(String message) Log a message object with the WARN Level.
void	warn(String format, Object arg) Log a message at the WARN level with message formatting done according to the value of format and the arg parameters.
void	warn(String format, Object[] argArray) Log a message at the WARN level according to the specified format and arguments.
void	warn(String format, Object arg1, Object arg2) Log a message at the WARN level according to the specified format and arguments.
void	warn(String message, Throwable t) Log an exception (throwable) at the WARN level with an accompanying message.

Methods inherited from class org.slf4j.impl.MarkerIgnoringBase

debug, debug, debug, debug, debug, error, error, error, error, error, info, info, info, info, info, isDebugEnabled, isErrorEnabled, isInfoEnabled, isWarnEnabled, warn, warn, warn, warn, warn

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 to false 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 interface AppenderAttachable

assertLog

public void assertLog(boolean assertion,
                      String msg)

If 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.

Parameters:

assertion -

msg - The message to print if assertion 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(String message)

Log a message string at the DEBUG level.

Specified by:

debug in interface Logger

Parameters:

message - the message string to log.

debug

public void debug(Object message)

Deprecated. Please use debug(String) method instead.

debug

public void debug(String format,
                  Object arg)

Log a message at the DEBUG level with message formatting done according to the value of format and the arg parameters.

This form avoids superflous parameter construction.

Specified by:

debug in interface Logger

Parameters:

format - the format

arg - the argument for substitution

debug

public void debug(String format,
                  Object arg1,
                  Object arg2)

Log a message at the DEBUG level according to the specified format and arguments.

This form avoids superflous object creations.

Specified by:

debug in interface Logger

Parameters:

format - the format

arg1 - the first argument

arg2 - the second argument

debug

public void debug(String format,
                  Object[] argArray)

Log a message at the DEBUG level according to the specified format and arguments.

This form avoids superflous object creations.

Specified by:

debug in interface Logger

Parameters:

format - the format

argArray - an array of arguments

debug

public void debug(String message,
                  Throwable t)

Log an exception (throwable) at the DEBUG level with an accompanying message.

Specified by:

debug in interface Logger

Parameters:

message - the message accompanying the exception

t - the exception (throwable) to log, including its stack trace.

error

public void error(String message)

Log a message string at the ERROR level.

Specified by:

error in interface Logger

Parameters:

message - the message string to log.

error

public void error(Object message)

Deprecated. Please use error(String) method instead.

error

public void error(String format,
                  Object arg)

Log a message at the ERROR level with message formatting done according to the value of format and the arg parameters.

This form avoids superflous parameter construction.

Specified by:

error in interface Logger

Parameters:

format - the format

arg - the argument for substitution

error

public void error(String format,
                  Object arg1,
                  Object arg2)

Log a message at the ERROR level according to the specified format and arguments.

This form avoids superflous object creations.

Specified by:

error in interface Logger

Parameters:

format - the format

arg1 - the first argument

arg2 - the second argument

error

public void error(String format,
                  Object[] argArray)

Log a message at the ERROR level according to the specified format and arguments.

This form avoids superflous object creations.

Specified by:

error in interface Logger

Parameters:

format - the format

argArray - an array of arguments

error

public void error(String message,
                  Throwable t)

Log an exception (throwable) at the ERROR level with an accompanying message.

Specified by:

error in interface Logger

Parameters:

message - the message accompanying the exception

t - the exception (throwable) 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(String message)

Log a message string at the FATAL level.

Parameters:

message - the message string to log.

fatal

public void fatal(Object message)

Deprecated. Please use fatal(String) method instead.

fatal

public void fatal(String message,
                  Throwable t)

Log an exception (throwable) at the FATAL level with an accompanying message.

Parameters:

message - the message accompanying the exception

t - the exception (throwable) 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 a NullEnumeration is returned.

Specified by:

getAllAppenders in interface AppenderAttachable

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 interface AppenderAttachable

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 this Category instance is attached.

Since:

1.1

getLoggerRepository

public LoggerRepository getLoggerRepository()

Return the the LoggerRepository where this Category 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.

Specified by:

getName in interface Logger

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 also getResourceBundle().

If the resource cannot be found, then an error message will be logged complaining about the missing resource.

info

public void info(String message)

Log a message object with the INFO Level.

Specified by:

info in interface Logger

Parameters:

message - the message object to log

info

public void info(Object message)

Deprecated. Please use info(String) method instead.

info

public void info(String format,
                 Object arg)

Log a message at the INFO level with message formatting done according to the value of format and the arg parameters.

This form avoids superflous parameter construction.

Specified by:

info in interface Logger

Parameters:

format - the format

arg - the argument for substitution

info

public void info(String format,
                 Object arg1,
                 Object arg2)

Log a message at the INFO level according to the specified format and arguments.

This form avoids superflous object creations.

Specified by:

info in interface Logger

Parameters:

format - the format

arg1 - the first argument

arg2 - the second argument

info

public void info(String format,
                 Object[] argArray)

Log a message at the INFO level according to the specified format and arguments.

This form avoids superflous object creations.

Specified by:

info in interface Logger

Parameters:

format - the format

argArray - an array of arguments

info

public void info(String message,
                 Throwable t)

Log an exception (throwable) at the INFO level with an accompanying message.

Specified by:

info in interface Logger

Parameters:

message - the message accompanying the exception

t - the exception (throwable) 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 interface AppenderAttachable

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 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.

Specified by:

isDebugEnabled in interface Logger

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 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 also isDebugEnabled().

Specified by:

isInfoEnabled in interface Logger

Returns:

boolean - true if this category is enabled for level info, false otherwise.

isWarnEnabled

public boolean isWarnEnabled()

Check whether this category is enabled for the info Level. See also isDebugEnabled().

Specified by:

isWarnEnabled in interface Logger

Returns:

boolean - true if this category is enabled for level WARN, false otherwise.

Since:

1.2.10

isErrorEnabled

public boolean isErrorEnabled()

Check whether this category is enabled for the info Level. See also isDebugEnabled().

Specified by:

isErrorEnabled in interface Logger

Returns:

boolean - true if this category is enabled for level ERROR, false otherwise.

Since:

1.2.10

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 using MessageFormat.format(String,Object[]) method with the user supplied object array params.

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,
                String 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 interface AppenderAttachable

removeAppender

public void removeAppender(Appender appender)

Remove the appender passed as parameter form the list of appenders.

Specified by:

removeAppender in interface AppenderAttachable

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 interface AppenderAttachable

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) and l7dlog(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 and 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

warn

public void warn(String message)

Log a message object with the WARN Level.

Specified by:

warn in interface Logger

Parameters:

message - the message object to log

warn

public void warn(Object message)

Deprecated. Please use warn(String) method instead.

warn

public void warn(String format,
                 Object arg)

Log a message at the WARN level with message formatting done according to the value of format and the arg parameters.

This form avoids superflous parameter construction.

Specified by:

warn in interface Logger

Parameters:

format - the format

arg - the argument for substitution

warn

public void warn(String format,
                 Object arg1,
                 Object arg2)

Log a message at the WARN level according to the specified format and arguments.

This form avoids superflous object creations.

Specified by:

warn in interface Logger

Parameters:

format - the format

arg1 - the first argument

arg2 - the second argument

warn

public void warn(String format,
                 Object[] argArray)

Log a message at the WARN level according to the specified format and arguments.

This form avoids superflous object creations.

Specified by:

warn in interface Logger

Parameters:

format - the format

argArray - an array of arguments

warn

public void warn(String message,
                 Throwable t)

Log an exception (throwable) at the WARN level with an accompanying message.

Specified by:

warn in interface Logger

Parameters:

message - the message accompanying the exception

t - the exception (throwable) to log, including its stack trace.