001: // Jericho HTML Parser - Java based library for analysing and manipulating HTML
002: // Version 2.5
003: // Copyright (C) 2007 Martin Jericho
004: // http://jerichohtml.sourceforge.net/
005: //
006: // This library is free software; you can redistribute it and/or
007: // modify it under the terms of either one of the following licences:
008: //
009: // 1. The Eclipse Public License (EPL) version 1.0,
010: // included in this distribution in the file licence-epl-1.0.html
011: // or available at http://www.eclipse.org/legal/epl-v10.html
012: //
013: // 2. The GNU Lesser General Public License (LGPL) version 2.1 or later,
014: // included in this distribution in the file licence-lgpl-2.1.txt
015: // or available at http://www.gnu.org/licenses/lgpl.txt
016: //
017: // This library is distributed on an "AS IS" basis,
018: // WITHOUT WARRANTY OF ANY KIND, either express or implied.
019: // See the individual licence texts for more details.
020:
021: package au.id.jericho.lib.html;
022:
023: /**
024: * Defines the interface for a factory class to provide {@link Logger} instances for each {@link Source} object.
025: * <p>
026: * It is not usually necessary for users to create implementations of this interface, as
027: * several predefined instances are defined which provide the most commonly required {@link Logger} implementations.
028: * <p>
029: * By default, a <code>LoggerProvider</code> is chosen automatically according to the algorithm described in the static {@link Config#LoggerProvider} property.
030: * This automatic choice can be overridden by setting the {@link Config#LoggerProvider} property manually with an instance of this interface,
031: * but this is also usually not necessary.
032: */
033: public interface LoggerProvider {
034: /**
035: * A {@link LoggerProvider} implementation that disables all log messages.
036: */
037: public static final LoggerProvider DISABLED = LoggerProviderDisabled.INSTANCE;
038:
039: /**
040: * A {@link LoggerProvider} implementation that sends all log messages to the standard error output stream (<code>System.err</code>).
041: * <p>
042: * The implementation uses the following code to create each logger:<br />
043: * <code>new </code>{@link WriterLogger}<code>(new OutputStreamWriter(System.err),name)</code>
044: */
045: public static final LoggerProvider STDERR = LoggerProviderSTDERR.INSTANCE;
046:
047: /**
048: * A {@link LoggerProvider} implementation that wraps the standard <code>java.util.logging</code> system included in the Java SDK version 1.4 and above.
049: * <p>
050: * This is the default used if no other logging framework is detected. See the description of the static {@link Config#LoggerProvider} property for more details.
051: * <p>
052: * The following mapping of <a href="Logger.html#LoggingLevel">logging levels</a> is used:
053: * <table class="bordered" style="margin: 15px" cellspacing="0">
054: * <tr><th>{@link Logger} level<th><code>java.util.logging.Level</code>
055: * <tr><td>{@link Logger#error(String) ERROR}<td><code>SEVERE</code>
056: * <tr><td>{@link Logger#warn(String) WARN}<td><code>WARNING</code>
057: * <tr><td>{@link Logger#info(String) INFO}<td><code>INFO</code>
058: * <tr><td>{@link Logger#debug(String) DEBUG}<td><code>FINE</code>
059: * </table>
060: */
061: public static final LoggerProvider JAVA = LoggerProviderJava.INSTANCE;
062:
063: /**
064: * A {@link LoggerProvider} implementation that wraps the <a target="_blank" href="http://jakarta.apache.org/commons/logging/">Jakarta Commons Logging</a> (JCL) framework.
065: * <p>
066: * See the description of the static {@link Config#LoggerProvider} property for details on when this implementation is used as the default.
067: * <p>
068: * The following mapping of <a href="Logger.html#LoggingLevel">logging levels</a> is used:
069: * <table class="bordered" style="margin: 15px" cellspacing="0">
070: * <tr><th>{@link Logger} level<th><code>org.apache.commons.logging</code> level
071: * <tr><td>{@link Logger#error(String) ERROR}<td><code>error</code>
072: * <tr><td>{@link Logger#warn(String) WARN}<td><code>warn</code>
073: * <tr><td>{@link Logger#info(String) INFO}<td><code>info</code>
074: * <tr><td>{@link Logger#debug(String) DEBUG}<td><code>debug</code>
075: * </table>
076: */
077: public static final LoggerProvider JCL = LoggerProviderJCL.INSTANCE;
078:
079: /**
080: * A {@link LoggerProvider} implementation that wraps the <a target="_blank" href="http://logging.apache.org/log4j/">Apache Log4J</a> framework.
081: * <p>
082: * See the description of the static {@link Config#LoggerProvider} property for details on when this implementation is used as the default.
083: * <p>
084: * The following mapping of <a href="Logger.html#LoggingLevel">logging levels</a> is used:
085: * <table class="bordered" style="margin: 15px" cellspacing="0">
086: * <tr><th>{@link Logger} level<th><code>org.apache.log4j.Level</code>
087: * <tr><td>{@link Logger#error(String) ERROR}<td><code>ERROR</code>
088: * <tr><td>{@link Logger#warn(String) WARN}<td><code>WARN</code>
089: * <tr><td>{@link Logger#info(String) INFO}<td><code>INFO</code>
090: * <tr><td>{@link Logger#debug(String) DEBUG}<td><code>DEBUG</code>
091: * </table>
092: */
093: public static final LoggerProvider LOG4J = LoggerProviderLog4J.INSTANCE;
094:
095: /**
096: * A {@link LoggerProvider} implementation that wraps the <a target="_blank" href="http://www.slf4j.org/">SLF4J</a> framework.
097: * <p>
098: * See the description of the static {@link Config#LoggerProvider} property for details on when this implementation is used as the default.
099: * <p>
100: * The following mapping of <a href="Logger.html#LoggingLevel">logging levels</a> is used:
101: * <table class="bordered" style="margin: 15px" cellspacing="0">
102: * <tr><th>{@link Logger} level<th><code>org.slf4j.Logger</code> level
103: * <tr><td>{@link Logger#error(String) ERROR}<td><code>error</code>
104: * <tr><td>{@link Logger#warn(String) WARN}<td><code>warn</code>
105: * <tr><td>{@link Logger#info(String) INFO}<td><code>info</code>
106: * <tr><td>{@link Logger#debug(String) DEBUG}<td><code>debug</code>
107: * </table>
108: */
109: public static final LoggerProvider SLF4J = LoggerProviderSLF4J.INSTANCE;
110:
111: /**
112: * Creates a new {@link Logger} instance with the specified name.
113: * <p>
114: * The <code>name</code> argument is used by the underlying logging implementation, and is normally a dot-separated name based on
115: * the package name or class name of the subsystem.
116: * <p>
117: * The name used for all automatically created {@link Logger} instances is "<code>net.htmlparser.jericho</code>".
118: *
119: * @param name the name of the logger, the use of which is determined by the underlying logging implementation, may be <code>null</code>.
120: * @return a new {@link Logger} instance with the specified name.
121: */
122: Logger getLogger(String name);
123: }
|