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     * <p>It is a programming error to append to a closed appender.
058     *
059     * @since 0.8.4
060     */
061    void close();
062
063    /**
064     * Log in <code>Appender</code> specific way. When appropriate,
065     * Loggers will call the <code>doAppend</code> method of appender
066     * implementations in order to log.
067     * @param event The LoggingEvent.
068     */
069    void doAppend(LoggingEvent event);
070
071
072    /**
073     * Get the name of this appender.
074     *
075     * @return name, may be null.
076     */
077    String getName();
078
079
080    /**
081     * Set the {@link ErrorHandler} for this appender.
082     * @param errorHandler The error handler.
083     *
084     * @since 0.9.0
085     */
086    void setErrorHandler(ErrorHandler errorHandler);
087
088    /**
089     * Returns the {@link ErrorHandler} for this appender.
090     * @return The error handler.
091     *
092     * @since 1.1
093     */
094    ErrorHandler getErrorHandler();
095
096    /**
097     * Set the {@link Layout} for this appender.
098     * @param layout The Layout.
099     *
100     * @since 0.8.1
101     */
102    void setLayout(Layout layout);
103
104    /**
105     * Returns this appenders layout.
106     * @return the Layout.
107     *
108     * @since 1.1
109     */
110    Layout getLayout();
111
112
113    /**
114     * Set the name of this appender. The name is used by other
115     * components to identify this appender.
116     * @param name The appender name.
117     *
118     * @since 0.8.1
119     */
120    void setName(String name);
121
122    /**
123     * Configurators call this method to determine if the appender
124     * requires a layout. If this method returns {@code true},
125     * meaning that layout is required, then the configurator will
126     * configure an layout using the configuration information at its
127     * disposal.  If this method returns {@code false}, meaning that
128     * a layout is not required, then layout configuration will be
129     * skipped even if there is available layout configuration
130     * information at the disposal of the configurator..
131     * <p/>
132     * <p>In the rather exceptional case, where the appender
133     * implementation admits a layout but can also work without it, then
134     * the appender should return {@code true}.
135     * @return true if a Layout is required.
136     *
137     * @since 0.8.4
138     */
139    boolean requiresLayout();
140}
141