1   /**
2    * Logback: the reliable, generic, fast and flexible logging framework.
3    * Copyright (C) 1999-2015, QOS.ch. All rights reserved.
4    *
5    * This program and the accompanying materials are dual-licensed under
6    * either the terms of the Eclipse Public License v1.0 as published by
7    * the Eclipse Foundation
8    *
9    *   or (per the licensee's choosing)
10   *
11   * under the terms of the GNU Lesser General Public License version 2.1
12   * as published by the Free Software Foundation.
13   */
14  package ch.qos.logback.core;
15  
16  import ch.qos.logback.core.spi.ContextAware;
17  import ch.qos.logback.core.spi.FilterAttachable;
18  import ch.qos.logback.core.spi.LifeCycle;
19  
20  /**
21   * Contract for components responsible for delivering logging events to their
22   * final destination (console, file, remote server, etc.).
23   *
24   * <p>Implementations are typically configured and managed by a LoggerContext.
25   * The type parameter E represents the event type the appender consumes (for
26   * example a log event object). Implementations should honor lifecycle methods
27   * from {@link LifeCycle} and may be {@link ContextAware} and
28   * {@link FilterAttachable} to support contextual information and filtering.</p>
29   *
30   * <p>Concurrency: appenders are generally invoked by multiple threads. Implementations
31   * must ensure thread-safety where applicable (for example when writing to shared
32   * resources). The {@link #doAppend(Object)} method may be called concurrently.</p>
33   *
34   * @param <E> the event type accepted by this appender
35   */
36  public interface Appender<E> extends LifeCycle, ContextAware, FilterAttachable<E> {
37  
38      /**
39       * Get the name of this appender. The name uniquely identifies the appender
40       * within its context and is used for configuration and lookup.
41       *
42       * @return the appender name, or {@code null} if not set
43       */
44      String getName();
45  
46      /**
47       * This is where an appender accomplishes its work: format and deliver the
48       * provided event to the appender's destination.
49       *
50       * <p>Implementations should apply any configured filters before outputting
51       * the event. Implementations should avoid throwing runtime exceptions;
52       * if an error occurs that cannot be handled internally, a {@link LogbackException}
53       * (or a subtype) may be thrown to indicate a failure during append.</p>
54       *
55       * @param event the event to append; may not be {@code null}
56       * @throws LogbackException if the append fails in a way that needs to be
57       *                          propagated to the caller
58       */
59      void doAppend(E event) throws LogbackException;
60  
61      /**
62       * Set the name of this appender. The name is used by other components to
63       * identify and reference this appender (for example in configuration or for
64       * status messages).
65       *
66       * @param name the new name for this appender; may be {@code null} to unset
67       */
68      void setName(String name);
69  
70  }