• Home
• com.sun.mail
• javax.mail
• 1.6.2
• 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

/*
 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
 *
 * Copyright (c) 2009-2017 Oracle and/or its affiliates. All rights reserved.
 * Copyright (c) 2009-2017 Jason Mehrens. All rights reserved.
 *
 * The contents of this file are subject to the terms of either the GNU
 * General Public License Version 2 only ("GPL") or the Common Development
 * and Distribution License("CDDL") (collectively, the "License").  You
 * may not use this file except in compliance with the License.  You can
 * obtain a copy of the License at
 * https://oss.oracle.com/licenses/CDDL+GPL-1.1
 * or LICENSE.txt.  See the License for the specific
 * language governing permissions and limitations under the License.
 *
 * When distributing the software, include this License Header Notice in each
 * file and include the License file at LICENSE.txt.
 *
 * GPL Classpath Exception:
 * Oracle designates this particular file as subject to the "Classpath"
 * exception as provided by Oracle in the GPL Version 2 section of the License
 * file that accompanied this code.
 *
 * Modifications:
 * If applicable, add the following below the License Header, with the fields
 * enclosed by brackets [] replaced by your own identifying information:
 * "Portions Copyright [year] [name of copyright owner]"
 *
 * Contributor(s):
 * If you wish your version of this file to be governed by only the CDDL or
 * only the GPL Version 2, indicate your decision by adding "[Contributor]
 * elects to include this software in this distribution under the [CDDL or GPL
 * Version 2] license."  If you don't indicate a single choice of license, a
 * recipient has the option to distribute your version of this file under
 * either the CDDL, the GPL Version 2 or to extend the choice of license to
 * its licensees as provided above.  However, if you add GPL Version 2 code
 * and therefore, elected the GPL Version 2 license, then the option applies
 * only if the new code is made subject to such option by the copyright
 * holder.
 */

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 javax.activation.*;
import javax.mail.*;
import javax.mail.internet.*;
import javax.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 javax.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 javax.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 javax.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 javax.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 javax.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 javax.mail.internet.MimeMessage#MimeMessage(
 * javax.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 JavaMail 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