001/*
002 * Copyright 2001-2004 The Apache Software Foundation.
003 *
004 * Licensed under the Apache License, Version 2.0 (the "License");
005 * you may not use this file except in compliance with the License.
006 * You may obtain a copy of the License at
007 *
008 *      http://www.apache.org/licenses/LICENSE-2.0
009 *
010 * Unless required by applicable law or agreed to in writing, software
011 * distributed under the License is distributed on an "AS IS" BASIS,
012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013 * See the License for the specific language governing permissions and
014 * limitations under the License.
015 */
016
017package org.apache.log4j;
018
019import org.apache.log4j.spi.Filter;
020import org.apache.log4j.spi.ErrorHandler;
021import org.apache.log4j.spi.LoggingEvent;
022
023/**
024 * Implement this interface for your own strategies for outputting log
025 * statements.
026 *
027 * @author Ceki Gülcü
028 */
029public interface Appender {
030
031    /**
032     * Add a filter to the end of the filter list.
033     *
034     * @since 0.9.0
035     */
036    void addFilter(Filter newFilter);
037
038    /**
039     * Returns the head Filter. The Filters are organized in a linked list
040     * and so all Filters on this Appender are available through the result.
041     *
042     * @return the head Filter or null, if no Filters are present
043     * @since 1.1
044     */
045    public Filter getFilter();
046
047    /**
048     * Clear the list of filters by removing all the filters in it.
049     *
050     * @since 0.9.0
051     */
052    public void clearFilters();
053
054    /**
055     * Release any resources allocated within the appender such as file
056     * handles, network connections, etc.
057     * 
058     * <p>It is a programming error to append to a closed appender.
059     *
060     * @since 0.8.4
061     */
062    public void close();
063
064    /**
065     * Log in <code>Appender</code> specific way. When appropriate,
066     * Loggers will call the <code>doAppend</code> method of appender
067     * implementations in order to log.
068     */
069    public void doAppend(LoggingEvent event);
070
071    /**
072     * Get the name of this appender. The name uniquely identifies the
073     * appender.
074     */
075    public String getName();
076
077    /**
078     * Set the {@link ErrorHandler} for this appender.
079     *
080     * @since 0.9.0
081     */
082    public void setErrorHandler(ErrorHandler errorHandler);
083
084    /**
085     * Returns the {@link ErrorHandler} for this appender.
086     *
087     * @since 1.1
088     */
089    public ErrorHandler getErrorHandler();
090
091    /**
092     * Set the {@link Layout} for this appender.
093     *
094     * @since 0.8.1
095     */
096    public void setLayout(Layout layout);
097
098    /**
099     * Returns this appenders layout.
100     *
101     * @since 1.1
102     */
103    public Layout getLayout();
104
105    /**
106     * Set the name of this appender. The name is used by other
107     * components to identify this appender.
108     *
109     * @since 0.8.1
110     */
111    public void setName(String name);
112
113    /**
114     * Configurators call this method to determine if the appender
115     * requires a layout. If this method returns <code>true</code>,
116     * meaning that layout is required, then the configurator will
117     * configure a layout using the configuration information at its
118     * disposal.  If this method returns <code>false</code>, meaning that
119     * a layout is not required, then layout configuration will be
120     * skipped even if there is available layout configuration
121     * information at the disposal of the configurator.
122     * 
123     * <p>In the rather exceptional case, where the appender
124     * implementation admits a layout but can also work without it, then
125     * the appender should return <code>true</code>.
126     *
127     * @since 0.8.4
128     */
129    public boolean requiresLayout();
130}