Module org.eclipse.angus.mail
Package org.eclipse.angus.mail.util.logging

Class MailHandler

java.lang.Object
java.util.logging.Handler
org.eclipse.angus.mail.util.logging.MailHandler
public class MailHandler extends Handler
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 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.
      org.eclipse.angus.mail.util.logging.MailHandler.mail.smtp.host = my-mail-server
      org.eclipse.angus.mail.util.logging.MailHandler.mail.to = me@example.com
      org.eclipse.angus.mail.util.logging.MailHandler.level = WARNING
      org.eclipse.angus.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 = me@example.com
      com.foo.MyHandler.level = WARNING
      com.foo.MyHandler.verify = local
All mail properties documented in the Jakarta 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 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 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>.enabled a boolean true to allow this handler to accept records or false to turn off this handler. (defaults to true)
  • <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>.mailEntries specifies the mail session properties for this Handler. The format for the value is described in setMailEntries method. This property eagerly loads the assigned mail properties where as the top level mail properties are lazily loaded. Prefer using this property when verification is off or when verification does not force the provider to load required mail properties. (defaults to null).
  • <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 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.
      }
 }
Since:
JavaMail 1.4.3

  • Constructor Details

    • MailHandler

      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").

    • MailHandler

      public MailHandler(int capacity)
      Creates a MailHandler that is configured by the LogManager configuration properties but overrides the LogManager capacity with the given capacity.
      Parameters:
      capacity - of the internal buffer. If less than one the default of 1000 is used.
      Throws:
      SecurityException - if a security manager exists and the caller does not have LoggingPermission("control").

    • MailHandler

      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 properties object or null. A null value will supply the mailEntries from the LogManager.
      Throws:
      SecurityException - if a security manager exists and the caller does not have LoggingPermission("control").

  • Method Details

    • isLoggable

      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.

      Overrides:
      isLoggable in class Handler
      Parameters:
      record - a LogRecord or null.
      Returns:
      true if the LogRecord would be logged.

    • publish

      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.

      Specified by:
      publish in class Handler
      Parameters:
      record - description of the log event or null.

    • postConstruct

      public void postConstruct()
      A callback method for when this object is about to be placed into commission. This contract is defined by the org.glassfish.hk2.api.PostConstruct interface. If this class is loaded via a lifecycle managed environment other than HK2 then it is recommended that this method is called either directly or through extending this class to signal that this object is ready for use.
      Since:
      JavaMail 1.5.3

    • preDestroy

      public void preDestroy()
      A callback method for when this object is about to be decommissioned. This contract is defined by the org.glassfish.hk2.api.PreDestory interface. If this class is loaded via a lifecycle managed environment other than HK2 then it is recommended that this method is called either directly or through extending this class to signal that this object will be destroyed.
      Since:
      JavaMail 1.5.3

    • push

      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:

    • flush

      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.
      Specified by:
      flush in class Handler
      See Also:

    • close

      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 and or mailEntries should be declared to define the mail properties.

      Specified by:
      close in class Handler
      Throws:
      SecurityException - if a security manager exists and the caller does not have LoggingPermission("control").
      See Also:

    • isEnabled

      public boolean isEnabled()
      Gets the enabled status of this handler.
      Returns:
      true if this handler is accepting log records.
      Since:
      Angus Mail 2.0.3
      See Also:

    • setEnabled

      public void setEnabled(boolean enabled)
      Used to enable or disable this handler. Pushes any buffered records to the email server as normal priority. The internal buffer is then cleared.
      Parameters:
      enabled - true to enable and false to disable.
      Throws:
      SecurityException - if a security manager exists and if the caller does not have LoggingPermission("control").
      Since:
      Angus Mail 2.0.3
      See Also:

    • setLevel

      public 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.
      Overrides:
      setLevel in class Handler
      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").

    • getLevel

      public Level getLevel()
      Get the log level specifying which messages will be logged by this Handler. Message levels lower than this level will be discarded.
      Overrides:
      getLevel in class Handler
      Returns:
      the level of messages being logged.

    • getErrorManager

      public ErrorManager getErrorManager()
      Retrieves the ErrorManager for this Handler.
      Overrides:
      getErrorManager in class Handler
      Returns:
      the ErrorManager for this Handler
      Throws:
      SecurityException - if a security manager exists and if the caller does not have LoggingPermission("control").

    • setErrorManager

      public void setErrorManager(ErrorManager em)
      Define an ErrorManager for this Handler.

      The ErrorManager's "error" method will be invoked if any errors occur while using this Handler.

      Overrides:
      setErrorManager in class Handler
      Parameters:
      em - the new ErrorManager
      Throws:
      SecurityException - if a security manager exists and if the caller does not have LoggingPermission("control").
      NullPointerException - if the given error manager is null.

    • getFilter

      public Filter getFilter()
      Get the current Filter for this Handler.
      Overrides:
      getFilter in class Handler
      Returns:
      a Filter object (may be null)

    • setFilter

      public void setFilter(Filter newFilter)
      Set a Filter to control output on this Handler.

      For each call of publish the Handler will call this Filter (if it is non-null) to check if the LogRecord should be published or discarded.

      Overrides:
      setFilter in class Handler
      Parameters:
      newFilter - a Filter object (may be null)
      Throws:
      SecurityException - if a security manager exists and if the caller does not have LoggingPermission("control").

    • getEncoding

      public String getEncoding()
      Return the character encoding for this Handler.
      Overrides:
      getEncoding in class Handler
      Returns:
      The encoding name. May be null, which indicates the default encoding should be used.

    • setEncoding

      public void setEncoding(String encoding) throws UnsupportedEncodingException
      Set the character encoding used by this Handler.

      The encoding should be set before any LogRecords are written to the Handler.

      Overrides:
      setEncoding in class Handler
      Parameters:
      encoding - The name of a supported character encoding. May be null, to indicate the default platform encoding.
      Throws:
      SecurityException - if a security manager exists and if the caller does not have LoggingPermission("control").
      UnsupportedEncodingException - if the named encoding is not supported.

    • getFormatter

      public Formatter getFormatter()
      Return the Formatter for this Handler.
      Overrides:
      getFormatter in class Handler
      Returns:
      the Formatter (may be null).

    • setFormatter

      public void setFormatter(Formatter newFormatter) throws SecurityException
      Set a Formatter. This Formatter will be used to format LogRecords for this Handler.

      Some Handlers may not use Formatters, in which case the Formatter will be remembered, but not used.

      Overrides:
      setFormatter in class Handler
      Parameters:
      newFormatter - the Formatter to use (may not be null)
      Throws:
      SecurityException - if a security manager exists and if the caller does not have LoggingPermission("control").
      NullPointerException - if the given formatter is null.

    • getPushLevel

      public final 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:
      a non-null push level.

    • setPushLevel

      public final 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 importance with urgent priority.
      Parameters:
      level - any level object or null meaning off.
      Throws:
      SecurityException - if a security manager exists and the caller does not have LoggingPermission("control").
      IllegalStateException - if called from inside a push.

    • getPushFilter

      public final Filter getPushFilter()
      Gets the push filter. The default is null.
      Returns:
      the push filter or null.

    • setPushFilter

      public final 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 importance with urgent 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.

    • getComparator

      public final Comparator<? super LogRecord> getComparator()
      Gets the comparator used to order all LogRecord objects prior to formatting. If null then the order is unspecified.
      Returns:
      the LogRecord comparator.

    • setComparator

      public final void setComparator(Comparator<? super LogRecord> 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.

    • getCapacity

      public final 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.

    • setCapacity

      public final void setCapacity(int newCapacity)
      Sets the capacity for this handler. Pushes any buffered records to the email server as normal priority. The internal buffer is then cleared.
      Parameters:
      newCapacity - the max number of records. The default capacity of 1000 is used if the given capacity is less than one.
      Throws:
      SecurityException - if a security manager exists and the caller does not have LoggingPermission("control").
      IllegalStateException - if called from inside a push.
      Since:
      Angus Mail 2.0.3
      See Also:

    • getAuthenticator

      public final 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").

    • setAuthenticator

      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.

    • setAuthenticator

      public final void setAuthenticator(char... password)
      Sets the Authenticator used to login to the email server.
      Parameters:
      password - a password, empty array can be used to only supply a user name set by mail.user property, or null if no credentials are required.
      Throws:
      SecurityException - if a security manager exists and the caller does not have LoggingPermission("control").
      IllegalStateException - if called from inside a push.
      Since:
      JavaMail 1.4.6
      See Also:

    • setAuthentication

      public final void setAuthentication(String auth)
      Sets the Authenticator class name or password used to login to the email server.
      Parameters:
      auth - the class name of the authenticator, literal password, or empty string can be used to only supply a user name set by mail.user property. A null value can be used if no credentials are required.
      Throws:
      SecurityException - if a security manager exists and the caller does not have LoggingPermission("control").
      IllegalStateException - if called from inside a push.
      Since:
      Angus Mail 2.0.3
      See Also:

    • setMailProperties

      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. A key named verify can be declared to trigger verification.
      Parameters:
      props - properties object or null. A null value will supply the mailEntries from the LogManager. An empty properties will clear all existing mail properties assigned to this handler.
      Throws:
      SecurityException - if a security manager exists and the caller does not have LoggingPermission("control").
      IllegalStateException - if called from inside a push.

    • getMailProperties

      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").

    • setMailEntries

      public final void setMailEntries(String entries)
      Parses the given properties lines then clears and sets all of the mail properties used for the session. Any parsing errors are reported to the error manager. This method provides bean style properties support.

      The given string should be treated as lines of a properties file. The character '=' or ':' are used to separate an entry also known as a key/value pair. The line terminator characters \r or \n or \r\n are used to separate each entry. The characters '#!' together can be used to signal the end of an entry when escape characters are not supported.

      The example from the configuration section would be formatted as the following string: 

       mail.smtp.host:my-mail-server#!mail.to:me@example.com#!verify:local

      The key/value pairs are defined in the Java Mail API documentation. This Handler will also search the LogManager for defaults if needed. A key named verify can be declared to trigger verification.

      Parameters:
      entries - one or more key/value pairs. A null value will supply the mailEntries from the LogManager. An empty string or the literal null are all treated as empty properties and will clear all existing mail properties assigned to this handler.
      Throws:
      SecurityException - if a security manager exists and the caller does not have LoggingPermission("control").
      IllegalStateException - if called from inside a push.
      Since:
      Angus Mail 2.0.3
      See Also:

    • getMailEntries

      public final String getMailEntries()
      Formats the current mail properties as properties lines. Any formatting errors are reported to the error manager. The returned string should be treated as lines of a properties file. The value of this string is reconstructed from the properties object and therefore may be different from what was originally set. This method provides bean style properties support.
      Returns:
      string representation of the mail properties.
      Throws:
      SecurityException - if a security manager exists and the caller does not have LoggingPermission("control").
      IllegalStateException - if called from inside a push.
      Since:
      Angus Mail 2.0.3
      See Also:

    • getAttachmentFilters

      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.

    • setAttachmentFilters

      public final void setAttachmentFilters(Filter... filters)
      Sets the attachment filters.
      Parameters:
      filters - array of filters. A null array is treated the same as an empty array and will remove all attachments. A null index 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").
      IllegalStateException - if called from inside a push.

    • getAttachmentFormatters

      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.

    • setAttachmentFormatters

      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 - an array of formatters. A null array is treated as an empty array. Any null indexes is replaced with a SimpleFormatter.
      Throws:
      SecurityException - if a security manager exists and the caller does not have LoggingPermission("control").
      IllegalStateException - if called from inside a push.

    • getAttachmentNames

      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.

    • setAttachmentNames

      public final void setAttachmentNames(String... names)
      Sets the attachment file name for each attachment. All control characters are removed from the attachment names. This method will create a set of custom formatters.
      Parameters:
      names - an array of names. A null array is treated as an empty array. Any null or empty indexes are replaced with the string representation of the attachment formatter.
      Throws:
      SecurityException - if a security manager exists and the caller does not have LoggingPermission("control").
      IllegalStateException - if called from inside a push.
      See Also:

    • setAttachmentNames

      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. All control characters will be removed from the output of the formatter. 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").
      IllegalStateException - if called from inside a push.
      See Also:

    • setAttachmentNameFormatters

      public final void setAttachmentNameFormatters(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. All control characters will be removed from the output of the formatter. 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").
      IllegalStateException - if called from inside a push.
      Since:
      Angus Mail 2.0.3
      See Also:

    • getSubject

      public final 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.

    • getSubjectFormatter

      public final Formatter getSubjectFormatter()
      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.
      Since:
      Angus Mail 2.0.3

    • setSubject

      public final void setSubject(String subject)
      Sets a literal string for the email subject. All control characters are removed from the subject line of the email
      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:

    • setSubject

      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. All control characters will be removed from the formatter output. The toString method of the given formatter should be overridden to provide a useful subject, if possible.
      Parameters:
      format - the subject formatter or null for default formatter.
      Throws:
      SecurityException - if a security manager exists and the caller does not have LoggingPermission("control").
      IllegalStateException - if called from inside a push.
      See Also:

    • setSubjectFormatter

      public final void setSubjectFormatter(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. All control characters will be removed from the formatter output. The toString method of the given formatter should be overridden to provide a useful subject, if possible.
      Parameters:
      format - the subject formatter or null for default formatter.
      Throws:
      SecurityException - if a security manager exists and the caller does not have LoggingPermission("control").
      IllegalStateException - if called from inside a push.
      Since:
      Angus Mail 2.0.3
      See Also:

    • reportError

      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.
      Overrides:
      reportError in class Handler
      Parameters:
      msg - a descriptive string (may be null)
      ex - an exception (may be null)
      code - an error code defined in ErrorManager