1  /*
  2   * Copyright 1999-2005 The Apache Software Foundation.
  3   * 
  4   * Licensed under the Apache License, Version 2.0 (the "License");
  5   * you may not use this file except in compliance with the License.
  6   * You may obtain a copy of the License at
  7   * 
  8   *      http://www.apache.org/licenses/LICENSE-2.0
  9   * 
 10   * Unless required by applicable law or agreed to in writing, software
 11   * distributed under the License is distributed on an "AS IS" BASIS,
 12   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 13   * See the License for the specific language governing permissions and
 14   * limitations under the License.
 15   */
 16  
 17  package org.apache.log4j;
 18  
 19  import org.apache.log4j.spi.LoggerFactory;
 20  import org.apache.log4j.Level;
 21  
 22  
 23  /**
 24    This is the central class in the log4j package. Most logging
 25    operations, except configuration, are done through this class.
 26  
 27    @since log4j 1.2
 28  
 29    @author Ceki Gülcü */
 30  public class Logger extends Category {
 31  
 32    /**
 33       The fully qualified name of the Logger class. See also the
 34       getFQCN method. */
 35    private static final String FQCN = Logger.class.getName();
 36  
 37  
 38    protected
 39    Logger(String name) {
 40      super(name);
 41    }
 42  
 43    /**
 44      Log a message object with the {@link Level#FINE FINE} level which
 45      is just an alias for the {@link Level#DEBUG DEBUG} level.
 46  
 47      <p>This method first checks if this category is <code>DEBUG</code>
 48      enabled by comparing the level of this category with the {@link
 49      Level#DEBUG DEBUG} level. If this category is
 50      <code>DEBUG</code> enabled, then it converts the message object
 51      (passed as parameter) to a string by invoking the appropriate
 52      {@link org.apache.log4j.or.ObjectRenderer}. It then proceeds to call all the
 53      registered appenders in this category and also higher in the
 54      hierarchy depending on the value of the additivity flag.
 55  
 56      <p><b>WARNING</b> Note that passing a {@link Throwable} to this
 57      method will print the name of the <code>Throwable</code> but no
 58      stack trace. To print a stack trace use the {@link #debug(Object,
 59      Throwable)} form instead.
 60  
 61      @param message the message object to log. */
 62    //public
 63    //void fine(Object message) {
 64    //  if(repository.isDisabled(Level.DEBUG_INT))
 65    //	return;
 66    //  if(Level.DEBUG.isGreaterOrEqual(this.getChainedLevel())) {
 67    //	forcedLog(FQCN, Level.DEBUG, message, null);
 68    //  }
 69    //}
 70  
 71  
 72    /**
 73     Log a message object with the <code>FINE</code> level including
 74     the stack trace of the {@link Throwable} <code>t</code> passed as
 75     parameter.
 76  
 77     <p>See {@link #fine(Object)} form for more detailed information.
 78  
 79     @param message the message object to log.
 80     @param t the exception to log, including its stack trace.  */
 81    //public
 82    //void fine(Object message, Throwable t) {
 83    //  if(repository.isDisabled(Level.DEBUG_INT))
 84    //	return;
 85    //  if(Level.DEBUG.isGreaterOrEqual(this.getChainedLevel()))
 86    //	forcedLog(FQCN, Level.FINE, message, t);
 87    //}
 88  
 89    /**
 90     * Retrieve a logger named according to the value of the
 91     * <code>name</code> parameter. If the named logger already exists,
 92     * then the existing instance will be returned. Otherwise, a new
 93     * instance is created.  
 94     *
 95     * <p>By default, loggers do not have a set level but inherit it
 96     * from their neareast ancestor with a set level. This is one of the
 97     * central features of log4j.
 98     *
 99     * @param name The name of the logger to retrieve.  
100    */
101    static
102    public
103    Logger getLogger(String name) {
104      return LogManager.getLogger(name);
105    }
106  
107    /**
108     * Shorthand for <code>getLogger(clazz.getName())</code>.
109     *
110     * @param clazz The name of <code>clazz</code> will be used as the
111     * name of the logger to retrieve.  See {@link #getLogger(String)}
112     * for more detailed information.
113     */
114    static
115    public
116    Logger getLogger(Class clazz) {
117      return LogManager.getLogger(clazz.getName());
118    }
119  
120  
121    /**
122     * Return the root logger for the current logger repository.
123     * <p>
124     * The {@link #getName Logger.getName()} method for the root logger always returns
125     * stirng value: "root". However, calling
126     * <code>Logger.getLogger("root")</code> does not retrieve the root
127     * logger but a logger just under root named "root".
128     * <p>
129     * In other words, calling this method is the only way to retrieve the 
130     * root logger.
131     */
132    public
133    static
134    Logger getRootLogger() {
135      return LogManager.getRootLogger();
136    }
137  
138    /**
139       Like {@link #getLogger(String)} except that the type of logger
140       instantiated depends on the type returned by the {@link
141       LoggerFactory#makeNewLoggerInstance} method of the
142       <code>factory</code> parameter.
143  
144       <p>This method is intended to be used by sub-classes.
145  
146       @param name The name of the logger to retrieve.
147  
148       @param factory A {@link LoggerFactory} implementation that will
149       actually create a new Instance.
150  
151       @since 0.8.5 */
152    public
153    static
154    Logger getLogger(String name, LoggerFactory factory) {
155      return LogManager.getLogger(name, factory);
156    }
157  
158      /**
159       * Log a message object with the {@link org.apache.log4j.Level#TRACE TRACE} level.
160       *
161       * @param message the message object to log.
162       * @see #debug(Object) for an explanation of the logic applied.
163       * @since 1.2.12
164       */
165      public void trace(Object message) {
166        if (repository.isDisabled(Level.TRACE_INT)) {
167          return;
168        }
169  
170        if (Level.TRACE.isGreaterOrEqual(this.getEffectiveLevel())) {
171          forcedLog(FQCN, Level.TRACE, message, null);
172        }
173      }
174  
175      /**
176       * Log a message object with the <code>TRACE</code> level including the
177       * stack trace of the {@link Throwable}<code>t</code> passed as parameter.
178       *
179       * <p>
180       * See {@link #debug(Object)} form for more detailed information.
181       * </p>
182       *
183       * @param message the message object to log.
184       * @param t the exception to log, including its stack trace.
185       * @since 1.2.12
186       */
187      public void trace(Object message, Throwable t) {
188        if (repository.isDisabled(Level.TRACE_INT)) {
189          return;
190        }
191  
192        if (Level.TRACE.isGreaterOrEqual(this.getEffectiveLevel())) {
193          forcedLog(FQCN, Level.TRACE, message, t);
194        }
195      }
196  
197      /**
198       * Check whether this category is enabled for the TRACE  Level.
199       * @since 1.2.12
200       *
201       * @return boolean - <code>true</code> if this category is enabled for level
202       *         TRACE, <code>false</code> otherwise.
203       */
204      public boolean isTraceEnabled() {
205          if (repository.isDisabled(Level.TRACE_INT)) {
206              return false;
207            }
208  
209            return Level.TRACE.isGreaterOrEqual(this.getEffectiveLevel());
210      }
211  
212  }