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
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    * 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 }
213