1 /* 2 * Licensed to the Apache Software Foundation (ASF) under one or more 3 * contributor license agreements. See the NOTICE file distributed with 4 * this work for additional information regarding copyright ownership. 5 * The ASF licenses this file to You under the Apache License, Version 2.0 6 * (the "License"); you may not use this file except in compliance with 7 * the License. You may obtain a copy of the License at 8 * 9 * http://www.apache.org/licenses/LICENSE-2.0 10 * 11 * Unless required by applicable law or agreed to in writing, software 12 * distributed under the License is distributed on an "AS IS" BASIS, 13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 14 * See the License for the specific language governing permissions and 15 * limitations under the License. 16 */ 17 18 package org.apache.commons.configuration2.io; 19 20 import org.apache.commons.logging.Log; 21 import org.apache.commons.logging.LogFactory; 22 import org.apache.commons.logging.impl.NoOpLog; 23 24 /** 25 * <p> 26 * A class providing basic logging capabilities. 27 * </p> 28 * <p> 29 * When reading configuration files in complex scenarios having log output is useful for diagnostic purposes. Therefore, 30 * <em>Commons Configuration</em> produces some logging output. As concrete projects have different requirements on the 31 * amount and detail of logging, there is a way of configuring logging: All classes derived from 32 * {@link org.apache.commons.configuration2.AbstractConfiguration} can be assigned a logger which is then used for all 33 * log statements generated. 34 * </p> 35 * <p> 36 * Allowing a logger object to be passed to a configuration creates a direct dependency to a concrete logging framework 37 * in the configuration API. This would make it impossible to switch to an alternative logging framework without 38 * breaking backwards compatibility. To avoid this, the {@code ConfigurationLogger} class is introduced. It is a minimum 39 * abstraction over a logging framework offering only very basic logging capabilities. The methods defined in this class 40 * are used by configuration implementations to produce their logging statements. Client applications can create 41 * specialized instances and pass them to configuration objects without having to deal with a concrete logging 42 * framework. It is even possible to create a subclass that uses a completely different logging framework. 43 * </p> 44 * 45 * @since 2.0 46 */ 47 public class ConfigurationLogger { 48 /** The internal logger. */ 49 private final Log log; 50 51 /** 52 * Creates a new instance of {@code ConfigurationLogger} that uses the specified logger name. 53 * 54 * @param loggerName the logger name (must not be <b>null</b>) 55 * @throws IllegalArgumentException if the logger name is <b>null</b> 56 */ 57 public ConfigurationLogger(final String loggerName) { 58 this(createLoggerForName(loggerName)); 59 } 60 61 /** 62 * Creates a new instance of {@code ConfigurationLogger} that uses a logger whose name is derived from the provided 63 * class. 64 * 65 * @param logCls the class whose name is to be used for logging (must not be <b>null</b>) 66 * @throws IllegalArgumentException if the logger class is <b>null</b> 67 */ 68 public ConfigurationLogger(final Class<?> logCls) { 69 this(createLoggerForClass(logCls)); 70 } 71 72 /** 73 * Creates a new, uninitialized instance of {@code ConfigurationLogger}. This constructor can be used by derived classes 74 * that implement their own specific logging mechanism. Such classes must override all methods because the default 75 * implementations do not work in this uninitialized state. 76 */ 77 protected ConfigurationLogger() { 78 this((Log) null); 79 } 80 81 /** 82 * Creates a new instance of {@code ConfigurationLogger} which wraps the specified logger. 83 * 84 * @param wrapped the logger to be wrapped 85 */ 86 ConfigurationLogger(final Log wrapped) { 87 log = wrapped; 88 } 89 90 /** 91 * Creates a new dummy logger which produces no output. If such a logger is passed to a configuration object, logging is 92 * effectively disabled. 93 * 94 * @return the new dummy logger 95 */ 96 public static ConfigurationLogger newDummyLogger() { 97 return new ConfigurationLogger(new NoOpLog()); 98 } 99 100 /** 101 * Returns a flag whether logging on debug level is enabled. 102 * 103 * @return <b>true</b> if debug logging is enabled, <b>false</b> otherwise 104 */ 105 public boolean isDebugEnabled() { 106 return getLog().isDebugEnabled(); 107 } 108 109 /** 110 * Logs the specified message on debug level. 111 * 112 * @param msg the message to be logged 113 */ 114 public void debug(final String msg) { 115 getLog().debug(msg); 116 } 117 118 /** 119 * Returns a flag whether logging on info level is enabled. 120 * 121 * @return <b>true</b> if debug logging is enabled, <b>false</b> otherwise 122 */ 123 public boolean isInfoEnabled() { 124 return getLog().isInfoEnabled(); 125 } 126 127 /** 128 * Logs the specified message on info level. 129 * 130 * @param msg the message to be logged 131 */ 132 public void info(final String msg) { 133 getLog().info(msg); 134 } 135 136 /** 137 * Logs the specified message on warn level. 138 * 139 * @param msg the message to be logged 140 */ 141 public void warn(final String msg) { 142 getLog().warn(msg); 143 } 144 145 /** 146 * Logs the specified exception on warn level. 147 * 148 * @param msg the message to be logged 149 * @param ex the exception to be logged 150 */ 151 public void warn(final String msg, final Throwable ex) { 152 getLog().warn(msg, ex); 153 } 154 155 /** 156 * Logs the specified message on error level. 157 * 158 * @param msg the message to be logged 159 */ 160 public void error(final String msg) { 161 getLog().error(msg); 162 } 163 164 /** 165 * Logs the specified exception on error level. 166 * 167 * @param msg the message to be logged 168 * @param ex the exception to be logged 169 */ 170 public void error(final String msg, final Throwable ex) { 171 getLog().error(msg, ex); 172 } 173 174 /** 175 * Gets the internal logger. 176 * 177 * @return the internal logger 178 */ 179 Log getLog() { 180 return log; 181 } 182 183 /** 184 * Creates an internal logger for the given name. Throws an exception if the name is undefined. 185 * 186 * @param name the name of the logger 187 * @return the logger object 188 * @throws IllegalArgumentException if the logger name is undefined 189 */ 190 private static Log createLoggerForName(final String name) { 191 if (name == null) { 192 throw new IllegalArgumentException("Logger name must not be null!"); 193 } 194 return LogFactory.getLog(name); 195 } 196 197 /** 198 * Creates an internal logger for the given class. Throws an exception if the class is undefined. 199 * 200 * @param cls the logger class 201 * @return the logger object 202 * @throws IllegalArgumentException if the logger class is undefined 203 */ 204 private static Log createLoggerForClass(final Class<?> cls) { 205 if (cls == null) { 206 throw new IllegalArgumentException("Logger class must not be null!"); 207 } 208 return LogFactory.getLog(cls); 209 } 210 }