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  
18  package org.apache.logging.log4j.core.appender;
19  
20  import org.apache.logging.log4j.core.config.plugins.Plugin;
21  import org.apache.logging.log4j.core.config.plugins.PluginAttr;
22  import org.apache.logging.log4j.core.config.plugins.PluginElement;
23  import org.apache.logging.log4j.core.config.plugins.PluginFactory;
24  import org.apache.logging.log4j.core.filter.ThresholdFilter;
25  import org.apache.logging.log4j.core.layout.HTMLLayout;
26  import org.apache.logging.log4j.core.net.SMTPManager;
27  import org.apache.logging.log4j.core.Filter;
28  import org.apache.logging.log4j.core.Layout;
29  import org.apache.logging.log4j.core.LogEvent;
30  
31  import java.io.Serializable;
32  
33  /**
34   * Send an e-mail when a specific logging event occurs, typically on errors or
35   * fatal errors.
36   *
37   * <p>
38   * The number of logging events delivered in this e-mail depend on the value of
39   * <b>BufferSize</b> option. The <code>SMTPAppender</code> keeps only the last
40   * <code>BufferSize</code> logging events in its cyclic buffer. This keeps
41   * memory requirements at a reasonable level while still delivering useful
42   * application context.
43   *
44   * By default, an email message will formatted as HTML. This can be modified by
45   * setting a layout for the appender.
46   *
47   * By default, an email message will be sent when an ERROR or higher severity
48   * message is appended. This can be modified by setting a filter for the
49   * appender.
50   */
51  @Plugin(name = "SMTP", category = "Core", elementType = "appender", printObject = true)
52  public final class SMTPAppender<T extends Serializable> extends AbstractAppender<T> {
53  
54      private static final int DEFAULT_BUFFER_SIZE = 512;
55  
56      /** The SMTP Manager */
57      protected final SMTPManager manager;
58  
59      private SMTPAppender(final String name, final Filter filter, final Layout<T> layout, final SMTPManager manager,
60                           final boolean handleExceptions) {
61          super(name, filter, layout, handleExceptions);
62          this.manager = manager;
63      }
64  
65      /**
66       * Create a SMTPAppender.
67       *
68       * @param name
69       *            The name of the Appender.
70       * @param to
71       *            The comma-separated list of recipient email addresses.
72       * @param cc
73       *            The comma-separated list of CC email addresses.
74       * @param bcc
75       *            The comma-separated list of BCC email addresses.
76       * @param from
77       *            The email address of the sender.
78       * @param replyTo
79       *            The comma-separated list of reply-to email addresses.
80       * @param subject The subject of the email message.
81       * @param smtpProtocol The SMTP transport protocol (such as "smtps", defaults to "smtp").
82       * @param smtpHost
83       *            The SMTP hostname to send to.
84       * @param smtpPortNum
85       *            The SMTP port to send to.
86       * @param smtpUsername
87       *            The username required to authenticate against the SMTP server.
88       * @param smtpPassword
89       *            The password required to authenticate against the SMTP server.
90       * @param smtpDebug
91       *            Enable mail session debuging on STDOUT.
92       * @param bufferSizeNum
93       *            How many log events should be buffered for inclusion in the
94       *            message?
95       * @param layout
96       *            The layout to use (defaults to HTMLLayout).
97       * @param filter
98       *            The Filter or null (defaults to ThresholdFilter, level of
99       *            ERROR).
100      * @param suppressExceptions
101      *            "true" if exceptions should be hidden from the application,
102      *            "false" otherwise (defaults to "true").
103      * @return The SMTPAppender.
104      */
105     @PluginFactory
106     public static <S extends Serializable> SMTPAppender<S> createAppender(@PluginAttr("name") final String name,
107                                               @PluginAttr("to") final String to,
108                                               @PluginAttr("cc") final String cc,
109                                               @PluginAttr("bcc") final String bcc,
110                                               @PluginAttr("from") final String from,
111                                               @PluginAttr("replyTo") final String replyTo,
112                                               @PluginAttr("subject") final String subject,
113                                               @PluginAttr("smtpProtocol") final String smtpProtocol,
114                                               @PluginAttr("smtpHost") final String smtpHost,
115                                               @PluginAttr("smtpPort") final String smtpPortNum,
116                                               @PluginAttr("smtpUsername") final String smtpUsername,
117                                               @PluginAttr("smtpPassword") final String smtpPassword,
118                                               @PluginAttr("smtpDebug") final String smtpDebug,
119                                               @PluginAttr("bufferSize") final String bufferSizeNum,
120                                               @PluginElement("layout") Layout<S> layout,
121                                               @PluginElement("filter") Filter filter,
122                                               @PluginAttr("suppressExceptions") final String suppressExceptions) {
123         if (name == null) {
124             LOGGER.error("No name provided for SMTPAppender");
125             return null;
126         }
127 
128         final boolean isHandleExceptions = suppressExceptions == null ? true : Boolean.valueOf(suppressExceptions);
129         final int smtpPort = smtpPortNum == null ? 0 : Integer.parseInt(smtpPortNum);
130         final boolean isSmtpDebug = smtpDebug == null ? false : Boolean.valueOf(smtpDebug);
131         final int bufferSize = bufferSizeNum == null ? DEFAULT_BUFFER_SIZE : Integer.valueOf(bufferSizeNum);
132 
133         if (layout == null) {
134             @SuppressWarnings({"unchecked", "UnnecessaryLocalVariable"})
135             Layout<S> l = (Layout<S>)HTMLLayout.createLayout(null, null, null, null, null, null);
136             layout = l;
137         }
138         if (filter == null) {
139             filter = ThresholdFilter.createFilter(null, null, null);
140         }
141 
142         final SMTPManager manager = SMTPManager.getSMTPManager(to, cc, bcc, from, replyTo, subject, smtpProtocol,
143             smtpHost, smtpPort, smtpUsername, smtpPassword, isSmtpDebug, filter.toString(),  bufferSize);
144         if (manager == null) {
145             return null;
146         }
147 
148         return new SMTPAppender<S>(name, filter, layout, manager, isHandleExceptions);
149     }
150 
151     /**
152      * Capture all events in CyclicBuffer.
153      * @param event The Log event.
154      * @return true if the event should be filtered.
155      */
156     @Override
157     public boolean isFiltered(final LogEvent event) {
158         final boolean filtered = super.isFiltered(event);
159         if (filtered) {
160             manager.add(event);
161         }
162         return filtered;
163     }
164 
165     /**
166      * Perform SMTPAppender specific appending actions, mainly adding the event
167      * to a cyclic buffer and checking if the event triggers an e-mail to be
168      * sent.
169      * @param event The Log event.
170      */
171     @Override
172     public void append(final LogEvent event) {
173         manager.sendEvents(getLayout(), event);
174     }
175 }