001/*
002 * Licensed to the Apache Software Foundation (ASF) under one or more
003 * contributor license agreements.  See the NOTICE file distributed with
004 * this work for additional information regarding copyright ownership.
005 * The ASF licenses this file to You under the Apache License, Version 2.0
006 * (the "License"); you may not use this file except in compliance with
007 * the License.  You may obtain a copy of the License at
008 * 
009 *      http://www.apache.org/licenses/LICENSE-2.0
010 * 
011 * Unless required by applicable law or agreed to in writing, software
012 * distributed under the License is distributed on an "AS IS" BASIS,
013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014 * See the License for the specific language governing permissions and
015 * limitations under the License.
016 */
017
018package org.apache.log4j;
019
020import org.apache.log4j.spi.LoggerFactory;
021
022
023/**
024  This is the central class in the log4j package. Most logging
025  operations, except configuration, are done through this class.
026
027  @since log4j 1.2
028
029  @author Ceki Gülcü */
030public class Logger extends Category {
031
032  /**
033     The fully qualified name of the Logger class. See also the
034     getFQCN method. */
035  private static final String FQCN = Logger.class.getName();
036
037
038  protected
039  Logger(String name) {
040    super(name);
041  }
042
043  /**
044    Log a message object with the {@link Level#FINE FINE} level which
045    is just an alias for the {@link Level#DEBUG DEBUG} level.
046
047    <p>This method first checks if this category is <code>DEBUG</code>
048    enabled by comparing the level of this category with the {@link
049    Level#DEBUG DEBUG} level. If this category is
050    <code>DEBUG</code> enabled, then it converts the message object
051    (passed as parameter) to a string by invoking the appropriate
052    {@link org.apache.log4j.or.ObjectRenderer}. It then proceeds to call all the
053    registered appenders in this category and also higher in the
054    hierarchy depending on the value of the additivity flag.
055
056    <p><b>WARNING</b> Note that passing a {@link Throwable} to this
057    method will print the name of the <code>Throwable</code> but no
058    stack trace. To print a stack trace use the {@link #debug(Object,
059    Throwable)} form instead.
060
061    @param message the message object to log. */
062  //public
063  //void fine(Object message) {
064  //  if(repository.isDisabled(Level.DEBUG_INT))
065  //    return;
066  //  if(Level.DEBUG.isGreaterOrEqual(this.getChainedLevel())) {
067  //    forcedLog(FQCN, Level.DEBUG, message, null);
068  //  }
069  //}
070
071
072  /**
073   Log a message object with the <code>FINE</code> level including
074   the stack trace of the {@link Throwable} <code>t</code> passed as
075   parameter.
076
077   <p>See {@link #fine(Object)} form for more detailed information.
078
079   @param message the message object to log.
080   @param t the exception to log, including its stack trace.  */
081  //public
082  //void fine(Object message, Throwable t) {
083  //  if(repository.isDisabled(Level.DEBUG_INT))
084  //    return;
085  //  if(Level.DEBUG.isGreaterOrEqual(this.getChainedLevel()))
086  //    forcedLog(FQCN, Level.FINE, message, t);
087  //}
088
089  /**
090   * Retrieve a logger named according to the value of the
091   * <code>name</code> parameter. If the named logger already exists,
092   * then the existing instance will be returned. Otherwise, a new
093   * instance is created.  
094   *
095   * <p>By default, loggers do not have a set level but inherit it
096   * from their neareast ancestor with a set level. This is one of the
097   * central features of log4j.
098   *
099   * @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   * string 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}