You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@commons.apache.org by oh...@apache.org on 2015/10/22 21:45:13 UTC
svn commit: r1710082 - in /commons/proper/configuration/trunk/src:
main/java/org/apache/commons/configuration2/ConfigurationLogger.java
test/java/org/apache/commons/configuration2/TestConfigurationLogger.java
Author: oheger
Date: Thu Oct 22 19:45:13 2015
New Revision: 1710082
URL: http://svn.apache.org/viewvc?rev=1710082&view=rev
Log:
Added new ConfigurationLogger class.
This is a very basic abstraction of a logging API. It is used internally by
classes of the library to produce logging statements. The idea is that client
applications can reference this class without having to deal with a specific
logging framework.
Added:
commons/proper/configuration/trunk/src/main/java/org/apache/commons/configuration2/ConfigurationLogger.java
commons/proper/configuration/trunk/src/test/java/org/apache/commons/configuration2/TestConfigurationLogger.java
Added: commons/proper/configuration/trunk/src/main/java/org/apache/commons/configuration2/ConfigurationLogger.java
URL: http://svn.apache.org/viewvc/commons/proper/configuration/trunk/src/main/java/org/apache/commons/configuration2/ConfigurationLogger.java?rev=1710082&view=auto
==============================================================================
--- commons/proper/configuration/trunk/src/main/java/org/apache/commons/configuration2/ConfigurationLogger.java (added)
+++ commons/proper/configuration/trunk/src/main/java/org/apache/commons/configuration2/ConfigurationLogger.java Thu Oct 22 19:45:13 2015
@@ -0,0 +1,243 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.apache.commons.configuration2;
+
+import org.apache.commons.logging.Log;
+import org.apache.commons.logging.LogFactory;
+import org.apache.commons.logging.impl.NoOpLog;
+
+/**
+ * <p>
+ * A class providing basic logging capabilities.
+ * </p>
+ * <p>
+ * When reading configuration files in complex scenarios having log output is
+ * useful for diagnostic purposes. Therefore, <em>Commons Configuration</em>
+ * produces some logging output. As concrete projects have different
+ * requirements on the amount and detail of logging, there is a way of
+ * configuring logging: All classes derived from {@link AbstractConfiguration}
+ * can be assigned a logger which is then used for all log statements generated.
+ * </p>
+ * <p>
+ * Allowing a logger object to be passed to a configuration creates a direct
+ * dependency to a concrete logging framework in the configuration API. This
+ * would make it impossible to switch to an alternative logging framework
+ * without breaking backwards compatibility. To avoid this, the
+ * {@code ConfigurationLogger} class is introduced. It is a minimum abstraction
+ * over a logging framework offering only very basic logging capabilities. The
+ * methods defined in this class are used by configuration implementations to
+ * produce their logging statements. Client applications can create specialized
+ * instances and pass them to configuration objects without having to deal with
+ * a concrete logging framework. It is even possible to create a subclass that
+ * uses a completely different logging framework.
+ * </p>
+ *
+ * @version $Id$
+ * @since 2.0
+ */
+public class ConfigurationLogger
+{
+ /** The internal logger. */
+ private final Log log;
+
+ /**
+ * Creates a new instance of {@code ConfigurationLogger} that uses the
+ * specified logger name.
+ *
+ * @param loggerName the logger name (must not be <b>null</b>)
+ * @throws IllegalArgumentException if the logger name is <b>null</b>
+ */
+ public ConfigurationLogger(String loggerName)
+ {
+ this(createLoggerForName(loggerName));
+ }
+
+ /**
+ * Creates a new instance of {@code ConfigurationLogger} that uses a logger
+ * whose name is derived from the provided class.
+ *
+ * @param logCls the class whose name is to be used for logging (must not be
+ * <b>null</b>)
+ * @throws IllegalArgumentException if the logger class is <b>null</b>
+ */
+ public ConfigurationLogger(Class<?> logCls)
+ {
+ this(createLoggerForClass(logCls));
+ }
+
+ /**
+ * Creates a new, uninitialized instance of {@code ConfigurationLogger}.
+ * This constructor can be used by derived classes that implement their own
+ * specific logging mechanism. Such classes must override all methods
+ * because the default implementations do not work in this uninitialized
+ * state.
+ */
+ protected ConfigurationLogger()
+ {
+ this((Log) null);
+ }
+
+ /**
+ * Creates a new instance of {@code ConfigurationLogger} which wraps the
+ * specified logger.
+ *
+ * @param wrapped the logger to be wrapped
+ */
+ ConfigurationLogger(Log wrapped)
+ {
+ log = wrapped;
+ }
+
+ /**
+ * Creates a new dummy logger which produces no output. If such a logger is
+ * passed to a configuration object, logging is effectively disabled.
+ *
+ * @return the new dummy logger
+ */
+ public static ConfigurationLogger newDummyLogger()
+ {
+ return new ConfigurationLogger(new NoOpLog());
+ }
+
+ /**
+ * Returns a flag whether logging on debug level is enabled.
+ *
+ * @return <b>true</b> if debug logging is enabled, <b>false</b> otherwise
+ */
+ public boolean isDebugEnabled()
+ {
+ return getLog().isDebugEnabled();
+ }
+
+ /**
+ * Logs the specified message on debug level.
+ *
+ * @param msg the message to be logged
+ */
+ public void debug(String msg)
+ {
+ getLog().debug(msg);
+ }
+
+ /**
+ * Returns a flag whether logging on info level is enabled.
+ *
+ * @return <b>true</b> if debug logging is enabled, <b>false</b> otherwise
+ */
+ public boolean isInfoEnabled()
+ {
+ return getLog().isInfoEnabled();
+ }
+
+ /**
+ * Logs the specified message on info level.
+ *
+ * @param msg the message to be logged
+ */
+ public void info(String msg)
+ {
+ getLog().info(msg);
+ }
+
+ /**
+ * Logs the specified message on warn level.
+ *
+ * @param msg the message to be logged
+ */
+ public void warn(String msg)
+ {
+ getLog().warn(msg);
+ }
+
+ /**
+ * Logs the specified exception on warn level.
+ *
+ * @param msg the message to be logged
+ * @param ex the exception to be logged
+ */
+ public void warn(String msg, Throwable ex)
+ {
+ getLog().warn(msg, ex);
+ }
+
+ /**
+ * Logs the specified message on error level.
+ *
+ * @param msg the message to be logged
+ */
+ public void error(String msg)
+ {
+ getLog().error(msg);
+ }
+
+ /**
+ * Logs the specified exception on error level.
+ *
+ * @param msg the message to be logged
+ * @param ex the exception to be logged
+ */
+ public void error(String msg, Throwable ex)
+ {
+ getLog().error(msg, ex);
+ }
+
+ /**
+ * Returns the internal logger.
+ *
+ * @return the internal logger
+ */
+ Log getLog()
+ {
+ return log;
+ }
+
+ /**
+ * Creates an internal logger for the given name. Throws an exception if the
+ * name is undefined.
+ *
+ * @param name the name of the logger
+ * @return the logger object
+ * @throws IllegalArgumentException if the logger name is undefined
+ */
+ private static Log createLoggerForName(String name)
+ {
+ if (name == null)
+ {
+ throw new IllegalArgumentException("Logger name must not be null!");
+ }
+ return LogFactory.getLog(name);
+ }
+
+ /**
+ * Creates an internal logger for the given class. Throws an exception if
+ * the class is undefined.
+ *
+ * @param cls the logger class
+ * @return the logger object
+ * @throws IllegalArgumentException if the logger class is undefined
+ */
+ private static Log createLoggerForClass(Class<?> cls)
+ {
+ if (cls == null)
+ {
+ throw new IllegalArgumentException(
+ "Logger class must not be null!");
+ }
+ return LogFactory.getLog(cls);
+ }
+}
Added: commons/proper/configuration/trunk/src/test/java/org/apache/commons/configuration2/TestConfigurationLogger.java
URL: http://svn.apache.org/viewvc/commons/proper/configuration/trunk/src/test/java/org/apache/commons/configuration2/TestConfigurationLogger.java?rev=1710082&view=auto
==============================================================================
--- commons/proper/configuration/trunk/src/test/java/org/apache/commons/configuration2/TestConfigurationLogger.java (added)
+++ commons/proper/configuration/trunk/src/test/java/org/apache/commons/configuration2/TestConfigurationLogger.java Thu Oct 22 19:45:13 2015
@@ -0,0 +1,230 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.apache.commons.configuration2;
+
+import static org.hamcrest.CoreMatchers.instanceOf;
+import static org.junit.Assert.assertEquals;
+import static org.junit.Assert.assertFalse;
+import static org.junit.Assert.assertNotNull;
+import static org.junit.Assert.assertNull;
+import static org.junit.Assert.assertThat;
+import static org.junit.Assert.assertTrue;
+
+import org.apache.commons.logging.Log;
+import org.apache.commons.logging.impl.NoOpLog;
+import org.easymock.EasyMock;
+import org.junit.Test;
+
+/**
+ * Test class for {@code ConfigurationLogger}.
+ *
+ * @version $Id$
+ */
+public class TestConfigurationLogger
+{
+ /** Constant for a message to be logged. */
+ private static final String MSG = "Interesting log output";
+
+ /**
+ * Tries to create an instance without passing in a logger name.
+ */
+ @Test(expected = IllegalArgumentException.class)
+ public void testInitNoLoggerName()
+ {
+ new ConfigurationLogger((String) null);
+ }
+
+ /**
+ * Tries to create an instance without passing a logger class.
+ */
+ @Test(expected = IllegalArgumentException.class)
+ public void testInitNoLoggerClass()
+ {
+ new ConfigurationLogger((Class<?>) null);
+ }
+
+ /**
+ * Tests whether a correct internal logger is created.
+ */
+ @Test
+ public void testInitWithLoggerSpec()
+ {
+ ConfigurationLogger logger1 =
+ new ConfigurationLogger(getClass().getName());
+ ConfigurationLogger logger2 = new ConfigurationLogger(getClass());
+
+ assertNotNull("No internal logger", logger1.getLog());
+ assertEquals("Different internal loggers", logger1.getLog(),
+ logger2.getLog());
+ }
+
+ /**
+ * Tests whether the debug status can be queried.
+ */
+ @Test
+ public void testIsDebugEnabled()
+ {
+ Log log = EasyMock.createMock(Log.class);
+ EasyMock.expect(log.isDebugEnabled()).andReturn(Boolean.TRUE);
+ EasyMock.replay(log);
+ ConfigurationLogger logger = new ConfigurationLogger(log);
+
+ assertTrue("No debug log", logger.isDebugEnabled());
+ EasyMock.verify(log);
+ }
+
+ /**
+ * Tests whether the info status can be queried.
+ */
+ @Test
+ public void testIsInfoEnabled()
+ {
+ Log log = EasyMock.createMock(Log.class);
+ EasyMock.expect(log.isInfoEnabled()).andReturn(Boolean.FALSE);
+ EasyMock.replay(log);
+ ConfigurationLogger logger = new ConfigurationLogger(log);
+
+ assertFalse("Wrong info log", logger.isInfoEnabled());
+ EasyMock.verify(log);
+ }
+
+ /**
+ * Tests whether debug logging is possible.
+ */
+ @Test
+ public void testDebug()
+ {
+ Log log = EasyMock.createMock(Log.class);
+ log.debug(MSG);
+ EasyMock.replay(log);
+ ConfigurationLogger logger = new ConfigurationLogger(log);
+
+ logger.debug(MSG);
+ EasyMock.verify(log);
+ }
+
+ /**
+ * Tests whether info logging is possible.
+ */
+ @Test
+ public void testInfo()
+ {
+ Log log = EasyMock.createMock(Log.class);
+ log.info(MSG);
+ EasyMock.replay(log);
+ ConfigurationLogger logger = new ConfigurationLogger(log);
+
+ logger.info(MSG);
+ EasyMock.verify(log);
+ }
+
+ /**
+ * Tests whether warn logging is possible.
+ */
+ @Test
+ public void testWarn()
+ {
+ Log log = EasyMock.createMock(Log.class);
+ log.warn(MSG);
+ EasyMock.replay(log);
+ ConfigurationLogger logger = new ConfigurationLogger(log);
+
+ logger.warn(MSG);
+ EasyMock.verify(log);
+ }
+
+ /**
+ * Tests whether an exception can be logged on warn level.
+ */
+ @Test
+ public void testWarnWithException()
+ {
+ Log log = EasyMock.createMock(Log.class);
+ Throwable ex = new Exception("Test exception");
+ log.warn(MSG, ex);
+ EasyMock.replay(log);
+ ConfigurationLogger logger = new ConfigurationLogger(log);
+
+ logger.warn(MSG, ex);
+ EasyMock.verify(log);
+ }
+
+ /**
+ * Tests whether error logging is possible.
+ */
+ @Test
+ public void testError()
+ {
+ Log log = EasyMock.createMock(Log.class);
+ log.error(MSG);
+ EasyMock.replay(log);
+ ConfigurationLogger logger = new ConfigurationLogger(log);
+
+ logger.error(MSG);
+ EasyMock.verify(log);
+ }
+
+ /**
+ * Tests whether an exception can be logged on error level.
+ */
+ @Test
+ public void testErrorWithException()
+ {
+ Log log = EasyMock.createMock(Log.class);
+ Throwable ex = new Exception("Test exception");
+ log.error(MSG, ex);
+ EasyMock.replay(log);
+ ConfigurationLogger logger = new ConfigurationLogger(log);
+
+ logger.error(MSG, ex);
+ EasyMock.verify(log);
+ }
+
+ /**
+ * Tests whether a dummy logger can be created.
+ */
+ @Test
+ public void testDummyLogger()
+ {
+ ConfigurationLogger logger = ConfigurationLogger.newDummyLogger();
+
+ assertThat("Wrong internal logger", logger.getLog(),
+ instanceOf(NoOpLog.class));
+ }
+
+ /**
+ * Tests that a derived class can be created for a logger.
+ */
+ @Test
+ public void testSubClass()
+ {
+ final StringBuilder buf = new StringBuilder();
+ ConfigurationLogger logger = new ConfigurationLogger()
+ {
+ @Override
+ public void info(String msg)
+ {
+ buf.append(msg);
+ }
+ };
+
+ assertNull("Got an internal logger", logger.getLog());
+ logger.info(MSG);
+ assertEquals("Message not logged", MSG, buf.toString());
+ }
+}