/* * Copyright 1999-2005 The Apache Software Foundation. *  * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at *  *      http://www.apache.org/licenses/LICENSE-2.0 *  * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. */// Contibutors: Alex Blewitt <Alex.Blewitt@ioshq.com>//              Markus Oestreicher <oes@zurich.ibm.com>//              Frank Hoering <fhr@zurich.ibm.com>//              Nelson Minar <nelson@media.mit.edu>//              Jim Cakalic <jim_cakalic@na.biomerieux.com>//              Avy Sharell <asharell@club-internet.fr>//              Ciaran Treanor <ciaran@xelector.com>//              Jeff Turner <jeff@socialchange.net.au>//              Michael Horwitz <MHorwitz@siemens.co.za>//              Calvin Chan <calvin.chan@hic.gov.au>//              Aaron Greenhouse <aarong@cs.cmu.edu>//              Beat Meier <bmeier@infovia.com.ar>//              Colin Sampaleanu <colinml1@exis.com>package org.apache.log4j;import org.apache.log4j.spi.AppenderAttachable;import org.apache.log4j.spi.LoggingEvent;import org.apache.log4j.spi.LoggerRepository;import org.apache.log4j.helpers.NullEnumeration;import org.apache.log4j.helpers.AppenderAttachableImpl;import java.util.Enumeration;import java.util.MissingResourceException;import java.util.ResourceBundle;/**  * <font color="#AA2222"><b>This class has been deprecated and  * replaced by the {@link Logger} <em>subclass</em></b></font>. It  * will be kept around to preserve backward compatibility until mid  * 2003.  *   * <p><code>Logger</code> is a subclass of Category, i.e. it extends  * Category. In other words, a logger <em>is</em> 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 <em>never</em> produce Category objects but  * only <code>Logger</code> instances. In order to preserve backward  * compatibility, methods that previously accepted category objects  * still continue to accept category objects.  *   * <p>For example, the following are all legal and will work as  * expected.  *    <pre>    &nbsp;&nbsp;&nbsp;// Deprecated form:    &nbsp;&nbsp;&nbsp;Category cat = Category.getInstance("foo.bar")       &nbsp;&nbsp;&nbsp;// Preferred form for retrieving loggers:    &nbsp;&nbsp;&nbsp;Logger logger = Logger.getLogger("foo.bar")   </pre>     *  <p>The first form is deprecated and should be avoided.  *   *  <p><b>There is absolutely no need for new client code to use or  *  refer to the <code>Category</code> class.</b> Whenever possible,  *  please avoid referring to it or using it.  *   * <p>See the <a href="../../../../manual.html">short manual</a> for an  * introduction on this class.  * <p>  * See the document entitled <a href="http://www.qos.ch/logging/preparingFor13.html">preparing  *  for log4j 1.3</a> for a more detailed discussion.  *  * @author Ceki G&uuml;lc&uuml;  * @author Anders Kristensen   */public class Category implements AppenderAttachable {  /**     The hierarchy where categories are attached to by default.  */  //static  //public  //final Hierarchy defaultHierarchy = new Hierarchy(new  //					   RootCategory(Level.DEBUG));  /**     The name of this category.  */  protected String   name;  /**     The assigned level of this category.  The     <code>level</code> variable need not be assigned a value in     which case it is inherited form the hierarchy.  */  volatile protected Level level;  /**     The parent of this category. All categories have at least one     ancestor which is the root category. */  volatile protected Category parent;  /**     The fully qualified name of the Category class. See also the     getFQCN method. */  private static final String FQCN = Category.class.getName();  protected ResourceBundle resourceBundle;  // Categories need to know what Hierarchy they are in  protected LoggerRepository repository;  AppenderAttachableImpl aai;  /** Additivity is set to true by default, that is children inherit      the appenders of their ancestors by default. If this variable is      set to <code>false</code> 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 <code>false</code> too. See      the user manual for more details. */  protected boolean additive = true;  /**     This constructor created a new <code>Category</code> instance and     sets its name.     <p>It is intended to be used by sub-classes only. You should not     create categories directly.     @param name The name of the category.  */  protected  Category(String name) {    this.name = name;  }  /**     Add <code>newAppender</code> to the list of appenders of this     Category instance.     <p>If <code>newAppender</code> is already in the list of     appenders, then it won't be added again.  */  synchronized  public  void addAppender(Appender newAppender) {    if(aai == null) {      aai = new AppenderAttachableImpl();    }    aai.addAppender(newAppender);    repository.fireAddAppenderEvent(this, newAppender);  }  /**     If <code>assertion</code> parameter is <code>false</code>, then     logs <code>msg</code> as an {@link #error(Object) error} statement.     <p>The <code>assert</code> method has been renamed to     <code>assertLog</code> because <code>assert</code> is a language     reserved word in JDK 1.4.     @param assertion     @param msg The message to print if <code>assertion</code> is     false.     @since 1.2 */  public  void assertLog(boolean assertion, String msg) {    if(!assertion)      this.error(msg);  }  /**     Call the appenders in the hierrachy starting at     <code>this</code>.  If no appenders could be found, emit a     warning.     <p>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.     @param event the event to log.  */  public  void callAppenders(LoggingEvent event) {    int writes = 0;    for(Category c = this; c != null; c=c.parent) {      // Protected against simultaneous call to addAppender, removeAppender,...      synchronized(c) {	if(c.aai != null) {	  writes += c.aai.appendLoopOnAppenders(event);	}	if(!c.additive) {	  break;	}      }    }    if(writes == 0) {      repository.emitNoAppenderWarning(this);    }  }  /**     Close all attached appenders implementing the AppenderAttachable     interface.     @since 1.0  */  synchronized  void closeNestedAppenders() {    Enumeration enumeration = this.getAllAppenders();    if(enumeration != null) {      while(enumeration.hasMoreElements()) {	Appender a = (Appender) enumeration.nextElement();	if(a instanceof AppenderAttachable) {	  a.close();	}      }    }  }  /**    Log a message object with the {@link Level#DEBUG DEBUG} level.    <p>This method first checks if this category is <code>DEBUG</code>    enabled by comparing the level of this category with the {@link    Level#DEBUG DEBUG} level. If this category is    <code>DEBUG</code> 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.    <p><b>WARNING</b> Note that passing a {@link Throwable} to this    method will print the name of the <code>Throwable</code> but no    stack trace. To print a stack trace use the {@link #debug(Object,    Throwable)} form instead.    @param message the message object to log. */  public  void debug(Object message) {    if(repository.isDisabled(Level.DEBUG_INT))      return;    if(Level.DEBUG.isGreaterOrEqual(this.getEffectiveLevel())) {      forcedLog(FQCN, Level.DEBUG, message, null);    }  }  /**   Log a message object with the <code>DEBUG</code> level including   the stack trace of the {@link Throwable} <code>t</code> passed as   parameter.   <p>See {@link #debug(Object)} form for more detailed information.   @param message the message object to log.   @param t the exception to log, including its stack trace.  */  public  void debug(Object message, Throwable t) {    if(repository.isDisabled(Level.DEBUG_INT))      return;    if(Level.DEBUG.isGreaterOrEqual(this.getEffectiveLevel()))      forcedLog(FQCN, Level.DEBUG, message, t);  }  /**    Log a message object with the {@link Level#ERROR ERROR} Level.    <p>This method first checks if this category is <code>ERROR</code>    enabled by comparing the level of this category with {@link    Level#ERROR ERROR} Level. If this category is <code>ERROR</code>    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.    <p><b>WARNING</b> Note that passing a {@link Throwable} to this    method will print the name of the <code>Throwable</code> but no    stack trace. To print a stack trace use the {@link #error(Object,    Throwable)} form instead.    @param message the message object to log */  public  void error(Object message) {    if(repository.isDisabled(Level.ERROR_INT))      return;    if(Level.ERROR.isGreaterOrEqual(this.getEffectiveLevel()))      forcedLog(FQCN, Level.ERROR, message, null);  }  /**   Log a message object with the <code>ERROR</code> level including   the stack trace of the {@link Throwable} <code>t</code> passed as   parameter.   <p>See {@link #error(Object)} form for more detailed information.   @param message the message object to log.   @param t the exception to log, including its stack trace.  */  public  void error(Object message, Throwable t) {    if(repository.isDisabled(Level.ERROR_INT))      return;    if(Level.ERROR.isGreaterOrEqual(this.getEffectiveLevel()))      forcedLog(FQCN, Level.ERROR, message, t);  }  /**     If the named category exists (in the default hierarchy) then it     returns a reference to the category, otherwise it returns     <code>null</code>.     @deprecated Please use {@link LogManager#exists} instead.     @since 0.8.5 */  public  static  Logger exists(String name) {    return LogManager.exists(name);  }  /**    Log a message object with the {@link Level#FATAL FATAL} Level.    <p>This method first checks if this category is <code>FATAL</code>    enabled by comparing the level of this category with {@link    Level#FATAL FATAL} Level. If the category is <code>FATAL</code>    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.    <p><b>WARNING</b> 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.    @param message the message object to log */  public  void fatal(Object message) {    if(repository.isDisabled(Level.FATAL_INT))      return;    if(Level.FATAL.isGreaterOrEqual(this.getEffectiveLevel()))      forcedLog(FQCN, Level.FATAL, message, null);  }  /**   Log a message object with the <code>FATAL</code> level including   the stack trace of the {@link Throwable} <code>t</code> passed as   parameter.   <p>See {@link #fatal(Object)} for more detailed information.   @param message the message object to log.   @param t the exception to log, including its stack trace.  */  public  void fatal(Object message, Throwable t) {    if(repository.isDisabled(Level.FATAL_INT))      return;    if(Level.FATAL.isGreaterOrEqual(this.getEffectiveLevel()))      forcedLog(FQCN, Level.FATAL, message, t);  }  /**     This method creates a new logging event and logs the event     without further checks.  */  protected  void forcedLog(String fqcn, Priority level, Object message, Throwable t) {    callAppenders(new LoggingEvent(fqcn, this, level, message, t));  }  /**     Get the additivity flag for this Category instance.  */  public  boolean getAdditivity() {    return additive;  }  /**     Get the appenders contained in this category as an {@link     Enumeration}. If no appenders can be found, then a {@link NullEnumeration}     is returned.     @return Enumeration An enumeration of the appenders in this category.  */  synchronized  public  Enumeration getAllAppenders() {    if(aai == null)      return NullEnumeration.getInstance();    else      return aai.getAllAppenders();  }  /**     Look for the appender named as <code>name</code>.     <p>Return the appender with that name if in the list. Return     <code>null</code> otherwise.  */  synchronized  public  Appender getAppender(String name) {     if(aai == null || name == null)      return null;     return aai.getAppender(name);  }  /**     Starting from this category, search the category hierarchy for a     non-null level and return it. Otherwise, return the level of the     root category.     <p>The Category class is designed so that this method executes as     quickly as possible.   */  public  Level getEffectiveLevel() {    for(Category c = this; c != null; c=c.parent) {      if(c.level != null)	return c.level;    }    return null; // If reached will cause an NullPointerException.  }  /**    *    * @deprecated Please use the the {@link #getEffectiveLevel} method    * instead.      * */  public  Priority getChainedPriority() {    for(Category c = this; c != null; c=c.parent) {      if(c.level != null)	return c.level;    }    return null; // If reached will cause an NullPointerException.  }  /**     Returns all the currently defined categories in the default     hierarchy as an {@link java.util.Enumeration Enumeration}.     <p>The root category is <em>not</em> included in the returned     {@link Enumeration}.     @deprecated Please use {@link LogManager#getCurrentLoggers()} instead.  */  public  static  Enumeration getCurrentCategories() {    return LogManager.getCurrentLoggers();  }  /**     Return the default Hierarchy instance.     @deprecated Please use {@link LogManager#getLoggerRepository()} instead.     @since 1.0   */  public  static  LoggerRepository getDefaultHierarchy() {    return LogManager.getLoggerRepository();  }  /**     Return the the {@link Hierarchy} where this <code>Category</code>     instance is attached.     @deprecated Please use {@link #getLoggerRepository} instead.     @since 1.1 */  public  LoggerRepository  getHierarchy() {    return repository;  }  /**     Return the the {@link LoggerRepository} where this     <code>Category</code> is attached.     @since 1.2 */  public  LoggerRepository  getLoggerRepository() {    return repository;  } /**  * @deprecated Make sure to use {@link Logger#getLogger(String)} instead.