001/**
002 * Logback: the reliable, generic, fast and flexible logging framework.
003 * Copyright (C) 1999-2015, QOS.ch. All rights reserved.
004 *
005 * This program and the accompanying materials are dual-licensed under
006 * either the terms of the Eclipse Public License v1.0 as published by
007 * the Eclipse Foundation
008 *
009 *   or (per the licensee's choosing)
010 *
011 * under the terms of the GNU Lesser General Public License version 2.1
012 * as published by the Free Software Foundation.
013 */
014package ch.qos.logback.core;
015
016import ch.qos.logback.core.spi.ContextAware;
017import ch.qos.logback.core.spi.FilterAttachable;
018import ch.qos.logback.core.spi.LifeCycle;
019
020/**
021 * Contract for components responsible for delivering logging events to their
022 * final destination (console, file, remote server, etc.).
023 *
024 * <p>Implementations are typically configured and managed by a LoggerContext.
025 * The type parameter E represents the event type the appender consumes (for
026 * example a log event object). Implementations should honor lifecycle methods
027 * from {@link LifeCycle} and may be {@link ContextAware} and
028 * {@link FilterAttachable} to support contextual information and filtering.</p>
029 *
030 * <p>Concurrency: appenders are generally invoked by multiple threads. Implementations
031 * must ensure thread-safety where applicable (for example when writing to shared
032 * resources). The {@link #doAppend(Object)} method may be called concurrently.</p>
033 *
034 * @param <E> the event type accepted by this appender
035 */
036public interface Appender<E> extends LifeCycle, ContextAware, FilterAttachable<E> {
037
038    /**
039     * Get the name of this appender. The name uniquely identifies the appender
040     * within its context and is used for configuration and lookup.
041     *
042     * @return the appender name, or {@code null} if not set
043     */
044    String getName();
045
046    /**
047     * This is where an appender accomplishes its work: format and deliver the
048     * provided event to the appender's destination.
049     *
050     * <p>Implementations should apply any configured filters before outputting
051     * the event. Implementations should avoid throwing runtime exceptions;
052     * if an error occurs that cannot be handled internally, a {@link LogbackException}
053     * (or a subtype) may be thrown to indicate a failure during append.</p>
054     *
055     * @param event the event to append; may not be {@code null}
056     * @throws LogbackException if the append fails in a way that needs to be
057     *                          propagated to the caller
058     */
059    void doAppend(E event) throws LogbackException;
060
061    /**
062     * Set the name of this appender. The name is used by other components to
063     * identify and reference this appender (for example in configuration or for
064     * status messages).
065     *
066     * @param name the new name for this appender; may be {@code null} to unset
067     */
068    void setName(String name);
069
070}