public class

MailHandler

extends Handler
java.lang.Object
   ↳ java.util.logging.Handler
     ↳ com.google.code.com.sun.mail.util.logging.MailHandler

Class Overview

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", "me@example.com");
      props.put("verify", "local");
      MailHandler h = new MailHandler(props);
      h.setLevel(Level.WARNING);

Configuration: The LogManager must 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 = me@example.com
      com.sun.mail.util.logging.MailHandler.level = WARNING
      com.sun.mail.util.logging.MailHandler.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 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. If properties are not defined, or contain invalid values, then the specified default values are used.
  • com.sun.mail.util.logging.MailHandler.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. (default is no filters)
  • com.sun.mail.util.logging.MailHandler.attachment.formatters a comma separated list of Formatter class names used to create each attachment. (default is no attachments)
  • com.sun.mail.util.logging.MailHandler.attachment.names a comma separated list of names or Formatter class names of each attachment. (default is no attachments names)
  • com.sun.mail.util.logging.MailHandler.authenticator name of a javax.mail.Authenticator class used to provide login credentials to the email server. (default is null)
  • com.sun.mail.util.logging.MailHandler.capacity the max number of LogRecord objects include in each email message. (defaults to 1000)
  • com.sun.mail.util.logging.MailHandler.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).
  • com.sun.mail.util.logging.MailHandler.encoding the name of the character set encoding to use (defaults to the default platform encoding).
  • com.sun.mail.util.logging.MailHandler.errorManager name of a ErrorManager class used to handle any configuration or mail transport problems. (defaults to java.util.logging.ErrorManager)
  • com.sun.mail.util.logging.MailHandler.filter name of a Filter class used for the body of the message. (defaults to null, allow all records)
  • com.sun.mail.util.logging.MailHandler.formatter name of a Formatter class used to format the body of this message. (defaults to java.util.logging.SimpleFormatter)
  • com.sun.mail.util.logging.MailHandler.level specifies the default level for this Handler (defaults to Level.WARNING).
  • com.sun.mail.util.logging.MailHandler.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. (defaults to null, none)
  • com.sun.mail.util.logging.MailHandler.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. (defaults to null, none)
  • com.sun.mail.util.logging.MailHandler.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. (defaults to javax.mail.Message#setFrom())
  • com.sun.mail.util.logging.MailHandler.mail.host the host name or IP address of the email server. (defaults to null, no host)
  • com.sun.mail.util.logging.MailHandler.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. (defaults to null, none)
  • com.sun.mail.util.logging.MailHandler.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. (defaults to null, none)
  • com.sun.mail.util.logging.MailHandler.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. (defaults to null, none)
  • com.sun.mail.util.logging.MailHandler.pushLevel the level which will trigger an early push. (defaults to Level.OFF, only push when full)
  • com.sun.mail.util.logging.MailHandler.pushFilter the name of a Filter class used to trigger an early push. (defaults to null, no early push)
  • com.sun.mail.util.logging.MailHandler.subject the name of a Formatter class or string literal used to create the subject line. (defaults to empty string)
  • com.sun.mail.util.logging.MailHandler.verify used to verify all of the Handler properties prior to a push. If set to a value of local the Handler will only verify settings of the local machine. If set to a value of remote, the Handler will verify all local settings and try to establish a connection with the email server. If the value is not set, equal to an empty string, or equal to the literal null then minimal or no settings are verified prior to a push. If this Handler is only implicitly closed by the LogManager, then verification should be turned on. (defaults to null, no verify).

    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 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. 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 javax.mail.internet.MimeMessage#writeTo 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, 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.
      }
 }

Summary

