View Javadoc

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