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}