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 */
017
018package org.apache.logging.log4j.core.appender;
019
020import java.io.Serializable;
021
022import org.apache.logging.log4j.core.Filter;
023import org.apache.logging.log4j.core.Layout;
024import org.apache.logging.log4j.core.LogEvent;
025import org.apache.logging.log4j.core.config.plugins.Plugin;
026import org.apache.logging.log4j.core.config.plugins.PluginAttribute;
027import org.apache.logging.log4j.core.config.plugins.PluginElement;
028import org.apache.logging.log4j.core.config.plugins.PluginFactory;
029import org.apache.logging.log4j.core.filter.ThresholdFilter;
030import org.apache.logging.log4j.core.helpers.Booleans;
031import org.apache.logging.log4j.core.layout.HTMLLayout;
032import org.apache.logging.log4j.core.net.SMTPManager;
033
034/**
035 * Send an e-mail when a specific logging event occurs, typically on errors or
036 * fatal errors.
037 *
038 * <p>
039 * The number of logging events delivered in this e-mail depend on the value of
040 * <b>BufferSize</b> option. The <code>SMTPAppender</code> keeps only the last
041 * <code>BufferSize</code> logging events in its cyclic buffer. This keeps
042 * memory requirements at a reasonable level while still delivering useful
043 * application context.
044 *
045 * By default, an email message will formatted as HTML. This can be modified by
046 * setting a layout for the appender.
047 *
048 * By default, an email message will be sent when an ERROR or higher severity
049 * message is appended. This can be modified by setting a filter for the
050 * appender.
051 */
052@Plugin(name = "SMTP", category = "Core", elementType = "appender", printObject = true)
053public final class SMTPAppender extends AbstractAppender {
054
055    private static final int DEFAULT_BUFFER_SIZE = 512;
056
057    /** The SMTP Manager */
058    protected final SMTPManager manager;
059
060    private SMTPAppender(final String name, final Filter filter, final Layout<? extends Serializable> layout, final SMTPManager manager,
061                         final boolean ignoreExceptions) {
062        super(name, filter, layout, ignoreExceptions);
063        this.manager = manager;
064    }
065
066    /**
067     * Create a SMTPAppender.
068     *
069     * @param name
070     *            The name of the Appender.
071     * @param to
072     *            The comma-separated list of recipient email addresses.
073     * @param cc
074     *            The comma-separated list of CC email addresses.
075     * @param bcc
076     *            The comma-separated list of BCC email addresses.
077     * @param from
078     *            The email address of the sender.
079     * @param replyTo
080     *            The comma-separated list of reply-to email addresses.
081     * @param subject The subject of the email message.
082     * @param smtpProtocol The SMTP transport protocol (such as "smtps", defaults to "smtp").
083     * @param smtpHost
084     *            The SMTP hostname to send to.
085     * @param smtpPortStr
086     *            The SMTP port to send to.
087     * @param smtpUsername
088     *            The username required to authenticate against the SMTP server.
089     * @param smtpPassword
090     *            The password required to authenticate against the SMTP server.
091     * @param smtpDebug
092     *            Enable mail session debuging on STDOUT.
093     * @param bufferSizeStr
094     *            How many log events should be buffered for inclusion in the
095     *            message?
096     * @param layout
097     *            The layout to use (defaults to HTMLLayout).
098     * @param filter
099     *            The Filter or null (defaults to ThresholdFilter, level of
100     *            ERROR).
101     * @param ignore If {@code "true"} (default) exceptions encountered when appending events are logged; otherwise
102     *               they are propagated to the caller.
103     * @return The SMTPAppender.
104     */
105    @PluginFactory
106    public static SMTPAppender createAppender(
107            @PluginAttribute("name") final String name,
108            @PluginAttribute("to") final String to,
109            @PluginAttribute("cc") final String cc,
110            @PluginAttribute("bcc") final String bcc,
111            @PluginAttribute("from") final String from,
112            @PluginAttribute("replyTo") final String replyTo,
113            @PluginAttribute("subject") final String subject,
114            @PluginAttribute("smtpProtocol") final String smtpProtocol,
115            @PluginAttribute("smtpHost") final String smtpHost,
116            @PluginAttribute("smtpPort") final String smtpPortStr,
117            @PluginAttribute("smtpUsername") final String smtpUsername,
118            @PluginAttribute("smtpPassword") final String smtpPassword,
119            @PluginAttribute("smtpDebug") final String smtpDebug,
120            @PluginAttribute("bufferSize") final String bufferSizeStr,
121            @PluginElement("Layout") Layout<? extends Serializable> layout,
122            @PluginElement("Filter") Filter filter,
123            @PluginAttribute("ignoreExceptions") final String ignore) {
124        if (name == null) {
125            LOGGER.error("No name provided for SMTPAppender");
126            return null;
127        }
128
129        final boolean ignoreExceptions = Booleans.parseBoolean(ignore, true);
130        final int smtpPort = AbstractAppender.parseInt(smtpPortStr, 0);
131        final boolean isSmtpDebug = Boolean.parseBoolean(smtpDebug);
132        final int bufferSize = bufferSizeStr == null ? DEFAULT_BUFFER_SIZE : Integer.parseInt(bufferSizeStr);
133
134        if (layout == null) {
135            layout = HTMLLayout.createLayout(null, null, null, null, null, null);
136        }
137        if (filter == null) {
138            filter = ThresholdFilter.createFilter(null, null, null);
139        }
140
141        final SMTPManager manager = SMTPManager.getSMTPManager(to, cc, bcc, from, replyTo, subject, smtpProtocol,
142            smtpHost, smtpPort, smtpUsername, smtpPassword, isSmtpDebug, filter.toString(),  bufferSize);
143        if (manager == null) {
144            return null;
145        }
146
147        return new SMTPAppender(name, filter, layout, manager, ignoreExceptions);
148    }
149
150    /**
151     * Capture all events in CyclicBuffer.
152     * @param event The Log event.
153     * @return true if the event should be filtered.
154     */
155    @Override
156    public boolean isFiltered(final LogEvent event) {
157        final boolean filtered = super.isFiltered(event);
158        if (filtered) {
159            manager.add(event);
160        }
161        return filtered;
162    }
163
164    /**
165     * Perform SMTPAppender specific appending actions, mainly adding the event
166     * to a cyclic buffer and checking if the event triggers an e-mail to be
167     * sent.
168     * @param event The Log event.
169     */
170    @Override
171    public void append(final LogEvent event) {
172        manager.sendEvents(getLayout(), event);
173    }
174}