001/*
002 * SonarQube
003 * Copyright (C) 2009-2016 SonarSource SA
004 * mailto:contact 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 javax.annotation.Nullable;
023
024/**
025 * SonarQube plugins are not coupled with external logging libraries like SLF4J or Logback.
026 * <p>
027 * Example:
028 * <pre>
029 * public class MyClass {
030 *   private static final Logger LOGGER = Loggers.get("logger_name");
031 *
032 *   public void doSomething() {
033 *     LOGGER.info("something valuable for production environment");
034 *     LOGGER.warn("message with arguments {} and {}", "foo", 42);
035 *   }
036 * }
037 * </pre>
038 * <p>
039 * Message arguments are defined with <code>{}</code>, but not with {@link java.util.Formatter} syntax.
040 *
041 * <p>
042 * INFO, WARN and ERROR levels are always enabled. They can't be disabled by users.
043 * DEBUG and TRACE levels are enabled on demand with the property <code>sonar.log.level</code>.
044 * <p>
045 * See {@link org.sonar.api.utils.log.LogTester} for testing facilities.
046 * @since 5.1
047 */
048public interface Logger {
049
050  boolean isTraceEnabled();
051
052  /**
053   * Logs a TRACE message.
054   * <p>
055   * TRACE messages must
056   * be valuable for diagnosing production problems. They must not be used for development debugging.
057   * They can significantly slow down performances. The standard use-case is logging of
058   * SQL and Elasticsearch requests.
059   */
060  void trace(String msg);
061
062  /**
063   * Logs an TRACE parameterized message according to the specified format and argument. Example:
064   * <code>trace("Value is {}", value)</code>
065   * <p>
066   * TRACE messages must
067   * be valuable for diagnosing production problems. They must not be used for development debugging.
068   * They can significantly slow down performances. The standard use-case is logging of
069   * SQL and Elasticsearch requests.
070   */
071  void trace(String pattern, @Nullable Object arg);
072
073  /**
074   * Logs an TRACE parameterized message according to the specified format and arguments. Example:
075   * <code>trace("Values are {} and {}", value1, value2)</code>
076   * <p>
077   * TRACE messages must
078   * be valuable for diagnosing production problems. They must not be used for development debugging.
079   * They can significantly slow down performances. The standard use-case is logging of
080   * SQL and Elasticsearch requests.
081   */
082  void trace(String msg, @Nullable Object arg1, @Nullable Object arg2);
083
084  /**
085   * Logs an TRACE parameterized message according to the specified format and arguments. Example:
086   * <code>trace("Values are {} and {}", value1, value2)</code>
087   * <p>
088   * TRACE messages must
089   * be valuable for diagnosing production problems. They must not be used for development debugging.
090   * They can significantly slow down performances. The standard use-case is logging of
091   * SQL and Elasticsearch requests.
092   * <p>
093   * This variant incurs the hidden cost of creating an Object[] before invoking the method.
094   * The variants taking one and two arguments exist solely in order to avoid this hidden cost. See
095   * {@link #trace(String, Object)} and {@link #trace(String, Object, Object)}
096   */
097  void trace(String msg, Object... args);
098
099  boolean isDebugEnabled();
100
101  /**
102   * Logs a DEBUG message. Debug messages must
103   * be valuable for diagnosing production problems. They must not be used for development debugging.
104   */
105  void debug(String msg);
106
107  /**
108   * Logs an DEBUG parameterized message according to the specified format and argument. Example:
109   * <code>debug("Value is {}", value)</code>
110   * <p>
111   * Debug messages must
112   * be valuable for diagnosing production problems. They must not be used for development debugging.
113   */
114  void debug(String pattern, @Nullable Object arg);
115
116  /**
117   * Logs an DEBUG parameterized message according to the specified format and arguments. Example:
118   * <code>debug("Values are {} and {}", value1, value2)</code>
119   * <p>
120   * Debug messages must
121   * be valuable for diagnosing production problems. They must not be used for development debugging.
122   */
123  void debug(String msg, @Nullable Object arg1, @Nullable Object arg2);
124
125  /**
126   * Logs an DEBUG parameterized message according to the specified format and arguments. Example:
127   * <code>debug("Values are {}, {} and {}", value1, value2, value3)</code>
128   * <p>
129   * Debug messages must
130   * be valuable for diagnosing production problems. They must not be used for development debugging.
131   * * <p>
132   * This variant incurs the hidden cost of creating an Object[] before invoking the method.
133   * The variants taking one and two arguments exist solely in order to avoid this hidden cost. See
134   * {@link #debug(String, Object)} and {@link #debug(String, Object, Object)}
135   */
136  void debug(String msg, Object... args);
137
138  /**
139   * Logs an INFO level message.
140   */
141  void info(String msg);
142
143  /**
144   * Logs an INFO parameterized message according to the specified format and argument. Example:
145   * <code>info("Value is {}", value)</code>
146   */
147  void info(String msg, @Nullable Object arg);
148
149  /**
150   * Logs an INFO parameterized message according to the specified format and arguments. Example:
151   * <code>info("Values are {} and {}", value1, value2)</code>
152   */
153  void info(String msg, @Nullable Object arg1, @Nullable Object arg2);
154
155  /**
156   * Logs an INFO parameterized message according to the specified format and arguments. Example:
157   * <code>info("Values are {}, {} and {}", value1, value2, value3)</code>
158   * <p>
159   * This variant incurs the hidden cost of creating an Object[] before invoking the method.
160   * The variants taking one and two arguments exist solely in order to avoid this hidden cost. See
161   * {@link #info(String, Object)} and {@link #info(String, Object, Object)}
162   */
163  void info(String msg, Object... args);
164
165  /**
166   * Logs a WARN level message.
167   */
168  void warn(String msg);
169
170  /**
171   * Logs an exception at the WARN level with an accompanying message.
172   */
173  void warn(String msg, Throwable throwable);
174
175  /**
176   * Logs a WARN parameterized message according to the specified format and argument. Example:
177   * <code>warn("Value is {}", value)</code>
178   */
179  void warn(String msg, @Nullable Object arg);
180
181  /**
182   * Logs a WARN parameterized message according to the specified format and arguments. Example:
183   * <code>warn("Values are {} and {}", value1, value2)</code>
184   */
185  void warn(String msg, @Nullable Object arg1, @Nullable Object arg2);
186
187  /**
188   * Logs a WARN parameterized message according to the specified format and arguments. Example:
189   * <code>warn("Values are {}, {} and {}", value1, value2, value3)</code>
190   * <p>
191   * This variant incurs the hidden cost of creating an Object[] before invoking the method.
192   * The variants taking one and two arguments exist solely in order to avoid this hidden cost. See
193   * {@link #warn(String, Object)} and {@link #warn(String, Object, Object)}
194   */
195  void warn(String msg, Object... args);
196
197  /**
198   * Logs an ERROR level message.
199   */
200  void error(String msg);
201
202  /**
203   * Logs an ERROR parameterized message according to the specified format and argument. Example:
204   * <code>error("Value is {}", value)</code>
205   */
206  void error(String msg, @Nullable Object arg);
207
208  /**
209   * Logs a ERROR parameterized message according to the specified format and arguments. Example:
210   * <code>error("Values are {} and {}", value1, value2)</code>
211   */
212  void error(String msg, @Nullable Object arg1, @Nullable Object arg2);
213
214  /**
215   * Logs a ERROR parameterized message according to the specified format and arguments. Example:
216   * <code>error("Values are {}, {} and {}", value1, value2, value3)</code>
217   * <p>
218   * This variant incurs the hidden cost of creating an Object[] before invoking the method.
219   * The variants taking one and two arguments exist solely in order to avoid this hidden cost. See
220   * {@link #error(String, Object)} and {@link #error(String, Object, Object)}
221   */
222  void error(String msg, Object... args);
223
224  /**
225   * Logs an exception at the ERROR level with an accompanying message.
226   */
227  void error(String msg, Throwable thrown);
228
229  /**
230   * Attempt to change logger level. Return true if it succeeded, false if
231   * the underlying logging facility does not allow to change level at
232   * runtime.
233   * <p>
234   * This method must not be used to enable DEBUG or TRACE logs in tests. Use
235   * {@link org.sonar.api.utils.log.LogTester#setLevel(LoggerLevel)} instead.
236   * <p>
237   * The standard use-case is to customize logging of embedded 3rd-party
238   * libraries.
239   */
240  boolean setLevel(LoggerLevel level);
241
242  LoggerLevel getLevel();
243}