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 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 toString of the attachment formatter)
• <handler-name>.authenticator name of an javax.mail.Authenticator class used to provide login credentials to the email server or string literal that is the password used with the 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 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 character set to use for the email message. (defaults to null, the 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 local address)
• <handler-name>.mail.host the host name or IP address of the email server. (defaults to null, use 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 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 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 equals and 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 overridden by adding a MIME 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 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 raw string and is then passed as the msg parameter to reportError along with the exception describing the cause of the failure. This allows custom error managers to store, 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.
     }
}