org.apache.log4j
Class Category

java.lang.Object
  extended by org.apache.log4j.Category
Direct Known Subclasses:
Logger

public abstract class Category
extends java.lang.Object

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  PaxLogger m_delegate
           
 
Constructor Summary
Category(PaxLogger delegate)
           
 
Method Summary
 void assertLog(boolean assertion, java.lang.String msg)
          If assertion parameter is false, then logs msg as an error statement.
 void debug(java.lang.Object message)
          Log a message object with the DEBUG level.
 void debug(java.lang.Object message, java.lang.Throwable t)
          Log a message object with the DEBUG level including the stack trace of the Throwablet passed as parameter.
 void error(java.lang.Object message)
          Log a message object with the ERROR Level.
 void error(java.lang.Object message, java.lang.Throwable t)
          Log a message object with the ERROR level including the stack trace of the Throwablet passed as parameter.
 void fatal(java.lang.Object message)
          Log a message object with the FATAL Level.
 void fatal(java.lang.Object message, java.lang.Throwable t)
          Log a message object with the FATAL level including the stack trace of the Throwablet passed as parameter.
static Category getInstance(java.lang.Class clazz)
          Deprecated. Please make sure to use Logger.getLogger(Class) instead.
static Category getInstance(java.lang.String name)
          Deprecated. Make sure to use Logger.getLogger(String) instead.
 java.lang.String getName()
          Return the category name.
 void info(java.lang.Object message)
          Log a message object with the INFO Level.
 void info(java.lang.Object message, java.lang.Throwable t)
          Log a message object with the INFO level including the stack trace of the Throwablet passed as parameter.
 boolean isDebugEnabled()
          Check whether this category is enabled for the DEBUG Level.
 boolean isEnabledFor(Priority priority)
          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 log(Priority priority, java.lang.Object msg)
          Log a message with the code level priority.
 void log(Priority priority, java.lang.Object message, java.lang.Throwable t)
          This generic form is intended to be used by wrappers.
 void log(java.lang.String callerFQCN, Priority level, java.lang.Object message, java.lang.Throwable t)
          This is the most generic printing method.
static void shutdown()
          Deprecated.  
protected abstract  void trace(java.lang.Object message, java.lang.Throwable t)
           
 void warn(java.lang.Object message)
          Log a message object with the WARN Level.
 void warn(java.lang.Object message, java.lang.Throwable t)
          Log a message with the WARN level including the stack trace of the Throwablet passed as parameter.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

m_delegate

protected PaxLogger m_delegate
Constructor Detail

Category

public Category(PaxLogger delegate)
Method Detail

assertLog

public void assertLog(boolean assertion,
                      java.lang.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 - if false, log the message.
msg - The message to print if assertion is false.
Since:
1.2

debug

public void debug(java.lang.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 the DEBUG level. If this category is DEBUG enabled, then it converts the message object (passed as parameter) to a string by invoking the appropriate 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 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.

Parameters:
message - the message object to log.

debug

public void debug(java.lang.Object message,
                  java.lang.Throwable t)
Log a message object with the DEBUG level including the stack trace of the Throwablet 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(java.lang.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 with ERROR Level. If this category is ERROR enabled, then it converts the message object passed as parameter to a string by invoking the appropriate 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 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.

Parameters:
message - the message object to log

error

public void error(java.lang.Object message,
                  java.lang.Throwable t)
Log a message object with the ERROR level including the stack trace of the Throwablet 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.

fatal

public void fatal(java.lang.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 with FATAL Level. If the category is FATAL enabled, then it converts the message object passed as parameter to a string by invoking the appropriate 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 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.

Parameters:
message - the message object to log

fatal

public void fatal(java.lang.Object message,
                  java.lang.Throwable t)
Log a message object with the FATAL level including the stack trace of the Throwablet 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.

getInstance

public static Category getInstance(java.lang.String name)
Deprecated. Make sure to use Logger.getLogger(String) instead.

Parameters:
name - of the Logger/Category to return.
Returns:
a Logger of the requested name.

getInstance

public static Category getInstance(java.lang.Class clazz)
Deprecated. Please make sure to use Logger.getLogger(Class) instead.

Parameters:
clazz - name of the Logger/Category to return.
Returns:
a Logger of the requested name.

getName

public final java.lang.String getName()
Return the category name.

Returns:
the name of this logger/category.

info

public void info(java.lang.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 with INFO Level. If the category is INFO enabled, then it converts the message object passed as parameter to a string by invoking the appropriate 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 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.

Parameters:
message - the message object to log

info

public void info(java.lang.Object message,
                 java.lang.Throwable t)
Log a message object with the INFO level including the stack trace of the Throwablet 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.

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.

Returns:
boolean - true if this category is debug enabled, false otherwise.

isEnabledFor

public boolean isEnabledFor(Priority priority)
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().

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

log

public void log(Priority priority,
                java.lang.Object msg)
Log a message with the code level priority.

Parameters:
priority, - the code level of the message
msg - the message object to log.

log

public void log(Priority priority,
                java.lang.Object message,
                java.lang.Throwable t)
This generic form is intended to be used by wrappers.

Parameters:
priority - priority of log to be generated.
message - the message to log
t - an Exception to be logged, if any.

trace

protected abstract void trace(java.lang.Object message,
                              java.lang.Throwable t)

log

public void log(java.lang.String callerFQCN,
                Priority level,
                java.lang.Object message,
                java.lang.Throwable t)
This is the most generic printing method. It is intended to be invoked by wrapper classes. Note:In Pax Logging the callerFQCN is ignored.

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.

shutdown

public static void shutdown()
Deprecated. 

Does nothing.

Since:
1.0

warn

public void warn(java.lang.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 with WARN Level. If the category is WARN enabled, then it converts the message object passed as parameter to a string by invoking the appropriate 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 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.

Parameters:
message - the message object to log.

warn

public void warn(java.lang.Object message,
                 java.lang.Throwable t)
Log a message with the WARN level including the stack trace of the Throwablet 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.


Copyright © 2006-2011 OPS4J - Open Participation Software for Java. All Rights Reserved.