MailHandler (JavaMail API documentation)
Date: 2018-10-22

com.sun.mail.util.logging

## Class MailHandler

- java.lang.Object
- - java.util.logging.Handler
  - - com.sun.mail.util.logging.MailHandler

-     public class MailHandler
      extends java.util.logging.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.
            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

  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 `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 `` 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. The attachment file names must not contain any line breaks. (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>.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. The subject line must not contain any line breaks. (defaults to the empty string)
  - <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 `remote`, the `Handler` will verify all local settings and try to establish a connection with the email server.
    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. 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 Summary

    Constructors
    Constructor and Description
    `MailHandler()` Creates a `MailHandler` that is configured by the `LogManager` configuration properties.
    `MailHandler(int capacity)` Creates a `MailHandler` that is configured by the `LogManager` configuration properties but overrides the `LogManager` capacity with the given capacity.
    `MailHandler(java.util.Properties props)` Creates a mail handler with the given mail properties.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `close()` Prevents any other records from being published.
    `void` | `flush()` Pushes any buffered records to the email server as normal priority.
    `java.util.logging.Filter[]` | `getAttachmentFilters()` Gets the attachment filters.
    `java.util.logging.Formatter[]` | `getAttachmentFormatters()` Gets the attachment formatters.
    `java.util.logging.Formatter[]` | `getAttachmentNames()` Gets the attachment name formatters.
    `Authenticator` | `getAuthenticator()` Gets the `Authenticator` used to login to the email server.
    `int` | `getCapacity()` Gets the number of log records the internal buffer can hold.
    `java.util.Comparator<? super java.util.logging.LogRecord>` | `getComparator()` Gets the comparator used to order all `LogRecord` objects prior to formatting.
    `java.util.Properties` | `getMailProperties()` Gets a copy of the mail properties used for the session.
    `java.util.logging.Filter` | `getPushFilter()` Gets the push filter.
    `java.util.logging.Level` | `getPushLevel()` Gets the push level.
    `java.util.logging.Formatter` | `getSubject()` Gets the formatter used to create the subject line.
    `boolean` | `isLoggable(java.util.logging.LogRecord record)` Check if this `Handler` would actually log a given `LogRecord` into its internal buffer.
    `void` | `publish(java.util.logging.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.
    `protected void` | `reportError(java.lang.String msg, java.lang.Exception ex, int code)` Protected convenience method to report an error to this Handler's ErrorManager.
    `void` | `setAttachmentFilters(java.util.logging.Filter... filters)` Sets the attachment filters.
    `void` | `setAttachmentFormatters(java.util.logging.Formatter... formatters)` Sets the attachment `Formatter` object for this handler.
    `void` | `setAttachmentNames(java.util.logging.Formatter... formatters)` Sets the attachment file name formatters.
    `void` | `setAttachmentNames(java.lang.String... names)` Sets the attachment file name for each attachment.
    `void` | `setAuthenticator(Authenticator auth)` Sets the `Authenticator` used to login to the email server.
    `void` | `setAuthenticator(char... password)` Sets the `Authenticator` used to login to the email server.
    `void` | `setComparator(java.util.Comparator<? super java.util.logging.LogRecord> c)` Sets the comparator used to order all `LogRecord` objects prior to formatting.
    `void` | `setLevel(java.util.logging.Level newLevel)` Set the log level specifying which message levels will be logged by this `Handler`.
    `void` | `setMailProperties(java.util.Properties props)` Sets the mail properties used for the session.
    `void` | `setPushFilter(java.util.logging.Filter filter)` Sets the push filter.
    `void` | `setPushLevel(java.util.logging.Level level)` Sets the push level.
    `void` | `setSubject(java.util.logging.Formatter format)` Sets the subject formatter for email.
    `void` | `setSubject(java.lang.String subject)` Sets a literal string for the email subject.

    - ### Methods inherited from class java.util.logging.Handler

      `getEncoding, getErrorManager, getFilter, getFormatter, getLevel, setEncoding, setErrorManager, setFilter, setFormatter`

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Constructor Detail

    - #### MailHandler

          public MailHandler()

      Creates a `MailHandler` that is configured by the `LogManager` configuration properties.
      Throws:
        `java.lang.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.
      Throws:
        `java.lang.IllegalArgumentException` - if `capacity` less than one.
        `java.lang.SecurityException` - if a security manager exists and the caller does not have `LoggingPermission("control")`.

    - #### MailHandler

          public MailHandler(java.util.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:
        `java.lang.NullPointerException` - if `props` is `null`.
        `java.lang.SecurityException` - if a security manager exists and the caller does not have `LoggingPermission("control")`.

  - ### Method Detail

    - #### isLoggable

          public boolean isLoggable(java.util.logging.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 `java.util.logging.Handler`
      Parameters:
        `record` - a `LogRecord`
      Returns:
        true if the `LogRecord` would be logged.

    - #### publish

          public void publish(java.util.logging.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 `java.util.logging.Handler`
      Parameters:
        `record` - description of the log event.

    - #### 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()`

    - #### 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 `java.util.logging.Handler`
      See Also:
        `push()`

    - #### 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.

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

    - #### setLevel

          public void setLevel(java.util.logging.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 `java.util.logging.Handler`
      Parameters:
        `newLevel` - the new value for the log level
      Throws:
        `java.lang.NullPointerException` - if `newLevel` is `null`.
        `java.lang.SecurityException` - if a security manager exists and the caller does not have `LoggingPermission("control")`.

    - #### getPushLevel

          public final java.util.logging.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.

    - #### setPushLevel

          public final void setPushLevel(java.util.logging.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` - Level object.
      Throws:
        `java.lang.NullPointerException` - if `level` is `null`.
        `java.lang.SecurityException` - if a security manager exists and the caller does not have `LoggingPermission("control")`.
        `java.lang.IllegalStateException` - if called from inside a push.

    - #### getPushFilter

          public final java.util.logging.Filter getPushFilter()

      Gets the push filter. The default is `null`.
      Returns:
        the push filter or `null`.

    - #### setPushFilter

          public final void setPushFilter(java.util.logging.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:
        `java.lang.SecurityException` - if a security manager exists and the caller does not have `LoggingPermission("control")`.
        `java.lang.IllegalStateException` - if called from inside a push.

    - #### getComparator

          public final java.util.Comparator<? super java.util.logging.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(java.util.Comparator<? super java.util.logging.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:
        `java.lang.SecurityException` - if a security manager exists and the caller does not have `LoggingPermission("control")`.
        `java.lang.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.

    - #### 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:
        `java.lang.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:
        `java.lang.SecurityException` - if a security manager exists and the caller does not have `LoggingPermission("control")`.
        `java.lang.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 or null if none is required.
      Throws:
        `java.lang.SecurityException` - if a security manager exists and the caller does not have `LoggingPermission("control")`.
        `java.lang.IllegalStateException` - if called from inside a push.
      Since:
        JavaMail 1.4.6
      See Also:
        `String.toCharArray()`

    - #### setMailProperties

          public final void setMailProperties(java.util.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:
        `java.lang.SecurityException` - if a security manager exists and the caller does not have `LoggingPermission("control")`.
        `java.lang.NullPointerException` - if `props` is `null`.
        `java.lang.IllegalStateException` - if called from inside a push.

    - #### getMailProperties

          public final java.util.Properties getMailProperties()

      Gets a copy of the mail properties used for the session.
      Returns:
        a non null properties object.
      Throws:
        `java.lang.SecurityException` - if a security manager exists and the caller does not have `LoggingPermission("control")`.

    - #### getAttachmentFilters

          public final java.util.logging.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(java.util.logging.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:
        `java.lang.SecurityException` - if a security manager exists and the caller does not have `LoggingPermission("control")`.
        `java.lang.NullPointerException` - if `filters` is `null`
        `java.lang.IndexOutOfBoundsException` - if the number of attachment name formatters do not match the number of attachment formatters.
        `java.lang.IllegalStateException` - if called from inside a push.

    - #### getAttachmentFormatters

          public final java.util.logging.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(java.util.logging.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:
        `java.lang.SecurityException` - if a security manager exists and the caller does not have `LoggingPermission("control")`.
        `java.lang.NullPointerException` - if the given array or any array index is `null`.
        `java.lang.IllegalStateException` - if called from inside a push.

    - #### getAttachmentNames

          public final java.util.logging.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(java.lang.String... names)

      Sets the attachment file name for each attachment. The caller must ensure that the attachment file names do not contain any line breaks. This method will create a set of custom formatters.
      Parameters:
        `names` - an array of names.
      Throws:
        `java.lang.SecurityException` - if a security manager exists and the caller does not have `LoggingPermission("control")`.
        `java.lang.IndexOutOfBoundsException` - if the number of attachment names do not match the number of attachment formatters.
        `java.lang.IllegalArgumentException` - if any name is empty.
        `java.lang.NullPointerException` - if any given array or name is `null`.
        `java.lang.IllegalStateException` - if called from inside a push.
      See Also:
        `Character.isISOControl(char)`, `Character.isISOControl(int)`

    - #### setAttachmentNames

          public final void setAttachmentNames(java.util.logging.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:
        `java.lang.SecurityException` - if a security manager exists and the caller does not have `LoggingPermission("control")`.
        `java.lang.IndexOutOfBoundsException` - if the number of attachment name formatters do not match the number of attachment formatters.
        `java.lang.NullPointerException` - if any given array or name is `null`.
        `java.lang.IllegalStateException` - if called from inside a push.
      See Also:
        `Character.isISOControl(char)`, `Character.isISOControl(int)`

    - #### getSubject

          public final java.util.logging.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.

    - #### setSubject

          public final void setSubject(java.lang.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:
        `java.lang.SecurityException` - if a security manager exists and the caller does not have `LoggingPermission("control")`.
        `java.lang.NullPointerException` - if `subject` is `null`.
        `java.lang.IllegalStateException` - if called from inside a push.
      See Also:
        `Character.isISOControl(char)`, `Character.isISOControl(int)`

    - #### setSubject

          public final void setSubject(java.util.logging.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:
        `java.lang.SecurityException` - if a security manager exists and the caller does not have `LoggingPermission("control")`.
        `java.lang.NullPointerException` - if `format` is `null`.
        `java.lang.IllegalStateException` - if called from inside a push.
      See Also:
        `Character.isISOControl(char)`, `Character.isISOControl(int)`

    - #### reportError

          protected void reportError(java.lang.String msg,
                                     java.lang.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 `java.util.logging.Handler`
      Parameters:
        `msg` - a descriptive string (may be null)
        `ex` - an exception (may be null)
        `code` - an error code defined in ErrorManager

Copyright © 1996-2013, Oracle and/or its affiliates. All Rights Reserved. Use is subject to license terms< /a>.