• Home
• com.sun.mail
• imap
• 2.0.0-RC6
• source code
• MailHandler.java

×

Project download

Many resources are needed to download a project. Please understand that we have to compensate our server costs. Thank you in advance.
Project price only 1 $

You can buy this project and download/modify it how often you want.

com.sun.mail.util.logging.MailHandler Maven / Gradle / Ivy

/*
 * Copyright (c) 2009, 2020 Oracle and/or its affiliates. All rights reserved.
 * Copyright (c) 2009, 2020 Jason Mehrens. All rights reserved.
 *
 * This program and the accompanying materials are made available under the
 * terms of the Eclipse Public License v. 2.0, which is available at
 * http://www.eclipse.org/legal/epl-2.0.
 *
 * This Source Code may also be made available under the following Secondary
 * Licenses when the conditions for such availability set forth in the
 * Eclipse Public License v. 2.0 are satisfied: GNU General Public License,
 * version 2 with the GNU Classpath Exception, which is available at
 * https://www.gnu.org/software/classpath/license.html.
 *
 * SPDX-License-Identifier: EPL-2.0 OR GPL-2.0 WITH Classpath-exception-2.0
 */

package com.sun.mail.util.logging;

import static com.sun.mail.util.logging.LogManagerProperties.fromLogManager;
import java.io.*;
import java.lang.reflect.InvocationTargetException;
import java.net.InetAddress;
import java.net.URLConnection;
import java.net.UnknownHostException;
import java.nio.charset.Charset;
import java.security.AccessController;
import java.security.PrivilegedAction;
import java.util.*;
import java.util.logging.*;
import java.util.logging.Formatter;
import jakarta.activation.*;
import jakarta.mail.*;
import jakarta.mail.internet.*;
import jakarta.mail.util.ByteArrayDataSource;

