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