001package org.apache.maven.doxia.logging;
002
003/*
004 * Licensed to the Apache Software Foundation (ASF) under one
005 * or more contributor license agreements.  See the NOTICE file
006 * distributed with this work for additional information
007 * regarding copyright ownership.  The ASF licenses this file
008 * to you under the Apache License, Version 2.0 (the
009 * "License"); you may not use this file except in compliance
010 * with the License.  You may obtain a copy of the License at
011 *
012 *  http://www.apache.org/licenses/LICENSE-2.0
013 *
014 * Unless required by applicable law or agreed to in writing,
015 * software distributed under the License is distributed on an
016 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
017 * KIND, either express or implied.  See the License for the
018 * specific language governing permissions and limitations
019 * under the License.
020 */
021
022/**
023 * This interface supplies the API for providing feedback to the user from
024 * a Parser or Sink, using standard <code>Doxia</code> channels.
025 * <br>
026 * There should be no big surprises here, although you may notice that the methods accept
027 * <code>java.lang.CharSequence</code> rather than <code>java.lang.String</code>. This is provided mainly as a
028 * convenience, to enable developers to pass things like <code>java.lang.StringBuilder</code> directly into the logger,
029 * rather than formatting first by calling <code>toString()</code>.
030 * <br>
031 * Based on <code>org.apache.maven.plugin.logging.Log</code>.
032 *
033 * @author jdcasey
034 * @author ltheussl
035 * @version $Id$
036 * @since 1.1
037 */
038public interface Log
039{
040    /** Typecode for debugging messages. */
041    int LEVEL_DEBUG = 0;
042
043    /** Typecode for informational messages. */
044    int LEVEL_INFO = 1;
045
046    /** Typecode for warning messages. */
047    int LEVEL_WARN = 2;
048
049    /** Typecode for error messages. */
050    int LEVEL_ERROR = 3;
051
052    /** Typecode for fatal error messages. */
053    int LEVEL_FATAL = 4;
054
055    /** Typecode for disabled log levels. */
056    int LEVEL_DISABLED = 5;
057
058    /**
059     * Set the current log level.
060     *
061     * @param level the log level to set.
062     */
063    void setLogLevel( int level );
064
065    /**
066     * <p>isDebugEnabled.</p>
067     *
068     * @return true if the <b>debug</b> error level is enabled.
069     */
070    boolean isDebugEnabled();
071
072    /**
073     * Send a message to the user in the <b>debug</b> error level.
074     *
075     * @param content the message to log.
076     */
077    void debug( CharSequence content );
078
079    /**
080     * Send a message (and accompanying exception) to the user in the <b>debug</b> error level.
081     * <br>
082     * The error's stacktrace will be output when this error level is enabled.
083     *
084     * @param content the message to log.
085     * @param error the error to log.
086     */
087    void debug( CharSequence content, Throwable error );
088
089    /**
090     * Send an exception to the user in the <b>debug</b> error level.
091     * <br>
092     * The stack trace for this exception will be output when this error level is enabled.
093     *
094     * @param error the error to log.
095     */
096    void debug( Throwable error );
097
098    /**
099     * <p>isInfoEnabled.</p>
100     *
101     * @return true if the <b>info</b> error level is enabled.
102     */
103    boolean isInfoEnabled();
104
105    /**
106     * Send a message to the user in the <b>info</b> error level.
107     *
108     * @param content the message to log.
109     */
110    void info( CharSequence content );
111
112    /**
113     * Send a message (and accompanying exception) to the user in the <b>info</b> error level.
114     * <br>
115     * The error's stacktrace will be output when this error level is enabled.
116     *
117     * @param content the message to log.
118     * @param error the error to log.
119     */
120    void info( CharSequence content, Throwable error );
121
122    /**
123     * Send an exception to the user in the <b>info</b> error level.
124     * <br>
125     * The stack trace for this exception will be output when this error level is enabled.
126     *
127     * @param error the error to log.
128     */
129    void info( Throwable error );
130
131    /**
132     * <p>isWarnEnabled.</p>
133     *
134     * @return true if the <b>warn</b> error level is enabled.
135     */
136    boolean isWarnEnabled();
137
138    /**
139     * Send a message to the user in the <b>warn</b> error level.
140     *
141     * @param content the message to log.
142     */
143    void warn( CharSequence content );
144
145    /**
146     * Send a message (and accompanying exception) to the user in the <b>warn</b> error level.
147     * <br>
148     * The error's stacktrace will be output when this error level is enabled.
149     *
150     * @param content the message to log.
151     * @param error the error to log.
152     */
153    void warn( CharSequence content, Throwable error );
154
155    /**
156     * Send an exception to the user in the <b>warn</b> error level.
157     * <br>
158     * The stack trace for this exception will be output when this error level is enabled.
159     *
160     * @param error the error to log.
161     */
162    void warn( Throwable error );
163
164    /**
165     * <p>isErrorEnabled.</p>
166     *
167     * @return true if the <b>error</b> error level is enabled.
168     */
169    boolean isErrorEnabled();
170
171    /**
172     * Send a message to the user in the <b>error</b> error level.
173     *
174     * @param content the message to log.
175     */
176    void error( CharSequence content );
177
178    /**
179     * Send a message (and accompanying exception) to the user in the <b>error</b> error level.
180     * <br>
181     * The error's stacktrace will be output when this error level is enabled.
182     *
183     * @param content the message to log.
184     * @param error the error to log.
185     */
186    void error( CharSequence content, Throwable error );
187
188    /**
189     * Send an exception to the user in the <b>error</b> error level.
190     * <br>
191     * The stack trace for this exception will be output when this error level is enabled.
192     *
193     * @param error the error to log.
194     */
195    void error( Throwable error );
196}