/**
 * Handler that formats log records as an email message.
 *
 * 

 * This Handler will store a fixed number of log records used to
 * generate a single email message.  When the internal buffer reaches capacity,
 * all log records are formatted and placed in an email which is sent to an
 * email server.  The code to manually setup this handler can be as simple as
 * the following:
 *
 * 
 *      Properties props = new Properties();
 *      props.put("mail.smtp.host", "my-mail-server");
 *      props.put("mail.to", "[email protected]");
 *      props.put("verify", "local");
 *      MailHandler h = new MailHandler(props);
 *      h.setLevel(Level.WARNING);
 * 
 *
 * 

 * Configuration:
 * The LogManager should define at least one or more recipient addresses and a
 * mail host for outgoing email.  The code to setup this handler via the
 * logging properties can be as simple as the following:
 *
 * 
 *      #Default MailHandler settings.
 *      com.sun.mail.util.logging.MailHandler.mail.smtp.host = my-mail-server
 *      com.sun.mail.util.logging.MailHandler.mail.to = [email protected]
 *      com.sun.mail.util.logging.MailHandler.level = WARNING
 *      com.sun.mail.util.logging.MailHandler.verify = local
 * 
 *
 * For a custom handler, e.g. com.foo.MyHandler, the properties
 * would be:
 *
 * 
 *      #Subclass com.foo.MyHandler settings.
 *      com.foo.MyHandler.mail.smtp.host = my-mail-server
 *      com.foo.MyHandler.mail.to = [email protected]
 *      com.foo.MyHandler.level = WARNING
 *      com.foo.MyHandler.verify = local
 * 
 *
 * All mail properties documented in the Java Mail API cascade to
 * the LogManager by prefixing a key using the fully qualified class name of
 * this MailHandler or the fully qualified derived class name dot
 * mail property.  If the prefixed property is not found, then the mail property
 * itself is searched in the LogManager. By default each
 * MailHandler is initialized using the following LogManager
 * configuration properties where <handler-name> refers to
 * the fully qualified class name of the handler.  If properties are not
 * defined, or contain invalid values, then the specified default values are
 * used.
 *
 * 

 * 
<handler-name>.attachment.filters a comma
 * separated list of Filter class names used to create each
 * attachment.  The literal null is reserved for attachments that
 * do not require filtering. (defaults to the
 * {@linkplain java.util.logging.Handler#getFilter() body} filter)
 *
 * 
<handler-name>.attachment.formatters a comma
 * separated list of Formatter class names used to create each
 * attachment. (default is no attachments)
 *
 * 
<handler-name>.attachment.names a comma separated
 * list of names or Formatter class names of each attachment.  All
 * control characters are removed from the attachment names.
 * (default is {@linkplain java.util.logging.Formatter#toString() toString}
 * of the attachment formatter)
 *
 * 
<handler-name>.authenticator name of an
 * {@linkplain jakarta.mail.Authenticator} class used to provide login credentials
 * to the email server or string literal that is the password used with the
 * {@linkplain Authenticator#getDefaultUserName() default} user name.
 * (default is null)
 *
 * 
<handler-name>.capacity the max number of
 * LogRecord objects include in each email message.
 * (defaults to 1000)
 *
 * 
<handler-name>.comparator name of a
 * {@linkplain java.util.Comparator} class used to sort the published
 * LogRecord objects prior to all formatting.
 * (defaults to null meaning records are unsorted).
 *
 * 
<handler-name>.comparator.reverse a boolean
 * true to reverse the order of the specified comparator or
 * false to retain the original order.
 * (defaults to false)
 *
 * 
<handler-name>.encoding the name of the Java
 * {@linkplain java.nio.charset.Charset#name() character set} to use for the
 * email message. (defaults to null, the
 * {@linkplain jakarta.mail.internet.MimeUtility#getDefaultJavaCharset() default}
 * platform encoding).
 *
 * 
<handler-name>.errorManager name of an
 * ErrorManager class used to handle any configuration or mail
 * transport problems. (defaults to java.util.logging.ErrorManager)
 *
 * 
<handler-name>.filter name of a Filter
 * class used for the body of the message. (defaults to null,
 * allow all records)
 *
 * 
<handler-name>.formatter name of a
 * Formatter class used to format the body of this message.
 * (defaults to java.util.logging.SimpleFormatter)
 *
 * 
<handler-name>.level specifies the default level
 * for this Handler (defaults to Level.WARNING).
 *
 * 
<handler-name>.mail.bcc a comma separated list of
 * addresses which will be blind carbon copied.  Typically, this is set to the
 * recipients that may need to be privately notified of a log message or
 * notified that a log message was sent to a third party such as a support team.
 * The empty string can be used to specify no blind carbon copied address.
 * (defaults to null, none)
 *
 * 
<handler-name>.mail.cc a comma separated list of
 * addresses which will be carbon copied.  Typically, this is set to the
 * recipients that may need to be notified of a log message but, are not
 * required to provide direct support.  The empty string can be used to specify
 * no carbon copied address.  (defaults to null, none)
 *
 * 
<handler-name>.mail.from a comma separated list of
 * addresses which will be from addresses. Typically, this is set to the email
 * address identifying the user running the application.  The empty string can
 * be used to override the default behavior and specify no from address.
 * (defaults to the {@linkplain jakarta.mail.Message#setFrom() local address})
 *
 * 
<handler-name>.mail.host the host name or IP
 * address of the email server. (defaults to null, use
 * {@linkplain Transport#protocolConnect default}
 * Java Mail behavior)
 *
 * 
<handler-name>.mail.reply.to a comma separated
 * list of addresses which will be reply-to addresses.  Typically, this is set
 * to the recipients that provide support for the application itself.  The empty
 * string can be used to specify no reply-to address.
 * (defaults to null, none)
 *
 * 
<handler-name>.mail.to a comma separated list of
 * addresses which will be send-to addresses. Typically, this is set to the
 * recipients that provide support for the application, system, and/or
 * supporting infrastructure.  The empty string can be used to specify no
 * send-to address which overrides the default behavior.  (defaults to
 * {@linkplain jakarta.mail.internet.InternetAddress#getLocalAddress
 * local address}.)
 *
 * 
<handler-name>.mail.sender a single address
 * identifying sender of the email; never equal to the from address.  Typically,
 * this is set to the email address identifying the application itself.  The
 * empty string can be used to specify no sender address.
 * (defaults to null, none)
 *
 * 
<handler-name>.subject the name of a
 * Formatter class or string literal used to create the subject
 * line.  The empty string can be used to specify no subject.  All control
 * characters are removed from the subject line. (defaults to {@linkplain
 * com.sun.mail.util.logging.CollectorFormatter CollectorFormatter}.)
 *
 * 
<handler-name>.pushFilter the name of a
 * Filter class used to trigger an early push.
 * (defaults to null, no early push)
 *
 * 
<handler-name>.pushLevel the level which will
 * trigger an early push. (defaults to Level.OFF, only push when
 * full)
 *
 * 
<handler-name>.verify used to
 * verify the Handler configuration prior to a push.
 * 

 *      
If the value is not set, equal to an empty string, or equal to the
 *      literal null then no settings are verified prior to a push.
 *      
If set to a value of limited then the
 *      Handler will verify minimal local machine settings.
 *      
If set to a value of local the Handler
 *      will verify all of settings of the local machine.
 *      
If set to a value of resolve, the Handler
 *      will verify all local settings and try to resolve the remote host name
 *      with the domain name server.
 *      
If set to a value of login, the Handler
 *      will verify all local settings and try to establish a connection with
 *      the email server.
 *      
If set to a value of remote, the Handler
 *      will verify all local settings, try to establish a connection with the
 *      email server, and try to verify the envelope of the email message.
 * 
 * If this Handler is only implicitly closed by the
 * LogManager, then verification should be turned on.
 * (defaults to null, no verify).
 * 
 *
 * 

 * Normalization:
 * The error manager, filters, and formatters when loaded from the LogManager
 * are converted into canonical form inside the MailHandler.  The pool of
 * interned values is limited to each MailHandler object such that no two
 * MailHandler objects created by the LogManager will be created sharing
 * identical error managers, filters, or formatters.  If a filter or formatter
 * should not be interned then it is recommended to retain the identity
 * equals and identity hashCode methods as the implementation.  For a filter or
 * formatter to be interned the class must implement the
 * {@linkplain java.lang.Object#equals(java.lang.Object) equals}
 * and {@linkplain java.lang.Object#hashCode() hashCode} methods.
 * The recommended code to use for stateless filters and formatters is:
 * 
 * public boolean equals(Object obj) {
 *     return obj == null ? false : obj.getClass() == getClass();
 * }
 *
 * public int hashCode() {
 *     return 31 * getClass().hashCode();
 * }
 * 
 *
 * 

 * Sorting:
 * All LogRecord objects are ordered prior to formatting if this
 * Handler has a non null comparator.  Developers might be
 * interested in sorting the formatted email by thread id, time, and sequence
 * properties of a LogRecord.  Where as system administrators might
 * be interested in sorting the formatted email by thrown, level, time, and
 * sequence properties of a LogRecord.  If comparator for this
 * handler is null then the order is unspecified.
 *
 * 

 * Formatting:
 * The main message body is formatted using the Formatter returned
 * by getFormatter().  Only records that pass the filter returned
 * by getFilter() will be included in the message body.  The
 * subject Formatter will see all LogRecord objects
 * that were published regardless of the current Filter.  The MIME
 * type of the message body can be
 * {@linkplain FileTypeMap#setDefaultFileTypeMap overridden}
 * by adding a MIME {@linkplain MimetypesFileTypeMap entry} using the simple
 * class name of the body formatter as the file extension.  The MIME type of the
 * attachments can be overridden by changing the attachment file name extension
 * or by editing the default MIME entry for a specific file name extension.
 *
 * 

 * Attachments:
 * This Handler allows multiple attachments per each email message.
 * The presence of an attachment formatter will change the content type of the
 * email message to a multi-part message.  The attachment order maps directly to
 * the array index order in this Handler with zero index being the
 * first attachment.  The number of attachment formatters controls the number of
 * attachments per email and the content type of each attachment.  The
 * attachment filters determine if a LogRecord will be included in
 * an attachment.  If an attachment filter is null then all records
 * are included for that attachment.  Attachments without content will be
 * omitted from email message.  The attachment name formatters create the file
 * name for an attachment.  Custom attachment name formatters can be used to
 * generate an attachment name based on the contents of the attachment.
 *
 * 

 * Push Level and Push Filter:
 * The push method, push level, and optional push filter can be used to
 * conditionally trigger a push at or prior to full capacity.  When a push
 * occurs, the current buffer is formatted into an email and is sent to the
 * email server.  If the push method, push level, or push filter trigger a push
 * then the outgoing email is flagged as high importance with urgent priority.
 *
 * 

 * Buffering:
 * Log records that are published are stored in an internal buffer.  When this
 * buffer reaches capacity the existing records are formatted and sent in an
 * email.  Any published records can be sent before reaching capacity by
 * explictly calling the flush, push, or
 * close methods.  If a circular buffer is required then this
 * handler can be wrapped with a {@linkplain java.util.logging.MemoryHandler}
 * typically with an equivalent capacity, level, and push level.
 *
 * 

 * Error Handling:
 * If the transport of an email message fails, the email is converted to
 * a {@linkplain jakarta.mail.internet.MimeMessage#writeTo raw}
 * {@linkplain java.io.ByteArrayOutputStream#toString(java.lang.String) string}
 * and is then passed as the msg parameter to
 * {@linkplain Handler#reportError reportError} along with the exception
 * describing the cause of the failure.  This allows custom error managers to
 * store, {@linkplain jakarta.mail.internet.MimeMessage#MimeMessage(
 * jakarta.mail.Session, java.io.InputStream) reconstruct}, and resend the
 * original MimeMessage.  The message parameter string is not a raw email
 * if it starts with value returned from Level.SEVERE.getName().
 * Custom error managers can use the following test to determine if the
 * msg parameter from this handler is a raw email:
 *
 * 
 * public void error(String msg, Exception ex, int code) {
 *      if (msg == null || msg.length() == 0 || msg.startsWith(Level.SEVERE.getName())) {
 *          super.error(msg, ex, code);
 *      } else {
 *          //The 'msg' parameter is a raw email.
 *      }
 * }
 * 
 *
 * @author Jason Mehrens
 * @since JavaMail 1.4.3
 */
public class MailHandler extends Handler {
    /**
     * Use the emptyFilterArray method.
     */
    private static final Filter[] EMPTY_FILTERS = new Filter[0];
    /**
     * Use the emptyFormatterArray method.
     */
    private static final Formatter[] EMPTY_FORMATTERS = new Formatter[0];
    /**
     * Min byte size for header data.  Used for initial arrays sizing.
     */
    private static final int MIN_HEADER_SIZE = 1024;
    /**
     * Cache the off value.
     */
    private static final int offValue = Level.OFF.intValue();
    /**
     * The action to set the context class loader for use with the Jakarta Mail API.
     * Load and pin this before it is loaded in the close method. The field is
     * declared as java.security.PrivilegedAction so
     * WebappClassLoader.clearReferencesStaticFinal() method will ignore this
     * field.
     */
    private static final PrivilegedAction