Siphalor/tweed5-commons-logging
1
0
Fork 0
Code Activity

Formatting and javadoc cleanup.

Browse Source 
git-svn-id: https://svn.apache.org/repos/asf/commons/proper/logging/trunk@1432446 13f79535-47bb-0310-9956-ffa450edef68
This commit is contained in:
Thomas Neidhart
2013-01-12 15:08:32 +00:00
parent 15e9fbcf46
commit 03fced4b61
4 changed files with 106 additions and 206 deletions
Download Patch File Download Diff File Expand all files Collapse all files

120
src/java/org/apache/commons/logging/Log.java
View File

@@ -15,16 +15,15 @@
* limitations under the License.
*/
package org.apache.commons.logging;
/**
* <p>A simple logging interface abstracting logging APIs. In order to be
* A simple logging interface abstracting logging APIs. In order to be
* instantiated successfully by {@link LogFactory}, classes that implement
* this interface must have a constructor that takes a single String
* parameter representing the "name" of this Log.</p>
*
* <p> The six logging levels used by <code>Log</code> are (in order):
* parameter representing the "name" of this Log.
* <p>
* The six logging levels used by <code>Log</code> are (in order):
* <ol>
* <li>trace (the least serious)</li>
* <li>debug</li>
@@ -36,25 +35,24 @@ package org.apache.commons.logging;
* The mapping of these log levels to the concepts used by the underlying
* logging system is implementation dependent.
* The implementation should ensure, though, that this ordering behaves
* as expected.</p>
*
* <p>Performance is often a logging concern.
* as expected.
* <p>
* Performance is often a logging concern.
* By examining the appropriate property,
* a component can avoid expensive operations (producing information
* to be logged).</p>
*
* <p> For example,
* to be logged).
* <p>
* For example,
* <code><pre>
* if (log.isDebugEnabled()) {
* ... do something expensive ...
* log.debug(theResult);
* }
* </pre></code>
* </p>
*
* <p>Configuration of the underlying logging system will generally be done
* <p>
* Configuration of the underlying logging system will generally be done
* external to the Logging APIs, through whatever mechanism is supported by
* that system.</p>
* that system.
*
* @author <a href="mailto:sanders@apache.org">Scott Sanders</a>
* @author Rod Waldhoff
@@ -62,163 +60,145 @@ package org.apache.commons.logging;
*/
public interface Log {
// ----------------------------------------------------- Logging Properties
/**
* <p> Is debug logging currently enabled? </p>
*
* <p> Call this method to prevent having to perform expensive operations
* Is debug logging currently enabled?
* <p>
* Call this method to prevent having to perform expensive operations
* (for example, <code>String</code> concatenation)
* when the log level is more than debug. </p>
* when the log level is more than debug.
*
* @return true if debug is enabled in the underlying logger.
*/
public boolean isDebugEnabled();
/**
* <p> Is error logging currently enabled? </p>
*
* <p> Call this method to prevent having to perform expensive operations
* Is error logging currently enabled?
* <p>
* Call this method to prevent having to perform expensive operations
* (for example, <code>String</code> concatenation)
* when the log level is more than error. </p>
* when the log level is more than error.
*
* @return true if error is enabled in the underlying logger.
*/
public boolean isErrorEnabled();
/**
* <p> Is fatal logging currently enabled? </p>
*
* <p> Call this method to prevent having to perform expensive operations
* Is fatal logging currently enabled?
* <p>
* Call this method to prevent having to perform expensive operations
* (for example, <code>String</code> concatenation)
* when the log level is more than fatal. </p>
* when the log level is more than fatal.
*
* @return true if fatal is enabled in the underlying logger.
*/
public boolean isFatalEnabled();
/**
* <p> Is info logging currently enabled? </p>
*
* <p> Call this method to prevent having to perform expensive operations
* Is info logging currently enabled?
* <p>
* Call this method to prevent having to perform expensive operations
* (for example, <code>String</code> concatenation)
* when the log level is more than info. </p>
* when the log level is more than info.
*
* @return true if info is enabled in the underlying logger.
*/
public boolean isInfoEnabled();
/**
* <p> Is trace logging currently enabled? </p>
*
* <p> Call this method to prevent having to perform expensive operations
* Is trace logging currently enabled?
* <p>
* Call this method to prevent having to perform expensive operations
* (for example, <code>String</code> concatenation)
* when the log level is more than trace. </p>
* when the log level is more than trace.
*
* @return true if trace is enabled in the underlying logger.
*/
public boolean isTraceEnabled();
/**
* <p> Is warn logging currently enabled? </p>
*
* <p> Call this method to prevent having to perform expensive operations
* Is warn logging currently enabled?
* <p>
* Call this method to prevent having to perform expensive operations
* (for example, <code>String</code> concatenation)
* when the log level is more than warn. </p>
* when the log level is more than warn.
*
* @return true if warn is enabled in the underlying logger.
*/
public boolean isWarnEnabled();
// -------------------------------------------------------- Logging Methods
/**
* <p> Log a message with trace log level. </p>
* Log a message with trace log level.
*
* @param message log this message
*/
public void trace(Object message);
/**
* <p> Log an error with trace log level. </p>
* Log an error with trace log level.
*
* @param message log this message
* @param t log this cause
*/
public void trace(Object message, Throwable t);
/**
* <p> Log a message with debug log level. </p>
* Log a message with debug log level.
*
* @param message log this message
*/
public void debug(Object message);
/**
* <p> Log an error with debug log level. </p>
* Log an error with debug log level.
*
* @param message log this message
* @param t log this cause
*/
public void debug(Object message, Throwable t);
/**
* <p> Log a message with info log level. </p>
* Log a message with info log level.
*
* @param message log this message
*/
public void info(Object message);
/**
* <p> Log an error with info log level. </p>
* Log an error with info log level.
*
* @param message log this message
* @param t log this cause
*/
public void info(Object message, Throwable t);
/**
* <p> Log a message with warn log level. </p>
* Log a message with warn log level.
*
* @param message log this message
*/
public void warn(Object message);
/**
* <p> Log an error with warn log level. </p>
* Log an error with warn log level.
*
* @param message log this message
* @param t log this cause
*/
public void warn(Object message, Throwable t);
/**
* <p> Log a message with error log level. </p>
* Log a message with error log level.
*
* @param message log this message
*/
public void error(Object message);
/**
* <p> Log an error with error log level. </p>
* Log an error with error log level.
*
* @param message log this message
* @param t log this cause
@@ -227,7 +207,7 @@ public interface Log {
/**
* <p> Log a message with fatal log level. </p>
* Log a message with fatal log level.
*
* @param message log this message
*/
@@ -235,12 +215,10 @@ public interface Log {
/**
* <p> Log an error with fatal log level. </p>
* Log an error with fatal log level.
*
* @param message log this message
* @param t log this cause
*/
public void fatal(Object message, Throwable t);
}

23
src/java/org/apache/commons/logging/LogConfigurationException.java
View File

@@ -17,40 +17,32 @@
package org.apache.commons.logging;
/**
* <p>An exception that is thrown only if a suitable <code>LogFactory</code>
* An exception that is thrown only if a suitable <code>LogFactory</code>
* or <code>Log</code> instance cannot be created by the corresponding
* factory methods.</p>
* factory methods.
*
* @author Craig R. McClanahan
* @version $Id$
*/
public class LogConfigurationException extends RuntimeException {
/**
* Construct a new exception with <code>null</code> as its detail message.
*/
public LogConfigurationException() {
super();
}
/**
* Construct a new exception with the specified detail message.
*
* @param message The detail message
*/
public LogConfigurationException(String message) {
super(message);
}
/**
* Construct a new exception with the specified cause and a derived
* detail message.
@@ -58,12 +50,9 @@ public class LogConfigurationException extends RuntimeException {
* @param cause The underlying cause
*/
public LogConfigurationException(Throwable cause) {
this(cause == null ? null : cause.toString(), cause);
}
/**
* Construct a new exception with the specified detail message and cause.
*
@@ -71,27 +60,19 @@ public class LogConfigurationException extends RuntimeException {
* @param cause The underlying cause
*/
public LogConfigurationException(String message, Throwable cause) {
super(message + " (Caused by " + cause + ")");
this.cause = cause; // Two-argument version requires JDK 1.4 or later
}
/**
* The underlying cause of this exception.
*/
protected Throwable cause = null;
/**
* Return the underlying cause of this exception (if any).
*/
public Throwable getCause() {
return this.cause;
}
}

104
src/java/org/apache/commons/logging/LogFactory.java
View File

@@ -17,7 +17,6 @@
package org.apache.commons.logging;
import java.io.BufferedReader;
import java.io.FileOutputStream;
import java.io.IOException;
@@ -34,15 +33,14 @@ import java.util.Enumeration;
import java.util.Hashtable;
import java.util.Properties;
/**
* <p>Factory for creating {@link Log} instances, with discovery and
* Factory for creating {@link Log} instances, with discovery and
* configuration features similar to that employed by standard Java APIs
* such as JAXP.</p>
*
* <p><strong>IMPLEMENTATION NOTE</strong> - This implementation is heavily
* such as JAXP.
* <p>
* <strong>IMPLEMENTATION NOTE</strong> - This implementation is heavily
* based on the SAXParserFactory and DocumentBuilderFactory implementations
* (corresponding to the JAXP pluggability APIs) found in Apache Xerces.</p>
* (corresponding to the JAXP pluggability APIs) found in Apache Xerces.
*
* @author Craig R. McClanahan
* @author Costin Manolache
@@ -75,7 +73,6 @@ public abstract class LogFactory {
// lib and JCL have the necessary permissions even when the untrusted
// caller does not. That's a pretty hard route to exploit though.
// ----------------------------------------------------- Manifest Constants
/**
@@ -98,26 +95,22 @@ public abstract class LogFactory {
* class name. This can be used as a system property, or as an entry in a
* configuration properties file.
*/
public static final String FACTORY_PROPERTY =
"org.apache.commons.logging.LogFactory";
public static final String FACTORY_PROPERTY = "org.apache.commons.logging.LogFactory";
/**
* The fully qualified class name of the fallback <code>LogFactory</code>
* implementation class to use, if no other can be found.
*/
public static final String FACTORY_DEFAULT =
"org.apache.commons.logging.impl.LogFactoryImpl";
public static final String FACTORY_DEFAULT = "org.apache.commons.logging.impl.LogFactoryImpl";
/**
* The name (<code>commons-logging.properties</code>) of the properties file to search for.
*/
public static final String FACTORY_PROPERTIES =
"commons-logging.properties";
public static final String FACTORY_PROPERTIES = "commons-logging.properties";
/**
* JDK1.3+ <a href="http://java.sun.com/j2se/1.3/docs/guide/jar/jar.html#Service%20Provider">
* 'Service Provider' specification</a>.
*
*/
protected static final String SERVICE_ID =
"META-INF/services/org.apache.commons.logging.LogFactory";
@@ -192,6 +185,7 @@ public abstract class LogFactory {
*/
public static final String HASHTABLE_IMPLEMENTATION_PROPERTY =
"org.apache.commons.logging.LogFactory.HashtableImpl";
/** Name used to load the weak hashtable implementation by names */
private static final String WEAK_HASHTABLE_CLASSNAME =
"org.apache.commons.logging.impl.WeakHashtable";
@@ -207,7 +201,6 @@ public abstract class LogFactory {
// ----------------------------------------------------------- Constructors
/**
* Protected constructor that is not available for public use.
*/
@@ -216,7 +209,6 @@ public abstract class LogFactory {
// --------------------------------------------------------- Public Methods
/**
* Return the configuration attribute with the specified name (if any),
* or <code>null</code> if there is no such attribute.
@@ -225,7 +217,6 @@ public abstract class LogFactory {
*/
public abstract Object getAttribute(String name);
/**
* Return an array containing the names of all currently defined
* configuration attributes. If there are no such attributes, a zero
@@ -233,41 +224,38 @@ public abstract class LogFactory {
*/
public abstract String[] getAttributeNames();
/**
* Convenience method to derive a name from the specified class and
* call <code>getInstance(String)</code> with it.
*
* @param clazz Class for which a suitable Log name will be derived
*
* @exception LogConfigurationException if a suitable <code>Log</code>
* @throws LogConfigurationException if a suitable <code>Log</code>
* instance cannot be returned
*/
public abstract Log getInstance(Class clazz)
throws LogConfigurationException;
/**
* <p>Construct (if necessary) and return a <code>Log</code> instance,
* using the factory's current set of configuration attributes.</p>
*
* <p><strong>NOTE</strong> - Depending upon the implementation of
* Construct (if necessary) and return a <code>Log</code> instance,
* using the factory's current set of configuration attributes.
* <p>
* <strong>NOTE</strong> - Depending upon the implementation of
* the <code>LogFactory</code> you are using, the <code>Log</code>
* instance you are returned may or may not be local to the current
* application, and may or may not be returned again on a subsequent
* call with the same name argument.</p>
* call with the same name argument.
*
* @param name Logical name of the <code>Log</code> instance to be
* returned (the meaning of this name is only known to the underlying
* logging implementation that is being wrapped)
*
* @exception LogConfigurationException if a suitable <code>Log</code>
* @throws LogConfigurationException if a suitable <code>Log</code>
* instance cannot be returned
*/
public abstract Log getInstance(String name)
throws LogConfigurationException;
/**
* Release any internal references to previously created {@link Log}
* instances returned by this factory. This is useful in environments
@@ -277,7 +265,6 @@ public abstract class LogFactory {
*/
public abstract void release();
/**
* Remove any configuration attribute associated with the specified name.
* If there is no such attribute, no action is taken.
@@ -286,7 +273,6 @@ public abstract class LogFactory {
*/
public abstract void removeAttribute(String name);
/**
* Set the configuration attribute with the specified name. Calling
* this with a <code>null</code> value is equivalent to calling
@@ -298,10 +284,8 @@ public abstract class LogFactory {
*/
public abstract void setAttribute(String name, Object value);
// ------------------------------------------------------- Static Variables
/**
* The previously constructed <code>LogFactory</code> instances, keyed by
* the <code>ClassLoader</code> with which it was created.
@@ -377,7 +361,6 @@ public abstract class LogFactory {
return result;
}
// --------------------------------------------------------- Static Methods
/** Utility method to safely trim a string. */
@@ -389,9 +372,10 @@ public abstract class LogFactory {
}
/**
* <p>Construct (if necessary) and return a <code>LogFactory</code>
* Construct (if necessary) and return a <code>LogFactory</code>
* instance, using the following ordered lookup procedure to determine
* the name of the implementation class to be loaded.</p>
* the name of the implementation class to be loaded.
* <p>
* <ul>
* <li>The <code>org.apache.commons.logging.LogFactory</code> system
* property.</li>
@@ -404,18 +388,17 @@ public abstract class LogFactory {
* <li>Fall back to a default implementation class
* (<code>org.apache.commons.logging.impl.LogFactoryImpl</code>).</li>
* </ul>
*
* <p><em>NOTE</em> - If the properties file method of identifying the
* <p>
* <em>NOTE</em> - If the properties file method of identifying the
* <code>LogFactory</code> implementation class is utilized, all of the
* properties defined in this file will be set as configuration attributes
* on the corresponding <code>LogFactory</code> instance.</p>
*
* <p><em>NOTE</em> - In a multi-threaded environment it is possible
* on the corresponding <code>LogFactory</code> instance.
* <p>
* <em>NOTE</em> - In a multi-threaded environment it is possible
* that two different instances will be returned for the same
* classloader environment.
* </p>
*
* @exception LogConfigurationException if the implementation class is not
* @throws LogConfigurationException if the implementation class is not
* available or cannot be instantiated.
*/
public static LogFactory getFactory() throws LogConfigurationException {
@@ -527,7 +510,6 @@ public abstract class LogFactory {
throw e;
}
// Second, try to find a service by using the JDK1.3 class
// discovery mechanism, which involves putting a file with the name
// of an interface class in the META-INF/services directory, where the
@@ -591,7 +573,6 @@ public abstract class LogFactory {
}
}
// Third try looking into the properties file read earlier (if found)
if (factory == null) {
@@ -627,7 +608,6 @@ public abstract class LogFactory {
}
}
// Fourth, try the fallback implementation class
if (factory == null) {
@@ -669,14 +649,13 @@ public abstract class LogFactory {
return factory;
}
/**
* Convenience method to return a named logger, without the application
* having to care about factories.
*
* @param clazz Class from which a log name will be derived
*
* @exception LogConfigurationException if a suitable <code>Log</code>
* @throws LogConfigurationException if a suitable <code>Log</code>
* instance cannot be returned
*/
public static Log getLog(Class clazz)
@@ -686,7 +665,6 @@ public abstract class LogFactory {
}
/**
* Convenience method to return a named logger, without the application
* having to care about factories.
@@ -695,7 +673,7 @@ public abstract class LogFactory {
* returned (the meaning of this name is only known to the underlying
* logging implementation that is being wrapped)
*
* @exception LogConfigurationException if a suitable <code>Log</code>
* @throws LogConfigurationException if a suitable <code>Log</code>
* instance cannot be returned
*/
public static Log getLog(String name)
@@ -705,7 +683,6 @@ public abstract class LogFactory {
}
/**
* Release any internal references to previously created {@link LogFactory}
* instances that have been associated with the specified class loader
@@ -738,7 +715,6 @@ public abstract class LogFactory {
}
/**
* Release any internal references to previously created {@link LogFactory}
* instances, after calling the instance method <code>release()</code> on
@@ -748,7 +724,6 @@ public abstract class LogFactory {
* garbage collection.
*/
public static void releaseAll() {
if (isDiagnosticsEnabled()) {
logDiagnostic("Releasing factory for all classloaders.");
}
@@ -767,10 +742,8 @@ public abstract class LogFactory {
nullClassLoaderFactory = null;
}
}
}
// ------------------------------------------------------ Protected Methods
/**
@@ -858,8 +831,7 @@ public abstract class LogFactory {
* @throws SecurityException if the current java security policy doesn't
* allow this class to access the context classloader.
*/
private static ClassLoader getContextClassLoaderInternal()
throws LogConfigurationException {
private static ClassLoader getContextClassLoaderInternal() throws LogConfigurationException {
return (ClassLoader)AccessController.doPrivileged(
new PrivilegedAction() {
public Object run() {
@@ -1054,8 +1026,7 @@ public abstract class LogFactory {
protected static LogFactory newFactory(final String factoryClass,
final ClassLoader classLoader,
final ClassLoader contextClassLoader)
throws LogConfigurationException
{
throws LogConfigurationException {
// Note that any unchecked exceptions thrown by the createFactory
// method will propagate out of this method; in particular a
// ClassCastException can be thrown.
@@ -1117,7 +1088,6 @@ public abstract class LogFactory {
* @since 1.1
*/
protected static Object createFactory(String factoryClass, ClassLoader classLoader) {
// This will be used to diagnose bad configurations
// and allow a useful message to be sent to the user
Class logFactoryClass = null;
@@ -1348,9 +1318,7 @@ public abstract class LogFactory {
* been granted permission for that operation. In this case, we need to
* run the operation using an AccessController.
*/
private static InputStream getResourceAsStream(final ClassLoader loader,
final String name)
{
private static InputStream getResourceAsStream(final ClassLoader loader, final String name) {
return (InputStream)AccessController.doPrivileged(
new PrivilegedAction() {
public Object run() {
@@ -1376,9 +1344,7 @@ public abstract class LogFactory {
* hasMoreElements method returns false (ie an "empty" enumeration).
* If resources could not be listed for some reason, null is returned.
*/
private static Enumeration getResources(final ClassLoader loader,
final String name)
{
private static Enumeration getResources(final ClassLoader loader, final String name) {
PrivilegedAction action =
new PrivilegedAction() {
public Object run() {
@@ -1413,7 +1379,7 @@ public abstract class LogFactory {
* succeed when this jarfile is privileged but the caller is not.
* This method must therefore remain private to avoid security issues.
* <p>
* Null is returned if the URL cannot be opened.
* {@code Null} is returned if the URL cannot be opened.
*/
private static Properties getProperties(final URL url) {
PrivilegedAction action =
@@ -1476,9 +1442,7 @@ public abstract class LogFactory {
* webapps. Webapps can also use explicit priorities to override a configuration
* file in the shared classpath if needed.
*/
private static final Properties getConfigurationFile(
ClassLoader classLoader, String fileName) {
private static final Properties getConfigurationFile(ClassLoader classLoader, String fileName) {
Properties props = null;
double priority = 0.0;
URL propsUrl = null;
@@ -1571,7 +1535,7 @@ public abstract class LogFactory {
* info to access data that should not be available to it.
*/
private static String getSystemProperty(final String key, final String def)
throws SecurityException {
throws SecurityException {
return (String) AccessController.doPrivileged(
new PrivilegedAction() {
public Object run() {

63
src/java/org/apache/commons/logging/LogSource.java
View File

@@ -17,13 +17,11 @@
package org.apache.commons.logging;
import java.lang.reflect.Constructor;
import java.util.Hashtable;
import org.apache.commons.logging.impl.NoOpLog;
/**
* <p>Factory for creating {@link Log} instances. Applications should call
* the <code>makeNewLogInstance()</code> method to instantiate new instances
@@ -70,7 +68,6 @@ public class LogSource {
/** Constructor for current log class */
static protected Constructor logImplctor = null;
// ----------------------------------------------------- Class Initializers
static {
@@ -134,24 +131,19 @@ public class LogSource {
}
// ------------------------------------------------------------ Constructor
/** Don't allow others to create instances */
/** Don't allow others to create instances. */
private LogSource() {
}
// ---------------------------------------------------------- Class Methods
/**
* Set the log implementation/log implementation factory
* by the name of the class. The given class
* must implement {@link Log}, and provide a constructor that
* takes a single {@link String} argument (containing the name
* of the log).
* by the name of the class. The given class must implement {@link Log},
* and provide a constructor that takes a single {@link String} argument
* (containing the name of the log).
*/
static public void setLogImplementation(String classname) throws
LinkageError,
@@ -167,12 +159,10 @@ public class LogSource {
}
}
/**
* Set the log implementation/log implementation factory
* by class. The given class must implement {@link Log},
* and provide a constructor that takes a single {@link String}
* argument (containing the name of the log).
* Set the log implementation/log implementation factory by class.
* The given class must implement {@link Log}, and provide a constructor
* that takes a single {@link String} argument (containing the name of the log).
*/
static public void setLogImplementation(Class logclass) throws
LinkageError, ExceptionInInitializerError,
@@ -182,8 +172,7 @@ public class LogSource {
logImplctor = logclass.getConstructor(argtypes);
}
/** Get a <code>Log</code> instance by class name */
/** Get a <code>Log</code> instance by class name. */
static public Log getInstance(String name) {
Log log = (Log) logs.get(name);
if (null == log) {
@@ -193,34 +182,25 @@ public class LogSource {
return log;
}
/** Get a <code>Log</code> instance by class */
/** Get a <code>Log</code> instance by class. */
static public Log getInstance(Class clazz) {
return getInstance(clazz.getName());
}
/**
* Create a new {@link Log} implementation, based
* on the given <i>name</i>.
* Create a new {@link Log} implementation, based on the given <i>name</i>.
* <p>
* The specific {@link Log} implementation returned
* is determined by the value of the
* <tt>org.apache.commons.logging.log</tt> property.
* The value of <tt>org.apache.commons.logging.log</tt> may be set to
* the fully specified name of a class that implements
* the {@link Log} interface. This class must also
* have a public constructor that takes a single
* {@link String} argument (containing the <i>name</i>
* of the {@link Log} to be constructed.
* The specific {@link Log} implementation returned is determined by the
* value of the <tt>org.apache.commons.logging.log</tt> property. The value
* of <tt>org.apache.commons.logging.log</tt> may be set to the fully specified
* name of a class that implements the {@link Log} interface. This class must
* also have a public constructor that takes a single {@link String} argument
* (containing the <i>name</i> of the {@link Log} to be constructed.
* <p>
* When <tt>org.apache.commons.logging.log</tt> is not set,
* or when no corresponding class can be found,
* this method will return a Log4JLogger
* if the log4j Logger class is
* available in the {@link LogSource}'s classpath, or a
* Jdk14Logger if we are on a JDK 1.4 or later system, or
* NoOpLog if neither of the above conditions is true.
* When <tt>org.apache.commons.logging.log</tt> is not set, or when no corresponding
* class can be found, this method will return a Log4JLogger if the log4j Logger
* class is available in the {@link LogSource}'s classpath, or a Jdk14Logger if we
* are on a JDK 1.4 or later system, or NoOpLog if neither of the above conditions is true.
*
* @param name the log name (or category)
*/
@@ -240,7 +220,6 @@ public class LogSource {
}
/**
* Returns a {@link String} array containing the names of
* all logs known to me.
@@ -248,6 +227,4 @@ public class LogSource {
static public String[] getLogNames() {
return (String[]) logs.keySet().toArray(new String[logs.size()]);
}
}