Fields
private Filter[] attachmentFilters Holds the filters for each attachment.
private Formatter[] attachmentFormatters Holds the formatters that create the content for each attachment.
private Formatter[] attachmentNames Holds the formatters that create the file name for each attachment.
private Authenticator auth Holds the authenticator required to login to the email server.
private int capacity The maximum number of log records to format per email.
private Comparator comparator Used to order all log records prior to formatting.
private FileTypeMap contentTypes Used to override the content type for the body and set the content type for each attachment.
private LogRecord[] data Holds all of the log records that will be used to create the email.
private boolean isWriting Determines if we are inside of a push.
private Properties mailProps Holds all of the email server properties.
private static final int offValue Cache the off value.
private Filter pushFilter Holds the push filter for trigger conditions requiring an early push.
private Level pushLevel Holds the push level for this handler.
private boolean sealed Used to turn off security checks.
private Session session Holds the session object used to generate emails.
private int size The number of log records in the buffer.
private Formatter subjectFormatter Holds the formatter used to create the subject line of the email.
[Expand]
Inherited Fields
From class java.util.logging.Handler
Public Constructors
MailHandler()
Creates a MailHandler that is configured by the LogManager configuration properties.
MailHandler(int capacity)
Creates a mail handler with the specified capacity.
MailHandler(Properties props)
Creates a mail handler with the given mail properties.
Public Methods
void close()
Prevents any other records from being published.
void flush()
Pushes any buffered records to the email server as normal priority.
final Filter[] getAttachmentFilters()
Gets the attachment filters.
final Formatter[] getAttachmentFormatters()
Gets the attachment formatters.
final Formatter[] getAttachmentNames()
Gets the attachment name formatters.
synchronized final Authenticator getAuthenticator()
Gets the Authenticator used to login to the email server.
synchronized final int getCapacity()
Gets the number of log records the internal buffer can hold.
synchronized final Comparator getComparator()
Gets the comparator used to order all LogRecord objects prior to formatting.
final Properties getMailProperties()
Gets a copy of the mail properties used for the session.
synchronized final Filter getPushFilter()
Gets the push filter.
synchronized final Level getPushLevel()
Gets the push level.
synchronized final Formatter getSubject()
Gets the formatter used to create the subject line.
boolean isLoggable(LogRecord record)
Check if this Handler would actually log a given LogRecord into its internal buffer.
void publish(LogRecord record)
Stores a LogRecord in the internal buffer.
void push()
Pushes any buffered records to the email server as high importance with urgent priority.
final void setAttachmentFilters(Filter[] filters)
Sets the attachment filters.
final void setAttachmentFormatters(Formatter[] formatters)
Sets the attachment Formatter object for this handler.
final void setAttachmentNames(String[] names)
Sets the attachment file name for each attachment.
final void setAttachmentNames(Formatter[] formatters)
Sets the attachment file name formatters.
final void setAuthenticator(Authenticator auth)
Sets the Authenticator used to login to the email server.
synchronized final void setComparator(Comparator c)
Sets the comparator used to order all LogRecord objects prior to formatting.
synchronized void setLevel(Level newLevel)
Set the log level specifying which message levels will be logged by this Handler.
final void setMailProperties(Properties props)
Sets the mail properties used for the session.
synchronized final void setPushFilter(Filter filter)
Sets the push filter.
synchronized final void setPushLevel(Level level)
Sets the push level.
final void setSubject(Formatter format)
Sets the subject formatter for email.
final void setSubject(String subject)
Sets a literal string for the email subject.
Protected Methods
void reportError(String msg, Exception ex, int code)
Protected convenience method to report an error to this Handler's ErrorManager.
[Expand]
Inherited Methods
From class java.util.logging.Handler
From class java.lang.Object

Fields

private Filter[] attachmentFilters

Holds the filters for each attachment. Filters are optional for each attachment.

private Formatter[] attachmentFormatters

Holds the formatters that create the content for each attachment. Each formatter maps directly to an attachment. The formatters getHead, format, and getTail methods are only called if one or more log records pass through the attachment filters.

private Formatter[] attachmentNames

Holds the formatters that create the file name for each attachment. Each formatter must produce a non null and non empty name. The final file name will be the concatenation of one getHead call, plus all of the format calls, plus one getTail call.

private Authenticator auth

Holds the authenticator required to login to the email server.

private int capacity

The maximum number of log records to format per email. Used to roughly bound the size of an email. Every time the capacity is reached, the handler will push. The capacity will be negative if this handler is closed. Negative values are used to ensure all records are pushed.

private Comparator comparator

Used to order all log records prior to formatting. The main email body and all attachments use the order determined by this comparator. If no comparator is present the log records will be in no specified order.

private FileTypeMap contentTypes

Used to override the content type for the body and set the content type for each attachment.

private LogRecord[] data

Holds all of the log records that will be used to create the email.

private boolean isWriting

Determines if we are inside of a push. Makes the handler properties read-only during a push.

private Properties mailProps

Holds all of the email server properties.

private static final int offValue

Cache the off value.

private Filter pushFilter

Holds the push filter for trigger conditions requiring an early push. Only gets called if the given log record is greater than or equal to the push level and the push level is not Level.OFF.

private Level pushLevel

Holds the push level for this handler. This is only required if an email must be sent prior to shutdown or before the buffer is full.

private boolean sealed

Used to turn off security checks.

private Session session

Holds the session object used to generate emails. Sessions can be shared by multiple threads. See BUGID 6228391

private int size

The number of log records in the buffer.

private Formatter subjectFormatter

Holds the formatter used to create the subject line of the email. A subject formatter is not required for the email message. All published records pass through the subject formatter.

Public Constructors

public MailHandler ()

Creates a MailHandler that is configured by the LogManager configuration properties.

Throws
SecurityException if a security manager exists and the caller does not have LoggingPermission("control").

public MailHandler (int capacity)

