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}