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.logging.log4j.core; 018 019import java.io.Serializable; 020 021/** 022 * Appends {@link LogEvent}s. An Appender can contain a {@link Layout} if applicable as well 023 * as an {@link ErrorHandler}. Typical Appender implementations coordinate with an 024 * implementation of {@link org.apache.logging.log4j.core.appender.AbstractManager} to handle external resources 025 * such as streams, connections, and other shared state. As Appenders are plugins, concrete implementations need to 026 * be annotated with {@link org.apache.logging.log4j.core.config.plugins.Plugin} and need to provide a static 027 * factory method annotated with {@link org.apache.logging.log4j.core.config.plugins.PluginFactory}. 028 * 029 * <p>Most core plugins are written using a related Manager class that handle the actual task of serializing a 030 * {@link LogEvent} to some output location. For instance, many Appenders can take 031 * advantage of the {@link org.apache.logging.log4j.core.appender.OutputStreamManager} class.</p> 032 * 033 * <p>It is recommended that Appenders don't do any heavy lifting since there can be many instances of the class 034 * being used at any given time. When resources require locking (e.g., through {@link java.nio.channels.FileLock}), 035 * it is important to isolate synchronized code to prevent concurrency issues.</p> 036 */ 037public interface Appender extends LifeCycle { 038 039 /** 040 * Logs a LogEvent using whatever logic this Appender wishes to use. It is typically recommended to use a 041 * bridge pattern not only for the benefits from decoupling an Appender from its implementation, but it is also 042 * handy for sharing resources which may require some form of locking. 043 * 044 * @param event The LogEvent. 045 */ 046 void append(LogEvent event); 047 048 049 /** 050 * Get the name of this Appender. 051 * 052 * @return name, may be null. 053 */ 054 String getName(); 055 056 /** 057 * Returns the Layout used by this Appender if applicable. 058 * 059 * @return the Layout for this Appender or {@code null} if none is configured. 060 */ 061 Layout<? extends Serializable> getLayout(); 062 063 /** 064 * Some Appenders need to propagate exceptions back to the application. When {@code ignoreExceptions} is 065 * {@code false} the AppenderControl will allow the exception to percolate. 066 * 067 * @return {@code true} if exceptions will be logged but not thrown, {@code false} otherwise. 068 */ 069 boolean ignoreExceptions(); 070 071 /** 072 * Gets the {@link ErrorHandler} used for handling exceptions. 073 * 074 * @return the ErrorHandler for handling exceptions. 075 */ 076 ErrorHandler getHandler(); 077 078 /** 079 * Sets the {@link ErrorHandler} used for handling exceptions. 080 * 081 * @param handler the ErrorHandler to use for handling exceptions. 082 */ 083 void setHandler(ErrorHandler handler); 084}