Creates a mail handler with the specified capacity.

Parameters
capacity Of the internal buffer.
Throws
IllegalArgumentException if capacity less than one.
SecurityException if a security manager exists and the caller does not have LoggingPermission("control").

public MailHandler (Properties props)

Creates a mail handler with the given mail properties. The key/value pairs are defined in the Java Mail API documentation. This Handler will also search the LogManager for defaults if needed.

Parameters
props A non null properties object.
Throws
NullPointerException if props is null.
SecurityException if a security manager exists and the caller does not have LoggingPermission("control").

Public Methods

public void close ()

Prevents any other records from being published. Pushes any buffered records to the email server as normal priority. The internal buffer is then cleared. Once this handler is closed it will remain closed.

If this Handler is only implicitly closed by the LogManager, then verification should be turned on.

Throws
SecurityException if a security manager exists and the caller does not have LoggingPermission("control").
See Also

public void flush ()

Pushes any buffered records to the email server as normal priority. The internal buffer is then cleared. Does nothing if called from inside a push.

See Also

public final Filter[] getAttachmentFilters ()

Gets the attachment filters. If the attachment filter does not allow any LogRecord to be formatted, the attachment may be omitted from the email.

Returns
  • a non null array of attachment filters.

public final Formatter[] getAttachmentFormatters ()

Gets the attachment formatters. This Handler is using attachments only if the returned array length is non zero.

Returns
  • a non null array of formatters.

public final Formatter[] getAttachmentNames ()

Gets the attachment name formatters. If the attachment names were set using explicit names then the names can be returned by calling toString on each attachment name formatter.

Returns
  • non null array of attachment name formatters.

public final synchronized Authenticator getAuthenticator ()

Gets the Authenticator used to login to the email server.

Returns
  • an Authenticator or null if none is required.
Throws
SecurityException if a security manager exists and the caller does not have LoggingPermission("control").

public final synchronized int getCapacity ()

Gets the number of log records the internal buffer can hold. When capacity is reached, Handler will format all LogRecord objects into one email message.

Returns
  • the capacity.

public final synchronized Comparator getComparator ()

Gets the comparator used to order all LogRecord objects prior to formatting. If null then the order is unspecified.

Returns
  • the LogRecord comparator.

public final Properties getMailProperties ()

Gets a copy of the mail properties used for the session.

Returns
  • a non null properties object.
Throws
SecurityException if a security manager exists and the caller does not have LoggingPermission("control").

public final synchronized Filter getPushFilter ()

Gets the push filter. The default is null.

Returns
  • the push filter or null.

public final synchronized Level getPushLevel ()

Gets the push level. The default is Level.OFF meaning that this Handler will only push when the internal buffer is full.

Returns
  • the push level.

public final synchronized Formatter getSubject ()

Gets the formatter used to create the subject line. If the subject was created using a literal string then the toString method can be used to get the subject line.

Returns
  • the formatter.

public boolean isLoggable (LogRecord record)

Check if this Handler would actually log a given LogRecord into its internal buffer.

This method checks if the LogRecord has an appropriate level and whether it satisfies any Filter including any attachment filters. However it does not check whether the LogRecord would result in a "push" of the buffer contents.

Parameters
record A LogRecord
Returns
  • true if the LogRecord would be logged.

public void publish (LogRecord record)

Stores a LogRecord in the internal buffer.

The isLoggable method is called to check if the given log record is loggable. If the given record is loggable, it is copied into an internal buffer. Then the record's level property is compared with the push level. If the given level of the LogRecord is greater than or equal to the push level then the push filter is called. If no push filter exists, the push filter returns true, or the capacity of the internal buffer has been reached then all buffered records are formatted into one email and sent to the server.

Parameters
record Description of the log event.

public void push ()

Pushes any buffered records to the email server as high importance with urgent priority. The internal buffer is then cleared. Does nothing if called from inside a push.

See Also

public final void setAttachmentFilters (Filter[] filters)

Sets the attachment filters.

Parameters
filters A non null array of filters. A null index value is allowed. A null value means that all records are allowed for the attachment at that index.
Throws
SecurityException if a security manager exists and the caller does not have LoggingPermission("control").
NullPointerException if filters is null
IndexOutOfBoundsException if the number of attachment name formatters do not match the number of attachment formatters.
IllegalStateException if called from inside a push.

public final void setAttachmentFormatters (Formatter[] formatters)

Sets the attachment Formatter object for this handler. The number of formatters determines the number of attachments per email. This method should be the first attachment method called. To remove all attachments, call this method with empty array.

Parameters
formatters A non null array of formatters.
Throws
SecurityException if a security manager exists and the caller does not have LoggingPermission("control").
NullPointerException if the given array or any array index is null.
IllegalStateException if called from inside a push.

