001/*
002 * SonarQube, open source software quality management tool.
003 * Copyright (C) 2008-2014 SonarSource
004 * mailto:contact AT sonarsource DOT com
005 *
006 * SonarQube 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 * SonarQube 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></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></p>
039 * Message arguments are defined with <code>{}</code>, but not with {@link java.util.Formatter} syntax.
040 *
041 * <p></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></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></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></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></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></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></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></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></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></p>
129   * Debug messages must
130   * be valuable for diagnosing production problems. They must not be used for development debugging.
131   * * <p></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></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 a WARN parameterized message according to the specified format and argument. Example:
172   * <code>warn("Value is {}", value)</code>
173   */
174  void warn(String msg, @Nullable Object arg);
175
176  /**
177   * Logs a WARN parameterized message according to the specified format and arguments. Example:
178   * <code>warn("Values are {} and {}", value1, value2)</code>
179   */
180  void warn(String msg, @Nullable Object arg1, @Nullable Object arg2);
181
182  /**
183   * Logs a WARN parameterized message according to the specified format and arguments. Example:
184   * <code>warn("Values are {}, {} and {}", value1, value2, value3)</code>
185   * <p></p>
186   * This variant incurs the hidden cost of creating an Object[] before invoking the method.
187   * The variants taking one and two arguments exist solely in order to avoid this hidden cost. See
188   * {@link #warn(String, Object)} and {@link #warn(String, Object, Object)}
189   */
190  void warn(String msg, Object... args);
191
192  /**
193   * Logs an ERROR level message.
194   */
195  void error(String msg);
196
197  /**
198   * Logs an ERROR parameterized message according to the specified format and argument. Example:
199   * <code>error("Value is {}", value)</code>
200   */
201  void error(String msg, @Nullable Object arg);
202
203  /**
204   * Logs a ERROR parameterized message according to the specified format and arguments. Example:
205   * <code>error("Values are {} and {}", value1, value2)</code>
206   */
207  void error(String msg, @Nullable Object arg1, @Nullable Object arg2);
208
209  /**
210   * Logs a ERROR parameterized message according to the specified format and arguments. Example:
211   * <code>error("Values are {}, {} and {}", value1, value2, value3)</code>
212   * <p></p>
213   * This variant incurs the hidden cost of creating an Object[] before invoking the method.
214   * The variants taking one and two arguments exist solely in order to avoid this hidden cost. See
215   * {@link #error(String, Object)} and {@link #error(String, Object, Object)}
216   */
217  void error(String msg, Object... args);
218
219  /**
220   * Logs an exception at the ERROR level with an accompanying message.
221   */
222  void error(String msg, Throwable thrown);
223
224  /**
225   * Attempt to change logger level. Return true if it succeeded, false if
226   * the underlying logging facility does not allow to change level at
227   * runtime.
228   * <p></p>
229   * This method must not be used to enable DEBUG or TRACE logs in tests. Use
230   * {@link org.sonar.api.utils.log.LogTester#setLevel(LoggerLevel)} instead.
231   * <p></p>
232   * The standard use-case is to customize logging of embedded 3rd-party
233   * libraries.
234   */
235  boolean setLevel(LoggerLevel level);
236
237}