View Javadoc

1   /*
2    * Licensed to the Apache Software Foundation (ASF) under one or more
3    * contributor license agreements. See the NOTICE file distributed with
4    * this work for additional information regarding copyright ownership.
5    * The ASF licenses this file to You under the Apache license, Version 2.0
6    * (the "License"); you may not use this file except in compliance with
7    * the License. You may obtain a copy of the License at
8    *
9    *      http://www.apache.org/licenses/LICENSE-2.0
10   *
11   * Unless required by applicable law or agreed to in writing, software
12   * distributed under the License is distributed on an "AS IS" BASIS,
13   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14   * See the license for the specific language governing permissions and
15   * limitations under the license.
16   */
17  package org.apache.logging.log4j.core;
18  
19  import java.io.Serializable;
20  
21  /**
22   * Appends log events. An Appender can contain a {@link org.apache.logging.log4j.core.Layout} if applicable as well
23   * as an {@link org.apache.logging.log4j.core.ErrorHandler}. Typical Appender implementations coordinate with an
24   * implementation of {@link org.apache.logging.log4j.core.appender.AbstractManager} to handle external resources
25   * such as streams, connections, and other shared state. As Appenders are plugins, concrete implementations need to
26   * be annotated with {@link org.apache.logging.log4j.core.config.plugins.Plugin} and need to provide a static
27   * factory method annotated with {@link org.apache.logging.log4j.core.config.plugins.PluginFactory}.
28   *
29   * <p>Most core plugins are written using a related Manager class that handle the actual task of serializing a
30   * {@link org.apache.logging.log4j.core.LogEvent} to some output location. For instance, many Appenders can take
31   * advantage of the {@link org.apache.logging.log4j.core.appender.OutputStreamManager} class.</p>
32   *
33   * <p>It is recommended that Appenders don't do any heavy lifting since there can be many instances of the class
34   * being used at any given time. When resources require locking (e.g., through {@link java.nio.channels.FileLock}),
35   * it is important to isolate synchronized code to prevent concurrency issues.</p>
36   */
37  public interface Appender extends LifeCycle {
38  
39      /**
40       * Logs a LogEvent using whatever logic this Appender wishes to use. It is typically recommended to use a
41       * bridge pattern not only for the benefits from decoupling an Appender from its implementation, but it is also
42       * handy for sharing resources which may require some form of locking.
43       *
44       * @param event The LogEvent.
45       */
46      void append(LogEvent event);
47  
48  
49      /**
50       * Get the name of this Appender.
51       *
52       * @return name, may be null.
53       */
54      String getName();
55  
56      /**
57       * Returns the Layout used by this Appender if applicable.
58       *
59       * @return the Layout for this Appender or {@code null} if none is configured.
60       */
61      Layout<? extends Serializable> getLayout();
62  
63      /**
64       * Some Appenders need to propagate exceptions back to the application. When {@code ignoreExceptions} is
65       * {@code false} the AppenderControl will allow the exception to percolate.
66       *
67       * @return {@code true} if exceptions will be logged but not thrown, {@code false} otherwise.
68       */
69      boolean ignoreExceptions();
70  
71      ErrorHandler getHandler();
72  
73      void setHandler(ErrorHandler handler);
74  }