public final void setAttachmentNames (String[] names)

Sets the attachment file name for each attachment. The caller must ensure that the attachment file name does not contain any line breaks. This method will create a set of custom formatters.

Parameters
names An array of names.
Throws
SecurityException if a security manager exists and the caller does not have LoggingPermission("control").
IndexOutOfBoundsException if the number of attachment names do not match the number of attachment formatters.
IllegalArgumentException if any name is empty.
NullPointerException if any given array or name is null.
IllegalStateException if called from inside a push.
See Also

public final void setAttachmentNames (Formatter[] formatters)

Sets the attachment file name formatters. The format method of each attachment formatter will see only the LogRecord objects that passed its attachment filter during formatting. The format method will typically return an empty string. Instead of being used to format records, it is used to gather information about the contents of an attachment. The getTail method should be used to construct the attachment file name and reset any formatter collected state. The formatter must ensure that the attachment file name does not contain any line breaks. The toString method of the given formatter should be overridden to provide a useful attachment file name, if possible.

Parameters
formatters And array of attachment name formatters.
Throws
SecurityException if a security manager exists and the caller does not have LoggingPermission("control").
IndexOutOfBoundsException if the number of attachment name formatters do not match the number of attachment formatters.
NullPointerException if any given array or name is null.
IllegalStateException if called from inside a push.
See Also

public final void setAuthenticator (Authenticator auth)

Sets the Authenticator used to login to the email server.

Parameters
auth An Authenticator object or null if none is required.
Throws
SecurityException if a security manager exists and the caller does not have LoggingPermission("control").
IllegalStateException if called from inside a push.

public final synchronized void setComparator (Comparator c)

Sets the comparator used to order all LogRecord objects prior to formatting. If null then the order is unspecified.

Parameters
c The LogRecord comparator.
Throws
SecurityException if a security manager exists and the caller does not have LoggingPermission("control").
IllegalStateException if called from inside a push.

public synchronized void setLevel (Level newLevel)

Set the log level specifying which message levels will be logged by this Handler. Message levels lower than this value will be discarded.

Parameters
newLevel The new value for the log level
Throws
NullPointerException if newLevel is null.
SecurityException if a security manager exists and the caller does not have LoggingPermission("control").

public final void setMailProperties (Properties props)

Sets the mail properties used for the session. The key/value pairs are defined in the Java Mail API documentation. This Handler will also search the LogManager for defaults if needed.

Parameters
props A non null properties object.
Throws
SecurityException if a security manager exists and the caller does not have LoggingPermission("control").
NullPointerException if props is null.
IllegalStateException if called from inside a push.

public final synchronized void setPushFilter (Filter filter)

Sets the push filter. This filter is only called if the given LogRecord level was greater than the push level. If this filter returns true, all pending records are formatted and sent to the email server. When the push filter triggers a send, the resulting email is flagged as high priority.

Parameters
filter Push filter or null
Throws
SecurityException if a security manager exists and the caller does not have LoggingPermission("control").
IllegalStateException if called from inside a push.

public final synchronized void setPushLevel (Level level)

Sets the push level. This level is used to trigger a push so that all pending records are formatted and sent to the email server. When the push level triggers a send, the resulting email is flagged as high priority.

Parameters
level Level object.
Throws
NullPointerException if level is null.
SecurityException if a security manager exists and the caller does not have LoggingPermission("control").
IllegalStateException if called from inside a push.

public final void setSubject (Formatter format)

Sets the subject formatter for email. The format method of the subject formatter will see all LogRecord objects that were published to this Handler during formatting and will typically return an empty string. This formatter is used to gather information to create a summary about what information is contained in the email. The getTail method should be used to construct the subject and reset any formatter collected state. The formatter must ensure that the subject line does not contain any line breaks. The toString method of the given formatter should be overridden to provide a useful subject, if possible.

Parameters
format The subject formatter.
Throws
SecurityException if a security manager exists and the caller does not have LoggingPermission("control").
NullPointerException if format is null.
IllegalStateException if called from inside a push.
See Also

public final void setSubject (String subject)

Sets a literal string for the email subject. The caller must ensure that the subject line does not contain any line breaks.

Parameters
subject A non null string.
Throws
SecurityException if a security manager exists and the caller does not have LoggingPermission("control").
NullPointerException if subject is null.
IllegalStateException if called from inside a push.
See Also

Protected Methods

protected void reportError (String msg, Exception ex, int code)

Protected convenience method to report an error to this Handler's ErrorManager. This method will prefix all non null error messages with Level.SEVERE.getName(). This allows the receiving error manager to determine if the msg parameter is a simple error message or a raw email message.

Parameters
msg A descriptive string (may be null)
ex An exception (may be null)
code An error code defined in ErrorManager