Package org.apache.log4j

Class Category

  • All Implemented Interfaces:
    org.apache.log4j.spi.AppenderAttachable, PaxLoggingManagerAwareLogger
    Direct Known Subclasses:
    Logger
    public abstract class Category
extends Object
implements org.apache.log4j.spi.AppenderAttachable, PaxLoggingManagerAwareLogger
    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 Detail

      • LOG4J_FQCN

        protected static final String LOG4J_FQCN

      • name

        protected String name
        The name of this category.

      • level

        protected volatile org.apache.log4j.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.

      • repository

        protected org.apache.log4j.spi.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

      • configurePaxLoggingManager

        public static void configurePaxLoggingManager​(PaxLoggingManager manager)
        Static method is different than usual, because here logger is also a factory.
        Parameters:
        manager -

      • addAppender

        public void addAppender​(org.apache.log4j.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 org.apache.log4j.spi.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​(org.apache.log4j.spi.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 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 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​(Object message,
                  Throwable t)
        Log a message object with the DEBUG level including the stack trace of the Throwable 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.

      • debug

        public void debug​(Object messagePattern,
                  Object arg)
        Log a message with the DEBUG level with message formatting done according to the value of messagePattern and arg parameters.

        This form avoids superflous parameter construction. Whenever possible, you should use this form instead of constructing the message parameter using string concatenation.

        Parameters:
        messagePattern - The message pattern which will be parsed and formatted
        arg - The argument to replace the formatting element, i,e, the '{}' pair within messagePattern.
        Since:
        1.3

      • debug

        public void debug​(String messagePattern,
                  Object arg1,
                  Object arg2)
        Log a message with the DEBUG level with message formatting done according to the messagePattern and the arguments arg1 and arg2.

        This form avoids superflous parameter construction. Whenever possible, you should use this form instead of constructing the message parameter using string concatenation.

        Parameters:
        messagePattern - The message pattern which will be parsed and formatted
        arg1 - The first argument to replace the first formatting element
        arg2 - The second argument to replace the second formatting element
        Since:
        1.3

      • trace

        public void trace​(Object message,
                  Throwable t)
        Log a message object with the TRACE 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.
        Since:
        1.2.12

      • trace

        public void trace​(Object messagePattern,
                  Object arg)
        Log a message with the TRACE level with message formatting done according to the value of messagePattern and arg parameters.

        This form avoids superflous parameter construction. Whenever possible, you should use this form instead of constructing the message parameter using string concatenation.

        Parameters:
        messagePattern - The message pattern which will be parsed and formatted
        arg - The argument to replace the formatting element, i,e, the '{}' pair within messagePattern.
        Since:
        1.3

      • trace

        public void trace​(String messagePattern,
                  Object arg1,
                  Object arg2)
        Log a message with the TRACE level with message formatting done according to the messagePattern and the arguments arg1 and arg2.

        This form avoids superflous parameter construction. Whenever possible, you should use this form instead of constructing the message parameter using string concatenation.

        Parameters:
        messagePattern - The message pattern which will be parsed and formatted
        arg1 - The first argument to replace the first formatting element
        arg2 - The second argument to replace the second formatting element
        Since:
        1.3

      • isErrorEnabled

        public boolean isErrorEnabled()
        Check whether this category is enabled for the ERROR Level. See also isDebugEnabled().
        Returns:
        boolean - true if this category is enabled for level ERROR, false otherwise.

      • 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 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 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​(Object message,
                  Throwable t)
        Log a message object with the ERROR level including the stack trace of the Throwable 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.

      • error

        public void error​(Object messagePattern,
                  Object arg)
        Log a message with the ERROR level with message formatting done according to the value of messagePattern and arg parameters.

        This form avoids superflous parameter construction. Whenever possible, you should use this form instead of constructing the message parameter using string concatenation.

        Parameters:
        messagePattern - The message pattern which will be parsed and formatted
        arg - The argument to replace the formatting element, i,e, the '{}' pair within messagePattern.
        Since:
        1.3

      • error

        public void error​(String messagePattern,
                  Object arg1,
                  Object arg2)
        Log a message with the ERROR level with message formatting done according to the messagePattern and the arguments arg1 and arg2.

        This form avoids superflous parameter construction. Whenever possible, you should use this form instead of constructing the message parameter using string concatenation.

        Parameters:
        messagePattern - The message pattern which will be parsed and formatted
        arg1 - The first argument to replace the first formatting element
        arg2 - The second argument to replace the second formatting element
        Since:
        1.3

      • 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 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 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​(Object messagePattern,
                  Object arg)
        Log a message with the FATAL level with message formatting done according to the value of messagePattern and arg parameters.

        This form avoids superflous parameter construction. Whenever possible, you should use this form instead of constructing the message parameter using string concatenation.

        Parameters:
        messagePattern - The message pattern which will be parsed and formatted
        arg - The argument to replace the formatting element, i,e, the '{}' pair within messagePattern.
        Since:
        1.3

      • fatal

        public void fatal​(String messagePattern,
                  Object arg1,
                  Object arg2)
        Log a message with the FATAL level with message formatting done according to the messagePattern and the arguments arg1 and arg2.

        This form avoids superflous parameter construction. Whenever possible, you should use this form instead of constructing the message parameter using string concatenation.

        Parameters:
        messagePattern - The message pattern which will be parsed and formatted
        arg1 - The first argument to replace the first formatting element
        arg2 - The second argument to replace the second formatting element
        Since:
        1.3

      • fatal

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

        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 a NullEnumeration is returned.
        Specified by:
        getAllAppenders in interface org.apache.log4j.spi.AppenderAttachable
        Returns:
        Enumeration An enumeration of the appenders in this category.

      • getAppender

        public org.apache.log4j.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 org.apache.log4j.spi.AppenderAttachable

      • getEffectiveLevel

        public org.apache.log4j.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.

      • getDefaultHierarchy

        public static org.apache.log4j.spi.LoggerRepository getDefaultHierarchy()
        Deprecated.
        Please use LogManager.getLoggerRepository() instead.
        Return the default Hierarchy instance.
        Since:
        1.0

      • getHierarchy

        public org.apache.log4j.spi.LoggerRepository getHierarchy()
        Deprecated.
        Please use getLoggerRepository() instead.
        Return the the Hierarchy where this Category instance is attached.
        Since:
        1.1

      • getLoggerRepository

        public org.apache.log4j.spi.LoggerRepository getLoggerRepository()
        Return the the LoggerRepository where this Category is attached.
        Since:
        1.2

      • 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 org.apache.log4j.Level getLevel()
        Returns the assigned Level, if any, for this Category.
        Returns:
        Level - the assigned Level, can be null.

      • getPriority

        public final org.apache.log4j.Level getPriority()
        Deprecated.
        Please use getLevel() 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​(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 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​(Object messagePattern,
                 Object arg)
        Log a message with the INFO level with message formatting done according to the value of messagePattern and arg parameters.

        This form avoids superflous parameter construction. Whenever possible, you should use this form instead of constructing the message parameter using string concatenation.

        Parameters:
        messagePattern - The message pattern which will be parsed and formatted
        arg - The argument to replace the formatting element, i,e, the '{}' pair within messagePattern.
        Since:
        1.3

      • info

        public void info​(String messagePattern,
                 Object arg1,
                 Object arg2)
        Log a message with the INFO level with message formatting done according to the messagePattern and the arguments arg1 and arg2.

        This form avoids superflous parameter construction. Whenever possible, you should use this form instead of constructing the message parameter using string concatenation.

        Parameters:
        messagePattern - The message pattern which will be parsed and formatted
        arg1 - The first argument to replace the first formatting element
        arg2 - The second argument to replace the second formatting element
        Since:
        1.3

      • info

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

        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​(org.apache.log4j.Appender appender)
        Is the appender passed as parameter attached to this category?
        Specified by:
        isAttached in interface org.apache.log4j.spi.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.

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

      • isTraceEnabled

        public boolean isTraceEnabled()
        Check whether this category is enabled for the TRACE Level. See also isDebugEnabled().
        Returns:
        boolean - true if this category is enabled for level TRACE, 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().
        Returns:
        boolean - true if this category is enabled for level info, false otherwise.

      • 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,
                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 interface org.apache.log4j.spi.AppenderAttachable

      • removeAppender

        public void removeAppender​(org.apache.log4j.Appender appender)
        Remove the appender passed as parameter form the list of appenders.
        Specified by:
        removeAppender in interface org.apache.log4j.spi.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 org.apache.log4j.spi.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​(org.apache.log4j.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.

      • 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

      • isWarnEnabled

        public boolean isWarnEnabled()
        Check whether this category is enabled for the WARN Level. See also isDebugEnabled().
        Returns:
        boolean - true if this category is enabled for level WARN, false otherwise.

      • 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 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 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​(Object message,
                 Throwable t)
        Log a message with the WARN level including the stack trace of the Throwable 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.

      • warn

        public void warn​(Object messagePattern,
                 Object arg)
        Log a message with the WARN level with message formatting done according to the value of messagePattern and arg parameters.

        This form avoids superflous parameter construction. Whenever possible, you should use this form instead of constructing the message parameter using string concatenation.

        Parameters:
        messagePattern - The message pattern which will be parsed and formatted
        arg - The argument to replace the formatting element, i,e, the '{}' pair within messagePattern.
        Since:
        1.3

      • warn

        public void warn​(String messagePattern,
                 Object arg1,
                 Object arg2)
        Log a message with the WARN level with message formatting done according to the messagePattern and the arguments arg1 and arg2.

        This form avoids superflous parameter construction. Whenever possible, you should use this form instead of constructing the message parameter using string concatenation.

        Parameters:
        messagePattern - The message pattern which will be parsed and formatted
        arg1 - The first argument to replace the first formatting element
        arg2 - The second argument to replace the second formatting element
        Since:
        1.3