Source code

001/*
002 * SonarQube
003 * Copyright (C) 2009-2017 SonarSource SA
004 * mailto:info AT sonarsource DOT com
005 *
006 * This program is free software; you can redistribute it and/or
007 * modify it under the terms of the GNU Lesser General Public
008 * License as published by the Free Software Foundation; either
009 * version 3 of the License, or (at your option) any later version.
010 *
011 * This program is distributed in the hope that it will be useful,
012 * but WITHOUT ANY WARRANTY; without even the implied warranty of
013 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
014 * Lesser General Public License for more details.
015 *
016 * You should have received a copy of the GNU Lesser General Public License
017 * along with this program; if not, write to the Free Software Foundation,
018 * Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
019 */
020package org.sonar.api.utils.log;
021
022import java.util.function.Supplier;
023import javax.annotation.Nullable;
024
025/**
026 * SonarQube plugins are not coupled with external logging libraries like SLF4J or Logback.
027 * <p>
028 * Example:
029 * <pre>
030 * public class MyClass {
031 *   private static final Logger LOGGER = Loggers.get("logger_name");
032 *
033 *   public void doSomething() {
034 *     LOGGER.info("something valuable for production environment");
035 *     LOGGER.warn("message with arguments {} and {}", "foo", 42);
036 *   }
037 * }
038 * </pre>
039 * <p>
040 * Message arguments are defined with <code>{}</code>, but not with {@link java.util.Formatter} syntax.
041 *
042 * <p>
043 * INFO, WARN and ERROR levels are always enabled. They can't be disabled by users.
044 * DEBUG and TRACE levels are enabled on demand with the property <code>sonar.log.level</code>.
045 * <p>
046 * See {@link org.sonar.api.utils.log.LogTester} for testing facilities.
047 * @since 5.1
048 */
049public interface Logger {
050
051  boolean isTraceEnabled();
052
053  /**
054   * Logs a TRACE message.
055   * <p>
056   * TRACE messages must
057   * be valuable for diagnosing production problems. They must not be used for development debugging.
058   * They can significantly slow down performances. The standard use-case is logging of
059   * SQL and Elasticsearch requests.
060   */
061  void trace(String msg);
062
063  /**
064   * Logs a TRACE message, which is only to be constructed if the logging level
065   * is such that the message will actually be logged.
066   * <p>
067   * TRACE messages must
068   * be valuable for diagnosing production problems. They must not be used for development debugging.
069   * They can significantly slow down performances. The standard use-case is logging of
070   * SQL and Elasticsearch requests.
071   * @param msgSupplier A function, which when called, produces the desired log message
072   * @since 6.3
073   */
074  default void trace(Supplier<String> msgSupplier) {
075    if (isTraceEnabled()) {
076      trace(msgSupplier.get());
077    }
078  }
079
080  /**
081   * Logs an TRACE parameterized message according to the specified format and argument. Example:
082   * <code>trace("Value is {}", value)</code>
083   * <p>
084   * TRACE messages must
085   * be valuable for diagnosing production problems. They must not be used for development debugging.
086   * They can significantly slow down performances. The standard use-case is logging of
087   * SQL and Elasticsearch requests.
088   */
089  void trace(String pattern, @Nullable Object arg);
090
091  /**
092   * Logs an TRACE parameterized message according to the specified format and arguments. Example:
093   * <code>trace("Values are {} and {}", value1, value2)</code>
094   * <p>
095   * TRACE messages must
096   * be valuable for diagnosing production problems. They must not be used for development debugging.
097   * They can significantly slow down performances. The standard use-case is logging of
098   * SQL and Elasticsearch requests.
099   */
100  void trace(String msg, @Nullable Object arg1, @Nullable Object arg2);
101
102  /**
103   * Logs an TRACE parameterized message according to the specified format and arguments. Example:
104   * <code>trace("Values are {} and {}", value1, value2)</code>
105   * <p>
106   * TRACE messages must
107   * be valuable for diagnosing production problems. They must not be used for development debugging.
108   * They can significantly slow down performances. The standard use-case is logging of
109   * SQL and Elasticsearch requests.
110   * <p>
111   * This variant incurs the hidden cost of creating an Object[] before invoking the method.
112   * The variants taking one and two arguments exist solely in order to avoid this hidden cost. See
113   * {@link #trace(String, Object)} and {@link #trace(String, Object, Object)}
114   */
115  void trace(String msg, Object... args);
116
117  boolean isDebugEnabled();
118
119  /**
120   * Logs a DEBUG message. 
121   * <p>
122   * DEBUG messages must
123   * be valuable for diagnosing production problems. They must not be used for development debugging.
124   */
125  void debug(String msg);
126
127  /**
128   * Logs a DEBUG message which is only to be constructed if the logging level
129   * is such that the message will actually be logged.
130   * <p>
131   * DEBUG messages must
132   * be valuable for diagnosing production problems. They must not be used for development debugging.
133   * @param msgSupplier A function, which when called, produces the desired log message
134   * @since 6.3
135   */
136  default void debug(Supplier<String> msgSupplier) {
137    if (isDebugEnabled()) {
138      debug(msgSupplier.get());
139    }
140  }
141
142  /**
143   * Logs an DEBUG parameterized message according to the specified format and argument. Example:
144   * <code>debug("Value is {}", value)</code>
145   * <p>
146   * Debug messages must
147   * be valuable for diagnosing production problems. They must not be used for development debugging.
148   */
149  void debug(String pattern, @Nullable Object arg);
150
151  /**
152   * Logs an DEBUG parameterized message according to the specified format and arguments. Example:
153   * <code>debug("Values are {} and {}", value1, value2)</code>
154   * <p>
155   * Debug messages must
156   * be valuable for diagnosing production problems. They must not be used for development debugging.
157   */
158  void debug(String msg, @Nullable Object arg1, @Nullable Object arg2);
159
160  /**
161   * Logs an DEBUG parameterized message according to the specified format and arguments. Example:
162   * <code>debug("Values are {}, {} and {}", value1, value2, value3)</code>
163   * <p>
164   * Debug messages must
165   * be valuable for diagnosing production problems. They must not be used for development debugging.
166   * * <p>
167   * This variant incurs the hidden cost of creating an Object[] before invoking the method.
168   * The variants taking one and two arguments exist solely in order to avoid this hidden cost. See
169   * {@link #debug(String, Object)} and {@link #debug(String, Object, Object)}
170   */
171  void debug(String msg, Object... args);
172
173  /**
174   * Logs an INFO level message.
175   */
176  void info(String msg);
177
178  /**
179   * Logs an INFO parameterized message according to the specified format and argument. Example:
180   * <code>info("Value is {}", value)</code>
181   */
182  void info(String msg, @Nullable Object arg);
183
184  /**
185   * Logs an INFO parameterized message according to the specified format and arguments. Example:
186   * <code>info("Values are {} and {}", value1, value2)</code>
187   */
188  void info(String msg, @Nullable Object arg1, @Nullable Object arg2);
189
190  /**
191   * Logs an INFO parameterized message according to the specified format and arguments. Example:
192   * <code>info("Values are {}, {} and {}", value1, value2, value3)</code>
193   * <p>
194   * This variant incurs the hidden cost of creating an Object[] before invoking the method.
195   * The variants taking one and two arguments exist solely in order to avoid this hidden cost. See
196   * {@link #info(String, Object)} and {@link #info(String, Object, Object)}
197   */
198  void info(String msg, Object... args);
199
200  /**
201   * Logs a WARN level message.
202   */
203  void warn(String msg);
204
205  /**
206   * Logs an exception at the WARN level with an accompanying message.
207   */
208  void warn(String msg, Throwable throwable);
209
210  /**
211   * Logs a WARN parameterized message according to the specified format and argument. Example:
212   * <code>warn("Value is {}", value)</code>
213   */
214  void warn(String msg, @Nullable Object arg);
215
216  /**
217   * Logs a WARN parameterized message according to the specified format and arguments. Example:
218   * <code>warn("Values are {} and {}", value1, value2)</code>
219   */
220  void warn(String msg, @Nullable Object arg1, @Nullable Object arg2);
221
222  /**
223   * Logs a WARN parameterized message according to the specified format and arguments. Example:
224   * <code>warn("Values are {}, {} and {}", value1, value2, value3)</code>
225   * <p>
226   * This variant incurs the hidden cost of creating an Object[] before invoking the method.
227   * The variants taking one and two arguments exist solely in order to avoid this hidden cost. See
228   * {@link #warn(String, Object)} and {@link #warn(String, Object, Object)}
229   */
230  void warn(String msg, Object... args);
231
232  /**
233   * Logs an ERROR level message.
234   */
235  void error(String msg);
236
237  /**
238   * Logs an ERROR parameterized message according to the specified format and argument. Example:
239   * <code>error("Value is {}", value)</code>
240   */
241  void error(String msg, @Nullable Object arg);
242
243  /**
244   * Logs a ERROR parameterized message according to the specified format and arguments. Example:
245   * <code>error("Values are {} and {}", value1, value2)</code>
246   */
247  void error(String msg, @Nullable Object arg1, @Nullable Object arg2);
248
249  /**
250   * Logs a ERROR parameterized message according to the specified format and arguments. Example:
251   * <code>error("Values are {}, {} and {}", value1, value2, value3)</code>
252   * <p>
253   * This variant incurs the hidden cost of creating an Object[] before invoking the method.
254   * The variants taking one and two arguments exist solely in order to avoid this hidden cost. See
255   * {@link #error(String, Object)} and {@link #error(String, Object, Object)}
256   */
257  void error(String msg, Object... args);
258
259  /**
260   * Logs an exception at the ERROR level with an accompanying message.
261   */
262  void error(String msg, Throwable thrown);
263
264  /**
265   * Attempt to change logger level. Return true if it succeeded, false if
266   * the underlying logging facility does not allow to change level at
267   * runtime.
268   * <p>
269   * This method must not be used to enable DEBUG or TRACE logs in tests. Use
270   * {@link org.sonar.api.utils.log.LogTester#setLevel(LoggerLevel)} instead.
271   * <p>
272   * The standard use-case is to customize logging of embedded 3rd-party
273   * libraries.
274   */
275  boolean setLevel(LoggerLevel level);
276
277  LoggerLevel getLevel();
278}