Class 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 <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>.encoding the name of the Java character set to use for the email message. (defaults to null, the default platform encoding).
    • <handler-name>.errorManager name of an ErrorManager class used to handle any configuration or mail transport problems. (defaults to java.util.logging.ErrorManager)
    • <handler-name>.filter name of a Filter class used for the body of the message. (defaults to null, allow all records)
    • <handler-name>.formatter name of a Formatter class used to format the body of this message. (defaults to java.util.logging.SimpleFormatter)
    • <handler-name>.level specifies the default level for this Handler (defaults to Level.WARNING).
    • <handler-name>.mail.bcc a comma separated list of addresses which will be blind carbon copied. Typically, this is set to the recipients that may need to be privately notified of a log message or notified that a log message was sent to a third party such as a support team. The empty string can be used to specify no blind carbon copied address. (defaults to null, none)
    • <handler-name>.mail.cc a comma separated list of addresses which will be carbon copied. Typically, this is set to the recipients that may need to be notified of a log message but, are not required to provide direct support. The empty string can be used to specify no carbon copied address. (defaults to null, none)
    • <handler-name>.mail.from a comma separated list of addresses which will be from addresses. Typically, this is set to the email address identifying the user running the application. The empty string can be used to override the default behavior and specify no from address. (defaults to the local address)
    • <handler-name>.mail.host the host name or IP address of the email server. (defaults to null, use default Java Mail behavior)
    • <handler-name>.mail.reply.to a comma separated list of addresses which will be reply-to addresses. Typically, this is set to the recipients that provide support for the application itself. The empty string can be used to specify no reply-to address. (defaults to null, none)
    • <handler-name>.mail.to a comma separated list of addresses which will be send-to addresses. Typically, this is set to the recipients that provide support for the application, system, and/or supporting infrastructure. The empty string can be used to specify no send-to address which overrides the default behavior. (defaults to local address.)
    • <handler-name>.mail.sender a single address identifying sender of the email; never equal to the from address. Typically, this is set to the email address identifying the application itself. The empty string can be used to specify no sender address. (defaults to null, none)
    • <handler-name>.subject the name of a Formatter class or string literal used to create the subject line. The empty string can be used to specify no subject. All control characters are removed from the subject line. (defaults to CollectorFormatter.)
    • <handler-name>.pushFilter the name of a Filter class used to trigger an early push. (defaults to null, no early push)
    • <handler-name>.pushLevel the level which will trigger an early push. (defaults to Level.OFF, only push when full)
    • <handler-name>.verify used to verify the Handler configuration prior to a push.
      • If the value is not set, equal to an empty string, or equal to the literal null then no settings are verified prior to a push.
      • If set to a value of limited then the Handler will verify minimal local machine settings.
      • If set to a value of local the Handler will verify all of settings of the local machine.
      • If set to a value of resolve, the Handler will verify all local settings and try to resolve the remote host name with the domain name server.
      • If set to a value of login, the Handler will verify all local settings and try to establish a connection with the email server.
      • If set to a value of remote, the Handler will verify all local settings, try to establish a connection with the email server, and try to verify the envelope of the email message.
      If this Handler is only implicitly closed by the LogManager, then verification should be turned on. (defaults to null, no verify).

    Normalization: The error manager, filters, and formatters when loaded from the LogManager are converted into canonical form inside the MailHandler. The pool of interned values is limited to each MailHandler object such that no two MailHandler objects created by the LogManager will be created sharing identical error managers, filters, or formatters. If a filter or formatter should not be interned then it is recommended to retain the identity equals and identity hashCode methods as the implementation. For a filter or formatter to be interned the class must implement the equals and hashCode methods. The recommended code to use for stateless filters and formatters is:

     public boolean equals(Object obj) {
         return obj == null ? false : obj.getClass() == getClass();
     }
    
     public int hashCode() {
         return 31 * getClass().hashCode();
     }
     

    Sorting: All LogRecord objects are ordered prior to formatting if this Handler has a non null comparator. Developers might be interested in sorting the formatted email by thread id, time, and sequence properties of a LogRecord. Where as system administrators might be interested in sorting the formatted email by thrown, level, time, and sequence properties of a LogRecord. If comparator for this handler is null then the order is unspecified.

    Formatting: The main message body is formatted using the Formatter returned by getFormatter(). Only records that pass the filter returned by getFilter() will be included in the message body. The subject Formatter will see all LogRecord objects that were published regardless of the current Filter. The MIME type of the message body can be overridden by adding a MIME entry using the simple class name of the body formatter as the file extension. The MIME type of the attachments can be overridden by changing the attachment file name extension or by editing the default MIME entry for a specific file name extension.

    Attachments: This Handler allows multiple attachments per each email message. The presence of an attachment formatter will change the content type of the email message to a multi-part message. The attachment order maps directly to the array index order in this Handler with zero index being the first attachment. The number of attachment formatters controls the number of attachments per email and the content type of each attachment. The attachment filters determine if a LogRecord will be included in an attachment. If an attachment filter is null then all records are included for that attachment. Attachments without content will be omitted from email message. The attachment name formatters create the file name for an attachment. Custom attachment name formatters can be used to generate an attachment name based on the contents of the attachment.

    Push Level and Push Filter: The push method, push level, and optional push filter can be used to conditionally trigger a push at or prior to full capacity. When a push occurs, the current buffer is formatted into an email and is sent to the email server. If the push method, push level, or push filter trigger a push then the outgoing email is flagged as high importance with urgent priority.

    Buffering: Log records that are published are stored in an internal buffer. When this buffer reaches capacity the existing records are formatted and sent in an email. Any published records can be sent before reaching capacity by explictly calling the flush, push, or close methods. If a circular buffer is required then this handler can be wrapped with a 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
    • Field Summary

      Fields 
      Modifier and Type Field Description
      private java.util.logging.Filter[] attachmentFilters
      Holds the filters for each attachment.
      private java.util.logging.Formatter[] attachmentFormatters
      Holds the formatters that create the content for each attachment.
      private java.util.logging.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 java.util.Comparator<? super java.util.logging.LogRecord> 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 java.util.logging.LogRecord[] data
      Holds all of the log records that will be used to create the email.
      private static java.util.logging.Filter[] EMPTY_FILTERS
      Use the emptyFilterArray method.
      private static java.util.logging.Formatter[] EMPTY_FORMATTERS
      Use the emptyFormatterArray method.
      private java.lang.String encoding
      Holds the encoding name for this handler.
      private java.util.logging.ErrorManager errorManager
      Holds the error manager for this handler.
      private java.util.logging.Filter filter
      Holds the entry and body filter for this handler.
      private java.util.logging.Formatter formatter
      Holds the entry and body filter for this handler.
      private boolean isWriting
      Determines if we are inside of a push.
      private java.util.logging.Level logLevel
      Holds the level for this handler.
      private static java.security.PrivilegedAction<java.lang.Object> MAILHANDLER_LOADER
      The action to set the context class loader for use with the JavaMail API.
      private java.util.Properties mailProps
      Holds all of the email server properties.
      private int[] matched
      A mapping of log record to matching filter index.
      private static int MIN_HEADER_SIZE
      Min byte size for header data.
      private static java.lang.ThreadLocal<java.lang.Integer> MUTEX
      A thread local mutex used to prevent logging loops.
      private static java.lang.Integer MUTEX_LINKAGE
      The used for linkage error reporting.
      private static java.lang.Integer MUTEX_PUBLISH
      The marker object used to report a publishing state.
      private static java.lang.Integer MUTEX_REPORT
      The used for the error reporting state.
      private static int offValue
      Cache the off value.
      private java.util.logging.Filter pushFilter
      Holds the push filter for trigger conditions requiring an early push.
      private java.util.logging.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 java.util.logging.Formatter subjectFormatter
      Holds the formatter used to create the subject line of the email.
    • Constructor Summary

      Constructors 
      Constructor 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 Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      private boolean alignAttachmentFilters()
      Expand or shrink the attachment filters with the attachment formatters.
      private boolean alignAttachmentNames()
      Expand or shrink the attachment name formatters with the attachment formatters.
      private boolean allowRestrictedHeaders()
      Determines if restricted headers are allowed in the current environment.
      private void appendContentLang​(MimePart p, java.util.Locale l)
      Appends the content language to the given mime part.
      private void appendFileName​(Part part, java.lang.String chunk)
      Constructs a file name from a formatter.
      private void appendFileName0​(Part part, java.lang.String chunk)
      It is assumed that file names are short and that in most cases getTail will be the only method that will produce a result.
      private void appendSubject​(Message msg, java.lang.String chunk)
      Constructs a subject line from a formatter.
      private void appendSubject0​(Message msg, java.lang.String chunk)
      It is assumed that subject lines are short and that in most cases getTail will be the only method that will produce a result.
      private static java.lang.String atIndexMsg​(int i)
      Outline the creation of the index error message.
      private static MessagingException attach​(MessagingException required, java.lang.Exception optional)
      Try to attach a suppressed exception to a MessagingException in any order that is possible.
      private static java.lang.RuntimeException attachmentMismatch​(int expected, int found)
      Outline the attachment mismatch message.
      private static java.lang.RuntimeException attachmentMismatch​(java.lang.String msg)
      A factory used to create a common attachment mismatch type.
      private void checkAccess()
      Calls log manager checkAccess if this is sealed.
      private void clearMatches​(int index)
      Clear previous matches when the filters are modified and there are existing log records that were matched.
      void close()
      Prevents any other records from being published.
      (package private) java.lang.String contentTypeOf​(java.lang.CharSequence chunk)
      Determines the mimeType of a formatter from the getHead call.
      (package private) java.lang.String contentTypeOf​(java.util.logging.Formatter f)
      Determines the mimeType of a formatter by the class name.
      private java.lang.String contentWithEncoding​(java.lang.String type, java.lang.String encoding)
      Replaces the charset parameter with the current encoding.
      private MimeBodyPart createBodyPart()
      Factory to create the in-line body part.
      private MimeBodyPart createBodyPart​(int index)
      Factory to create the attachment body part.
      private static java.util.logging.Formatter createSimpleFormatter()
      Factory method used to create a java.util.logging.SimpleFormatter.
      private java.util.logging.ErrorManager defaultErrorManager()
      Used to get or create the default ErrorManager used before init.
      private java.lang.String descriptionFrom​(java.util.Comparator<?> c, java.util.logging.Level l, java.util.logging.Filter f)
      Gets the description for the MimeMessage itself.
      private java.lang.String descriptionFrom​(java.util.logging.Formatter f, java.util.logging.Filter filter, java.util.logging.Formatter name)
      Creates a description for a body part.
      private static java.util.logging.Filter[] emptyFilterArray()
      Factory for empty filter arrays.
      private static java.util.logging.Formatter[] emptyFormatterArray()
      Factory for empty formatter arrays.
      private void envelopeFor​(Message msg, boolean priority)
      Creates all of the envelope information for a message.
      void flush()
      Pushes any buffered records to the email server as normal priority.
      private java.lang.String format​(java.util.logging.Formatter f, java.util.logging.LogRecord r)
      Creates the formatted log record or reports a formatting error.
      private java.lang.Object getAndSetContextClassLoader​(java.lang.Object ccl)
      Replaces the current context class loader with our class loader.
      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.
      private java.lang.String getClassId​(java.util.logging.Formatter f)
      Gets a class name represents the behavior of the formatter.
      java.util.Comparator<? super java.util.logging.LogRecord> getComparator()
      Gets the comparator used to order all LogRecord objects prior to formatting.
      private java.lang.String getContentType​(java.lang.String name)
      Determines the mimeType from the given file name.
      java.lang.String getEncoding()
      Return the character encoding for this Handler.
      private java.lang.String getEncodingName()
      Gets the encoding set for this handler, mime encoding, or file encoding.
      java.util.logging.ErrorManager getErrorManager()
      Retrieves the ErrorManager for this Handler.
      java.util.logging.Filter getFilter()
      Get the current Filter for this Handler.
      java.util.logging.Formatter getFormatter()
      Return the Formatter for this Handler.
      java.util.logging.Level getLevel()
      Get the log level specifying which messages will be logged by this Handler.
      private java.lang.String getLocalHost​(Service s)
      Gets the local host from the given service object.
      java.util.Properties getMailProperties()
      Gets a copy of the mail properties used for the session.
      private int getMatchedPart()
      This is used to get the filter index from when isLoggable and isAttachmentLoggable was invoked by publish method.
      java.util.logging.Filter getPushFilter()
      Gets the push filter.
      java.util.logging.Level getPushLevel()
      Gets the push level.
      private Session getSession​(Message msg)
      Google App Engine doesn't support Message.getSession.
      java.util.logging.Formatter getSubject()
      Gets the formatter used to create the subject line.
      private void grow()
      Expands the internal buffer up to the capacity.
      private static boolean hasValue​(java.lang.String name)
      Checks that a string is not empty and not equal to the literal "null".
      private java.lang.String head​(java.util.logging.Formatter f)
      Creates the head or reports a formatting error.
      private void init​(java.util.Properties props)
      Configures the handler properties from the log manager.
      private void initAttachmentFilters​(java.lang.String p)
      Parses LogManager string values into objects used by this handler.
      private void initAttachmentFormaters​(java.lang.String p)
      Parses LogManager string values into objects used by this handler.
      private void initAttachmentNames​(java.lang.String p)
      Parses LogManager string values into objects used by this handler.
      private void initAuthenticator​(java.lang.String p)
      Parses LogManager string values into objects used by this handler.
      private void initCapacity​(java.lang.String p)
      Parses LogManager string values into objects used by this handler.
      private void initComparator​(java.lang.String p)
      Parses LogManager string values into objects used by this handler.
      private void initEncoding​(java.lang.String p)
      Parses LogManager string values into objects used by this handler.
      private void initErrorManager​(java.lang.String p)
      Parses LogManager string values into objects used by this handler.
      private void initFilter​(java.lang.String p)
      Parses LogManager string values into objects used by this handler.
      private void initFormatter​(java.lang.String p)
      Parses LogManager string values into objects used by this handler.
      private void initLevel​(java.lang.String p)
      Parses LogManager string values into objects used by this handler.
      private void initPushFilter​(java.lang.String p)
      Parses LogManager string values into objects used by this handler.
      private void initPushLevel​(java.lang.String p)
      Parses LogManager string values into objects used by this handler.
      private Session initSession()
      Creates a session using a proxy properties object.
      private void initSubject​(java.lang.String p)
      Parses LogManager string values into objects used by this handler.
      private void intern()
      Interns the error manager, formatters, and filters contained in this handler.
      private java.lang.Object intern​(java.util.Map<java.lang.Object,​java.lang.Object> m, java.lang.Object o)
      If possible performs an intern of the given object into the map.
      private boolean isAttachmentLoggable​(java.util.logging.LogRecord record)
      Check if any attachment would actually format the given LogRecord.
      private static boolean isEmpty​(java.lang.CharSequence s)
      Checks a char sequence value for null or empty.
      boolean isLoggable​(java.util.logging.LogRecord record)
      Check if this Handler would actually log a given LogRecord into its internal buffer.
      (package private) boolean isMissingContent​(Message msg, java.lang.Throwable t)
      Determines if the given throwable is a no content exception.
      private boolean isPushable​(java.util.logging.LogRecord record)
      Check if this Handler would push after storing the LogRecord into its internal buffer.
      private java.util.Locale localeFor​(java.util.logging.LogRecord r)
      Gets the locale for the given log record from the resource bundle.
      void postConstruct()
      A callback method for when this object is about to be placed into commission.
      void preDestroy()
      A callback method for when this object is about to be decommissioned.
      void publish​(java.util.logging.LogRecord record)
      Stores a LogRecord in the internal buffer.
      private void publish0​(java.util.logging.LogRecord record)
      Performs the publish after the record has been filtered.
      void push()
      Pushes any buffered records to the email server as high importance with urgent priority.
      private void push​(boolean priority, int code)
      Used to perform push or flush.
      private java.util.logging.Filter[] readOnlyAttachmentFilters()
      Gets the attachment filters using a happens-before relationship between this method and setAttachmentFilters.
      private void releaseMutex()
      Releases the mutex held by the current thread.
      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.
      private void reportError​(Message msg, java.lang.Exception ex, int code)
      Converts a mime message to a raw string or formats the reason why message can't be changed to raw string and reports it.
      private void reportFilterError​(java.util.logging.LogRecord record)
      Used when a log record was loggable prior to being inserted into the buffer but at the time of formatting was no longer loggable.
      private void reportLinkageError​(java.lang.Throwable le, int code)
      Reports the given linkage error or runtime exception.
      private void reportNonDiscriminating​(java.lang.Object o, java.lang.Object found)
      Reports equals implementations that do not discriminate between objects of different types or subclass types.
      private void reportNonSymmetric​(java.lang.Object o, java.lang.Object found)
      Reports symmetric contract violations an equals implementation.
      private void reportNullError​(int code)
      Used to outline the bytes to report a null pointer exception.
      private void reportUnexpectedSend​(MimeMessage msg, java.lang.String verify, java.lang.Exception cause)
      Reports that an empty content message was sent and should not have been.
      private void reportUnPublishedError​(java.util.logging.LogRecord record)
      Report to the error manager that a logging loop was detected and we are going to break the cycle of messages.
      private void reset()
      Sets the size to zero and clears the current buffer.
      private void saveChangesNoContent​(Message abort, java.lang.String msg)
      Handles all exceptions thrown when save changes is called on a message that doesn't have any content.
      private void send​(Message msg, boolean priority, int code)
      Used to send the generated email or write its contents to the error manager for this handler.
      private void setAcceptLang​(Part p)
      Sets the accept language to the default locale of the JVM.
      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.lang.String... names)
      Sets the attachment file name for each attachment.
      void setAttachmentNames​(java.util.logging.Formatter... formatters)
      Sets the attachment file name formatters.
      void setAuthenticator​(char... password)
      Sets the Authenticator used to login to the email server.
      void setAuthenticator​(Authenticator auth)
      Sets the Authenticator used to login to the email server.
      private void setAuthenticator0​(Authenticator auth)
      A private hook to handle possible future overrides.
      private void setAutoSubmitted​(Message msg)
      Signals that this message was generated by automatic process.
      private void setCapacity0​(int newCapacity)
      Sets the capacity for this handler.
      void setComparator​(java.util.Comparator<? super java.util.logging.LogRecord> c)
      Sets the comparator used to order all LogRecord objects prior to formatting.
      private void setContent​(MimePart part, java.lang.CharSequence buf, java.lang.String type)
      Set the content for a part using the encoding assigned to the handler.
      private void setDefaultFrom​(Message msg)
      Sets the from header to the local address.
      private void setDefaultRecipient​(Message msg, Message.RecipientType type)
      Computes the default to-address if none was specified.
      void setEncoding​(java.lang.String encoding)
      Set the character encoding used by this Handler.
      private void setEncoding0​(java.lang.String e)
      Set the character encoding used by this handler.
      private void setErrorContent​(MimeMessage msg, java.lang.String verify, java.lang.Throwable t)
      Creates and sets the message content from the given Throwable.
      void setErrorManager​(java.util.logging.ErrorManager em)
      Define an ErrorManager for this Handler.
      private void setErrorManager0​(java.util.logging.ErrorManager em)
      Sets the error manager on this handler and the super handler.
      void setFilter​(java.util.logging.Filter newFilter)
      Set a Filter to control output on this Handler.
      void setFormatter​(java.util.logging.Formatter newFormatter)
      Set a Formatter.
      private void setFrom​(Message msg)
      Sets from address header.
      private void setIncompleteCopy​(Message msg)
      Used to signal that body parts are missing from a message.
      void setLevel​(java.util.logging.Level newLevel)
      Set the log level specifying which message levels will be logged by this Handler.
      private void setMailer​(Message msg)
      Sets the x-mailer header.
      void setMailProperties​(java.util.Properties props)
      Sets the mail properties used for the session.
      private void setMailProperties0​(java.util.Properties props)
      A private hook to handle overrides when the public method is declared non final.
      private void setMatchedPart​(int index)
      This is used to record the filter index when isLoggable and isAttachmentLoggable was invoked by publish method.
      private void setPriority​(Message msg)
      Sets the priority and importance headers.
      void setPushFilter​(java.util.logging.Filter filter)
      Sets the push filter.
      void setPushLevel​(java.util.logging.Level level)
      Sets the push level.
      private boolean setRecipient​(Message msg, java.lang.String key, Message.RecipientType type)
      Sets the recipient for the given message.
      private void setReplyTo​(Message msg)
      Sets reply-to address header.
      private void setSender​(Message msg)
      Sets sender address header.
      void setSubject​(java.lang.String subject)
      Sets a literal string for the email subject.
      void setSubject​(java.util.logging.Formatter format)
      Sets the subject formatter for email.
      private void sort()
      Performs a sort on the records if needed.
      private java.lang.String tail​(java.util.logging.Formatter f, java.lang.String def)
      Creates the tail or reports a formatting error.
      private java.lang.String toMsgString​(java.lang.Throwable t)
      Converts a throwable to a message string.
      private AddressException tooManyAddresses​(Address[] address, int offset)
      A common factory used to create the too many addresses exception.
      private java.lang.String toRawString​(Message msg)
      Converts an email message to a raw string.
      private java.lang.String toString​(java.util.logging.Formatter f)
      Ensure that a formatter creates a valid string for a part name.
      private boolean tryMutex()
      Used to detect reentrance by the current thread to the publish method.
      private Session updateSession()
      Used to update the cached session object based on changes in mail properties or authenticator.
      private static void verifyAddresses​(Address[] all)
      Calls validate for every address given.
      private static java.net.InetAddress verifyHost​(java.lang.String host)
      Perform a lookup of the host address or FQDN.
      private static void verifyProperties​(Session session, java.lang.String protocol)
      Cache common session properties into the LogManagerProperties.
      private void verifySettings​(Session session)
      Checks all of the settings if the caller requests a verify and a verify was not performed yet and no verify is in progress.
      private void verifySettings0​(Session session, java.lang.String verify)
      Checks all of the settings using the given setting.
      private Message writeLogRecords​(int code)
      Formats all records in the buffer and places the output in a Message.
      private Message writeLogRecords0()
      Formats all records in the buffer and places the output in a Message.
      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
    • Field Detail

      • EMPTY_FILTERS

        private static final java.util.logging.Filter[] EMPTY_FILTERS
        Use the emptyFilterArray method.
      • EMPTY_FORMATTERS

        private static final java.util.logging.Formatter[] EMPTY_FORMATTERS
        Use the emptyFormatterArray method.
      • MIN_HEADER_SIZE

        private static final int MIN_HEADER_SIZE
        Min byte size for header data. Used for initial arrays sizing.
        See Also:
        Constant Field Values
      • offValue

        private static final int offValue
        Cache the off value.
      • MAILHANDLER_LOADER

        private static final java.security.PrivilegedAction<java.lang.Object> MAILHANDLER_LOADER
        The action to set the context class loader for use with the JavaMail API. Load and pin this before it is loaded in the close method. The field is declared as java.security.PrivilegedAction so WebappClassLoader.clearReferencesStaticFinal() method will ignore this field.
      • MUTEX

        private static final java.lang.ThreadLocal<java.lang.Integer> MUTEX
        A thread local mutex used to prevent logging loops. This code has to be prepared to deal with unexpected null values since the WebappClassLoader.clearReferencesThreadLocals() and InnocuousThread.eraseThreadLocals() can remove thread local values. The MUTEX has 5 states: 1. A null value meaning default state of not publishing. 2. MUTEX_PUBLISH on first entry of a push or publish. 3. The index of the first filter to accept a log record. 4. MUTEX_REPORT when cycle of records is detected. 5. MUTEXT_LINKAGE when a linkage error is reported.
      • MUTEX_PUBLISH

        private static final java.lang.Integer MUTEX_PUBLISH
        The marker object used to report a publishing state. This must be less than the body filter index (-1).
      • MUTEX_REPORT

        private static final java.lang.Integer MUTEX_REPORT
        The used for the error reporting state. This must be less than the PUBLISH state.
      • MUTEX_LINKAGE

        private static final java.lang.Integer MUTEX_LINKAGE
        The used for linkage error reporting. This must be less than the REPORT state.
      • sealed

        private volatile boolean sealed
        Used to turn off security checks.
      • isWriting

        private boolean isWriting
        Determines if we are inside of a push. Makes the handler properties read-only during a push.
      • mailProps

        private java.util.Properties mailProps
        Holds all of the email server properties.
      • auth

        private Authenticator auth
        Holds the authenticator required to login to the email server.
      • session

        private Session session
        Holds the session object used to generate emails. Sessions can be shared by multiple threads. See JDK-6228391 and K 6278.
      • matched

        private int[] matched
        A mapping of log record to matching filter index. Negative one is used to track the body filter. Zero and greater is used to track the attachment parts. All indexes less than or equal to the matched value have already seen the given log record.
      • data

        private java.util.logging.LogRecord[] data
        Holds all of the log records that will be used to create the email.
      • size

        private int size
        The number of log records in the buffer.
      • capacity

        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.
      • comparator

        private java.util.Comparator<? super java.util.logging.LogRecord> 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.
      • subjectFormatter

        private java.util.logging.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.
      • pushLevel

        private java.util.logging.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.
      • pushFilter

        private java.util.logging.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.
      • filter

        private volatile java.util.logging.Filter filter
        Holds the entry and body filter for this handler. There is no way to un-seal the super handler.
      • logLevel

        private volatile java.util.logging.Level logLevel
        Holds the level for this handler. There is no way to un-seal the super handler.
      • attachmentFilters

        private volatile java.util.logging.Filter[] attachmentFilters
        Holds the filters for each attachment. Filters are optional for each attachment. This is declared volatile because this is treated as copy-on-write. The VO_VOLATILE_REFERENCE_TO_ARRAY warning is a false positive.
      • encoding

        private java.lang.String encoding
        Holds the encoding name for this handler. There is no way to un-seal the super handler.
      • formatter

        private java.util.logging.Formatter formatter
        Holds the entry and body filter for this handler. There is no way to un-seal the super handler.
      • attachmentFormatters

        private java.util.logging.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.
      • attachmentNames

        private java.util.logging.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.
      • contentTypes

        private FileTypeMap contentTypes
        Used to override the content type for the body and set the content type for each attachment.
      • errorManager

        private volatile java.util.logging.ErrorManager errorManager
        Holds the error manager for this handler. There is no way to un-seal the super handler.
    • 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.
      • publish0

        private void publish0​(java.util.logging.LogRecord record)
        Performs the publish after the record has been filtered.
        Parameters:
        record - the record.
        Since:
        JavaMail 1.4.5
      • reportUnPublishedError

        private void reportUnPublishedError​(java.util.logging.LogRecord record)
        Report to the error manager that a logging loop was detected and we are going to break the cycle of messages. It is possible that a custom error manager could continue the cycle in which case we will stop trying to report errors.
        Parameters:
        record - the record or null.
        Since:
        JavaMail 1.4.6
      • tryMutex

        private boolean tryMutex()
        Used to detect reentrance by the current thread to the publish method. This mutex is thread local scope and will not block other threads. The state is advanced on if the current thread is in a reset state.
        Returns:
        true if the mutex was acquired.
        Since:
        JavaMail 1.4.6
      • releaseMutex

        private void releaseMutex()
        Releases the mutex held by the current thread. This mutex is thread local scope and will not block other threads.
        Since:
        JavaMail 1.4.6
      • getMatchedPart

        private int getMatchedPart()
        This is used to get the filter index from when isLoggable and isAttachmentLoggable was invoked by publish method.
        Returns:
        the filter index or MUTEX_PUBLISH if unknown.
        Throws:
        java.lang.NullPointerException - if tryMutex was not called.
        Since:
        JavaMail 1.5.5
      • setMatchedPart

        private void setMatchedPart​(int index)
        This is used to record the filter index when isLoggable and isAttachmentLoggable was invoked by publish method.
        Parameters:
        index - the filter index.
        Since:
        JavaMail 1.5.5
      • clearMatches

        private void clearMatches​(int index)
        Clear previous matches when the filters are modified and there are existing log records that were matched.
        Parameters:
        index - the lowest filter index to clear.
        Since:
        JavaMail 1.5.5
      • 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()
      • 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").
      • getLevel

        public java.util.logging.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 java.util.logging.Handler
        Returns:
        the level of messages being logged.
      • getErrorManager

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

        public void setErrorManager​(java.util.logging.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 java.util.logging.Handler
        Parameters:
        em - the new ErrorManager
        Throws:
        java.lang.SecurityException - if a security manager exists and if the caller does not have LoggingPermission("control").
        java.lang.NullPointerException - if the given error manager is null.
      • setErrorManager0

        private void setErrorManager0​(java.util.logging.ErrorManager em)
        Sets the error manager on this handler and the super handler. In secure environments the super call may not be allowed which is not a failure condition as it is an attempt to free the unused handler error manager.
        Parameters:
        em - a non null error manager.
        Throws:
        java.lang.NullPointerException - if the given error manager is null.
        Since:
        JavaMail 1.5.6
      • getFilter

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

        public void setFilter​(java.util.logging.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 java.util.logging.Handler
        Parameters:
        newFilter - a Filter object (may be null)
        Throws:
        java.lang.SecurityException - if a security manager exists and if the caller does not have LoggingPermission("control").
      • getEncoding

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

        public void setEncoding​(java.lang.String encoding)
                         throws java.io.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 java.util.logging.Handler
        Parameters:
        encoding - The name of a supported character encoding. May be null, to indicate the default platform encoding.
        Throws:
        java.lang.SecurityException - if a security manager exists and if the caller does not have LoggingPermission("control").
        java.io.UnsupportedEncodingException - if the named encoding is not supported.
      • setEncoding0

        private void setEncoding0​(java.lang.String e)
                           throws java.io.UnsupportedEncodingException
        Set the character encoding used by this handler. This method does not check permissions of the caller.
        Parameters:
        e - any encoding name or null for the default.
        Throws:
        java.io.UnsupportedEncodingException - if the given encoding is not supported.
      • getFormatter

        public java.util.logging.Formatter getFormatter()
        Return the Formatter for this Handler.
        Overrides:
        getFormatter in class java.util.logging.Handler
        Returns:
        the Formatter (may be null).
      • setFormatter

        public void setFormatter​(java.util.logging.Formatter newFormatter)
                          throws java.lang.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 java.util.logging.Handler
        Parameters:
        newFormatter - the Formatter to use (may not be null)
        Throws:
        java.lang.SecurityException - if a security manager exists and if the caller does not have LoggingPermission("control").
        java.lang.NullPointerException - if the given formatter is null.
      • 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, empty array can be used to only supply a user name set by mail.user property, or null if no credentials are 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()
      • setAuthenticator0

        private void setAuthenticator0​(Authenticator auth)
        A private hook to handle possible future overrides. See public method.
        Parameters:
        auth - see public method.
        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.
      • 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.
      • setMailProperties0

        private void setMailProperties0​(java.util.Properties props)
        A private hook to handle overrides when the public method is declared non final. See public method for details.
        Parameters:
        props - see public method.
      • 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. All control characters are removed from the attachment names. 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. 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:
        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. All control characters are removed from the subject line.
        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. 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.
        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
      • checkAccess

        private void checkAccess()
        Calls log manager checkAccess if this is sealed.
      • contentTypeOf

        final java.lang.String contentTypeOf​(java.lang.CharSequence chunk)
        Determines the mimeType of a formatter from the getHead call. This could be made protected, or a new class could be created to do this type of conversion. Currently, this is only used for the body since the attachments are computed by filename. Package-private for unit testing.
        Parameters:
        chunk - any char sequence or null.
        Returns:
        return the mime type or null for text/plain.
      • contentTypeOf

        final java.lang.String contentTypeOf​(java.util.logging.Formatter f)
        Determines the mimeType of a formatter by the class name. This method avoids calling getHead and getTail of content formatters during verify because they might trigger side effects or excessive work. The name formatters and subject are usually safe to call. Package-private for unit testing.
        Parameters:
        f - the formatter or null.
        Returns:
        return the mime type or null, meaning text/plain.
        Since:
        JavaMail 1.5.6
      • isMissingContent

        final boolean isMissingContent​(Message msg,
                                       java.lang.Throwable t)
        Determines if the given throwable is a no content exception. It is assumed Transport.sendMessage will call Message.writeTo so we need to ignore any exceptions that could be layered on top of that call chain to infer that sendMessage is failing because of writeTo. Package-private for unit testing.
        Parameters:
        msg - the message without content.
        t - the throwable chain to test.
        Returns:
        true if the throwable is a missing content exception.
        Throws:
        java.lang.NullPointerException - if any of the arguments are null.
        Since:
        JavaMail 1.4.5
      • reportError

        private void reportError​(Message msg,
                                 java.lang.Exception ex,
                                 int code)
        Converts a mime message to a raw string or formats the reason why message can't be changed to raw string and reports it.
        Parameters:
        msg - the mime message.
        ex - the original exception.
        code - the ErrorManager code.
        Since:
        JavaMail 1.4.5
      • reportLinkageError

        private void reportLinkageError​(java.lang.Throwable le,
                                        int code)
        Reports the given linkage error or runtime exception. The current LogManager code will stop closing all remaining handlers if an error is thrown during resetLogger. This is a workaround for GLASSFISH-21258 and JDK-8152515.
        Parameters:
        le - the linkage error or a RuntimeException.
        code - the ErrorManager code.
        Throws:
        java.lang.NullPointerException - if error is null.
        Since:
        JavaMail 1.5.3
      • getContentType

        private java.lang.String getContentType​(java.lang.String name)
        Determines the mimeType from the given file name. Used to override the body content type and used for all attachments.
        Parameters:
        name - the file name or class name.
        Returns:
        the mime type or null for text/plain.
      • getEncodingName

        private java.lang.String getEncodingName()
        Gets the encoding set for this handler, mime encoding, or file encoding.
        Returns:
        the java charset name, never null.
        Since:
        JavaMail 1.4.5
      • setContent

        private void setContent​(MimePart part,
                                java.lang.CharSequence buf,
                                java.lang.String type)
                         throws MessagingException
        Set the content for a part using the encoding assigned to the handler.
        Parameters:
        part - the part to assign.
        buf - the formatted data.
        type - the mime type or null, meaning text/plain.
        Throws:
        MessagingException - if there is a problem.
      • contentWithEncoding

        private java.lang.String contentWithEncoding​(java.lang.String type,
                                                     java.lang.String encoding)
        Replaces the charset parameter with the current encoding.
        Parameters:
        type - the content type.
        encoding - the java charset name.
        Returns:
        the type with a specified encoding.
      • setCapacity0

        private void setCapacity0​(int newCapacity)
        Sets the capacity for this handler. This method is kept private because we would have to define a public policy for when the size is greater than the capacity. E.G. do nothing, flush now, truncate now, push now and resize.
        Parameters:
        newCapacity - the max number of records.
        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.
      • readOnlyAttachmentFilters

        private java.util.logging.Filter[] readOnlyAttachmentFilters()
        Gets the attachment filters using a happens-before relationship between this method and setAttachmentFilters. The attachment filters are treated as copy-on-write, so the returned array must never be modified or published outside this class.
        Returns:
        a read only array of filters.
      • emptyFormatterArray

        private static java.util.logging.Formatter[] emptyFormatterArray()
        Factory for empty formatter arrays.
        Returns:
        an empty array.
      • emptyFilterArray

        private static java.util.logging.Filter[] emptyFilterArray()
        Factory for empty filter arrays.
        Returns:
        an empty array.
      • alignAttachmentNames

        private boolean alignAttachmentNames()
        Expand or shrink the attachment name formatters with the attachment formatters.
        Returns:
        true if size was changed.
      • alignAttachmentFilters

        private boolean alignAttachmentFilters()
        Expand or shrink the attachment filters with the attachment formatters.
        Returns:
        true if the size was changed.
      • reset

        private void reset()
        Sets the size to zero and clears the current buffer.
      • grow

        private void grow()
        Expands the internal buffer up to the capacity.
      • init

        private void init​(java.util.Properties props)
        Configures the handler properties from the log manager.
        Parameters:
        props - the given mail properties. Maybe null and are never captured by this handler.
        Throws:
        java.lang.SecurityException - if a security manager exists and the caller does not have LoggingPermission("control").
      • intern

        private void intern()
        Interns the error manager, formatters, and filters contained in this handler. The comparator is not interned. This method can only be called from init after all of formatters and filters are in a constructed and in a consistent state.
        Since:
        JavaMail 1.5.0
      • intern

        private java.lang.Object intern​(java.util.Map<java.lang.Object,​java.lang.Object> m,
                                        java.lang.Object o)
                                 throws java.lang.Exception
        If possible performs an intern of the given object into the map. If the object can not be interned the given object is returned.
        Parameters:
        m - the map used to record the interned values.
        o - the object to try an intern.
        Returns:
        the original object or an intern replacement.
        Throws:
        java.lang.SecurityException - if this operation is not allowed by the security manager.
        java.lang.Exception - if there is an unexpected problem.
        Since:
        JavaMail 1.5.0
      • createSimpleFormatter

        private static java.util.logging.Formatter createSimpleFormatter()
        Factory method used to create a java.util.logging.SimpleFormatter.
        Returns:
        a new SimpleFormatter.
        Since:
        JavaMail 1.5.6
      • isEmpty

        private static boolean isEmpty​(java.lang.CharSequence s)
        Checks a char sequence value for null or empty.
        Parameters:
        s - the char sequence.
        Returns:
        true if the given string is null or zero length.
      • hasValue

        private static boolean hasValue​(java.lang.String name)
        Checks that a string is not empty and not equal to the literal "null".
        Parameters:
        name - the string to check for a value.
        Returns:
        true if the string has a valid value.
      • initAttachmentFilters

        private void initAttachmentFilters​(java.lang.String p)
        Parses LogManager string values into objects used by this handler.
        Parameters:
        p - the handler class name used as the prefix.
        Throws:
        java.lang.NullPointerException - if the given argument is null.
        java.lang.SecurityException - if not allowed.
      • initAttachmentFormaters

        private void initAttachmentFormaters​(java.lang.String p)
        Parses LogManager string values into objects used by this handler.
        Parameters:
        p - the handler class name used as the prefix.
        Throws:
        java.lang.NullPointerException - if the given argument is null.
        java.lang.SecurityException - if not allowed.
      • initAttachmentNames

        private void initAttachmentNames​(java.lang.String p)
        Parses LogManager string values into objects used by this handler.
        Parameters:
        p - the handler class name used as the prefix.
        Throws:
        java.lang.NullPointerException - if the given argument is null.
        java.lang.SecurityException - if not allowed.
      • initAuthenticator

        private void initAuthenticator​(java.lang.String p)
        Parses LogManager string values into objects used by this handler.
        Parameters:
        p - the handler class name used as the prefix.
        Throws:
        java.lang.NullPointerException - if the given argument is null.
        java.lang.SecurityException - if not allowed.
      • initLevel

        private void initLevel​(java.lang.String p)
        Parses LogManager string values into objects used by this handler.
        Parameters:
        p - the handler class name used as the prefix.
        Throws:
        java.lang.NullPointerException - if the given argument is null.
        java.lang.SecurityException - if not allowed.
      • initFilter

        private void initFilter​(java.lang.String p)
        Parses LogManager string values into objects used by this handler.
        Parameters:
        p - the handler class name used as the prefix.
        Throws:
        java.lang.NullPointerException - if the given argument is null.
        java.lang.SecurityException - if not allowed.
      • initCapacity

        private void initCapacity​(java.lang.String p)
        Parses LogManager string values into objects used by this handler.
        Parameters:
        p - the handler class name used as the prefix.
        Throws:
        java.lang.NullPointerException - if argument is null.
        java.lang.SecurityException - if not allowed.
      • initEncoding

        private void initEncoding​(java.lang.String p)
        Parses LogManager string values into objects used by this handler.
        Parameters:
        p - the handler class name used as the prefix.
        Throws:
        java.lang.NullPointerException - if the given argument is null.
        java.lang.SecurityException - if not allowed.
      • defaultErrorManager

        private java.util.logging.ErrorManager defaultErrorManager()
        Used to get or create the default ErrorManager used before init.
        Returns:
        the super error manager or a new ErrorManager.
        Since:
        JavaMail 1.5.3
      • initErrorManager

        private void initErrorManager​(java.lang.String p)
        Parses LogManager string values into objects used by this handler.
        Parameters:
        p - the handler class name used as the prefix.
        Throws:
        java.lang.NullPointerException - if the given argument is null.
        java.lang.SecurityException - if not allowed.
      • initFormatter

        private void initFormatter​(java.lang.String p)
        Parses LogManager string values into objects used by this handler.
        Parameters:
        p - the handler class name used as the prefix.
        Throws:
        java.lang.NullPointerException - if the given argument is null.
        java.lang.SecurityException - if not allowed.
      • initComparator

        private void initComparator​(java.lang.String p)
        Parses LogManager string values into objects used by this handler.
        Parameters:
        p - the handler class name used as the prefix.
        Throws:
        java.lang.NullPointerException - if the given argument is null.
        java.lang.SecurityException - if not allowed.
      • initPushLevel

        private void initPushLevel​(java.lang.String p)
        Parses LogManager string values into objects used by this handler.
        Parameters:
        p - the handler class name used as the prefix.
        Throws:
        java.lang.NullPointerException - if the given argument is null.
        java.lang.SecurityException - if not allowed.
      • initPushFilter

        private void initPushFilter​(java.lang.String p)
        Parses LogManager string values into objects used by this handler.
        Parameters:
        p - the handler class name used as the prefix.
        Throws:
        java.lang.NullPointerException - if the given argument is null.
        java.lang.SecurityException - if not allowed.
      • initSubject

        private void initSubject​(java.lang.String p)
        Parses LogManager string values into objects used by this handler.
        Parameters:
        p - the handler class name used as the prefix.
        Throws:
        java.lang.NullPointerException - if the given argument is null.
        java.lang.SecurityException - if not allowed.
      • isAttachmentLoggable

        private boolean isAttachmentLoggable​(java.util.logging.LogRecord record)
        Check if any attachment would actually format the given LogRecord. This method does not check if the handler is level is set to OFF or if the handler is closed.
        Parameters:
        record - a LogRecord
        Returns:
        true if the LogRecord would be formatted.
      • isPushable

        private boolean isPushable​(java.util.logging.LogRecord record)
        Check if this Handler would push after storing the LogRecord into its internal buffer.
        Parameters:
        record - a LogRecord
        Returns:
        true if the LogRecord triggers an email push.
        Throws:
        java.lang.NullPointerException - if tryMutex was not called.
      • push

        private void push​(boolean priority,
                          int code)
        Used to perform push or flush.
        Parameters:
        priority - true for high priority otherwise false for normal.
        code - the error manager code.
      • send

        private void send​(Message msg,
                          boolean priority,
                          int code)
        Used to send the generated email or write its contents to the error manager for this handler. This method does not hold any locks so new records can be added to this handler during a send or failure.
        Parameters:
        msg - the message or null.
        priority - true for high priority or false for normal.
        code - the ErrorManager code.
        Throws:
        java.lang.NullPointerException - if message is null.
      • sort

        private void sort()
        Performs a sort on the records if needed. Any exception thrown during a sort is considered a formatting error.
      • writeLogRecords

        private Message writeLogRecords​(int code)
        Formats all records in the buffer and places the output in a Message. This method under most conditions will catch, report, and continue when exceptions occur. This method holds a lock on this handler.
        Parameters:
        code - the error manager code.
        Returns:
        null if there are no records or is currently in a push. Otherwise a new message is created with a formatted message and attached session.
      • writeLogRecords0

        private Message writeLogRecords0()
                                  throws java.lang.Exception
        Formats all records in the buffer and places the output in a Message. This method under most conditions will catch, report, and continue when exceptions occur.
        Returns:
        null if there are no records or is currently in a push. Otherwise a new message is created with a formatted message and attached session.
        Throws:
        MessagingException - if there is a problem.
        java.io.IOException - if there is a problem.
        java.lang.RuntimeException - if there is an unexpected problem.
        java.lang.Exception
        Since:
        JavaMail 1.5.3
      • verifySettings

        private void verifySettings​(Session session)
        Checks all of the settings if the caller requests a verify and a verify was not performed yet and no verify is in progress. A verify is performed on create because this handler may be at the end of a handler chain and therefore may not see any log records until LogManager.reset() is called and at that time all of the settings have been cleared.
        Parameters:
        session - the current session or null.
        Since:
        JavaMail 1.4.4
      • verifySettings0

        private void verifySettings0​(Session session,
                                     java.lang.String verify)
        Checks all of the settings using the given setting. This triggers the LogManagerProperties to copy all of the mail settings without explictly knowing them. Once all of the properties are copied this handler can handle LogManager.reset clearing all of the properties. It is expected that this method is, at most, only called once per session.
        Parameters:
        session - the current session.
        verify - the type of verify to perform.
        Since:
        JavaMail 1.4.4
      • saveChangesNoContent

        private void saveChangesNoContent​(Message abort,
                                          java.lang.String msg)
        Handles all exceptions thrown when save changes is called on a message that doesn't have any content.
        Parameters:
        abort - the message requiring save changes.
        msg - the error description.
        Since:
        JavaMail 1.6.0
      • verifyProperties

        private static void verifyProperties​(Session session,
                                             java.lang.String protocol)
        Cache common session properties into the LogManagerProperties. This is a workaround for JDK-7092981.
        Parameters:
        session - the session.
        protocol - the mail protocol.
        Throws:
        java.lang.NullPointerException - if session is null.
        Since:
        JavaMail 1.6.0
      • verifyHost

        private static java.net.InetAddress verifyHost​(java.lang.String host)
                                                throws java.io.IOException
        Perform a lookup of the host address or FQDN.
        Parameters:
        host - the host or null.
        Returns:
        the address.
        Throws:
        java.io.IOException - if the host name is not valid.
        java.lang.SecurityException - if security manager is present and doesn't allow access to check connect permission.
        Since:
        JavaMail 1.5.0
      • verifyAddresses

        private static void verifyAddresses​(Address[] all)
                                     throws AddressException
        Calls validate for every address given. If the addresses given are null, empty or not an InternetAddress then the check is skipped.
        Parameters:
        all - any address array, null or empty.
        Throws:
        AddressException - if there is a problem.
        Since:
        JavaMail 1.4.5
      • reportUnexpectedSend

        private void reportUnexpectedSend​(MimeMessage msg,
                                          java.lang.String verify,
                                          java.lang.Exception cause)
        Reports that an empty content message was sent and should not have been.
        Parameters:
        msg - the MimeMessage.
        verify - the verify enum.
        cause - the exception that caused the problem or null.
        Since:
        JavaMail 1.4.5
      • setErrorContent

        private void setErrorContent​(MimeMessage msg,
                                     java.lang.String verify,
                                     java.lang.Throwable t)
        Creates and sets the message content from the given Throwable. When verify fails, this method fixes the 'abort' message so that any created envelope data can be used in the error manager.
        Parameters:
        msg - the message with or without content.
        verify - the verify enum.
        t - the throwable or null.
        Since:
        JavaMail 1.4.5
      • updateSession

        private Session updateSession()
        Used to update the cached session object based on changes in mail properties or authenticator.
        Returns:
        the current session or null if no verify is required.
      • initSession

        private Session initSession()
        Creates a session using a proxy properties object.
        Returns:
        the session that was created and assigned.
      • envelopeFor

        private void envelopeFor​(Message msg,
                                 boolean priority)
        Creates all of the envelope information for a message. This method is safe to call outside of a lock because the message provides the safe snapshot of the mail properties.
        Parameters:
        msg - the Message to write the envelope information.
        priority - true for high priority.
      • createBodyPart

        private MimeBodyPart createBodyPart​(int index)
                                     throws MessagingException
        Factory to create the attachment body part.
        Parameters:
        index - the attachment index.
        Returns:
        a body part with default headers set.
        Throws:
        MessagingException - if there is a problem.
        java.lang.IndexOutOfBoundsException - if the given index is not an valid attachment index.
      • descriptionFrom

        private java.lang.String descriptionFrom​(java.util.Comparator<?> c,
                                                 java.util.logging.Level l,
                                                 java.util.logging.Filter f)
        Gets the description for the MimeMessage itself. The push level and filter are included because they play a role in formatting of a message when triggered or not triggered.
        Parameters:
        c - the comparator.
        l - the pushLevel.
        f - the pushFilter
        Returns:
        the description.
        Throws:
        java.lang.NullPointerException - if level is null.
        Since:
        JavaMail 1.4.5
      • descriptionFrom

        private java.lang.String descriptionFrom​(java.util.logging.Formatter f,
                                                 java.util.logging.Filter filter,
                                                 java.util.logging.Formatter name)
        Creates a description for a body part.
        Parameters:
        f - the content formatter.
        filter - the content filter.
        name - the naming formatter.
        Returns:
        the description for the body part.
      • getClassId

        private java.lang.String getClassId​(java.util.logging.Formatter f)
        Gets a class name represents the behavior of the formatter. The class name may not be assignable to a Formatter.
        Parameters:
        f - the formatter.
        Returns:
        a class name that represents the given formatter.
        Throws:
        java.lang.NullPointerException - if the parameter is null.
        Since:
        JavaMail 1.4.5
      • toString

        private java.lang.String toString​(java.util.logging.Formatter f)
        Ensure that a formatter creates a valid string for a part name.
        Parameters:
        f - the formatter.
        Returns:
        the to string value or the class name.
      • appendFileName

        private void appendFileName​(Part part,
                                    java.lang.String chunk)
        Constructs a file name from a formatter. This method is called often but, rarely does any work.
        Parameters:
        part - to append to.
        chunk - non null string to append.
      • appendFileName0

        private void appendFileName0​(Part part,
                                     java.lang.String chunk)
        It is assumed that file names are short and that in most cases getTail will be the only method that will produce a result.
        Parameters:
        part - to append to.
        chunk - non null string to append.
      • appendSubject

        private void appendSubject​(Message msg,
                                   java.lang.String chunk)
        Constructs a subject line from a formatter.
        Parameters:
        msg - to append to.
        chunk - non null string to append.
      • appendSubject0

        private void appendSubject0​(Message msg,
                                    java.lang.String chunk)
        It is assumed that subject lines are short and that in most cases getTail will be the only method that will produce a result.
        Parameters:
        msg - to append to.
        chunk - non null string to append.
      • localeFor

        private java.util.Locale localeFor​(java.util.logging.LogRecord r)
        Gets the locale for the given log record from the resource bundle. If the resource bundle is using the root locale then the default locale is returned.
        Parameters:
        r - the log record.
        Returns:
        null if not localized otherwise, the locale of the record.
        Since:
        JavaMail 1.4.5
      • appendContentLang

        private void appendContentLang​(MimePart p,
                                       java.util.Locale l)
        Appends the content language to the given mime part. The language tag is only appended if the given language has not been specified. This method is only used when we have LogRecords that are localized with an assigned resource bundle.
        Parameters:
        p - the mime part.
        l - the locale to append.
        Throws:
        java.lang.NullPointerException - if any argument is null.
        Since:
        JavaMail 1.4.5
      • setAcceptLang

        private void setAcceptLang​(Part p)
        Sets the accept language to the default locale of the JVM. If the locale is the root locale the header is not added.
        Parameters:
        p - the part to set.
        Since:
        JavaMail 1.4.5
      • reportFilterError

        private void reportFilterError​(java.util.logging.LogRecord record)
        Used when a log record was loggable prior to being inserted into the buffer but at the time of formatting was no longer loggable. Filters were changed after publish but prior to a push or a bug in the body filter or one of the attachment filters.
        Parameters:
        record - that was not formatted.
        Since:
        JavaMail 1.4.5
      • reportNonSymmetric

        private void reportNonSymmetric​(java.lang.Object o,
                                        java.lang.Object found)
        Reports symmetric contract violations an equals implementation.
        Parameters:
        o - the test object must be non null.
        found - the possible intern, must be non null.
        Throws:
        java.lang.NullPointerException - if any argument is null.
        Since:
        JavaMail 1.5.0
      • reportNonDiscriminating

        private void reportNonDiscriminating​(java.lang.Object o,
                                             java.lang.Object found)
        Reports equals implementations that do not discriminate between objects of different types or subclass types.
        Parameters:
        o - the test object must be non null.
        found - the possible intern, must be non null.
        Throws:
        java.lang.NullPointerException - if any argument is null.
        Since:
        JavaMail 1.5.0
      • reportNullError

        private void reportNullError​(int code)
        Used to outline the bytes to report a null pointer exception. See BUD ID 6533165.
        Parameters:
        code - the ErrorManager code.
      • head

        private java.lang.String head​(java.util.logging.Formatter f)
        Creates the head or reports a formatting error.
        Parameters:
        f - the formatter.
        Returns:
        the head string or an empty string.
      • format

        private java.lang.String format​(java.util.logging.Formatter f,
                                        java.util.logging.LogRecord r)
        Creates the formatted log record or reports a formatting error.
        Parameters:
        f - the formatter.
        r - the log record.
        Returns:
        the formatted string or an empty string.
      • tail

        private java.lang.String tail​(java.util.logging.Formatter f,
                                      java.lang.String def)
        Creates the tail or reports a formatting error.
        Parameters:
        f - the formatter.
        def - the default string to use when there is an error.
        Returns:
        the tail string or the given default string.
      • setMailer

        private void setMailer​(Message msg)
        Sets the x-mailer header.
        Parameters:
        msg - the target message.
      • setPriority

        private void setPriority​(Message msg)
        Sets the priority and importance headers.
        Parameters:
        msg - the target message.
      • setIncompleteCopy

        private void setIncompleteCopy​(Message msg)
        Used to signal that body parts are missing from a message. Also used when LogRecords were passed to an attachment formatter but the formatter produced no output, which is allowed. Used during a verify because all parts are omitted, none of the content formatters are used. This is not used when a filter prevents LogRecords from being formatted. This header is defined in RFC 2156 and RFC 4021.
        Parameters:
        msg - the message.
        Since:
        JavaMail 1.4.5
      • setAutoSubmitted

        private void setAutoSubmitted​(Message msg)
        Signals that this message was generated by automatic process. This header is defined in RFC 3834 section 5.
        Parameters:
        msg - the message.
        Since:
        JavaMail 1.4.6
      • setFrom

        private void setFrom​(Message msg)
        Sets from address header.
        Parameters:
        msg - the target message.
      • setDefaultFrom

        private void setDefaultFrom​(Message msg)
        Sets the from header to the local address.
        Parameters:
        msg - the target message.
      • setDefaultRecipient

        private void setDefaultRecipient​(Message msg,
                                         Message.RecipientType type)
        Computes the default to-address if none was specified. This can fail if the local address can't be computed.
        Parameters:
        msg - the message
        type - the recipient type.
        Since:
        JavaMail 1.5.0
      • setReplyTo

        private void setReplyTo​(Message msg)
        Sets reply-to address header.
        Parameters:
        msg - the target message.
      • setSender

        private void setSender​(Message msg)
        Sets sender address header.
        Parameters:
        msg - the target message.
      • tooManyAddresses

        private AddressException tooManyAddresses​(Address[] address,
                                                  int offset)
        A common factory used to create the too many addresses exception.
        Parameters:
        address - the addresses, never null.
        offset - the starting address to display.
        Returns:
        the too many addresses exception.
      • setRecipient

        private boolean setRecipient​(Message msg,
                                     java.lang.String key,
                                     Message.RecipientType type)
        Sets the recipient for the given message.
        Parameters:
        msg - the message.
        key - the key to search in the session.
        type - the recipient type.
        Returns:
        true if the key was contained in the session.
      • toRawString

        private java.lang.String toRawString​(Message msg)
                                      throws MessagingException,
                                             java.io.IOException
        Converts an email message to a raw string. This raw string is passed to the error manager to allow custom error managers to recreate the original MimeMessage object.
        Parameters:
        msg - a Message object.
        Returns:
        the raw string or null if msg was null.
        Throws:
        MessagingException - if there was a problem with the message.
        java.io.IOException - if there was a problem.
      • toMsgString

        private java.lang.String toMsgString​(java.lang.Throwable t)
        Converts a throwable to a message string.
        Parameters:
        t - any throwable or null.
        Returns:
        the throwable with a stack trace or the literal null.
      • getAndSetContextClassLoader

        private java.lang.Object getAndSetContextClassLoader​(java.lang.Object ccl)
        Replaces the current context class loader with our class loader.
        Parameters:
        ccl - null for boot class loader, a class loader, a class used to get the class loader, or a source object to get the class loader.
        Returns:
        null for the boot class loader, a class loader, or a marker object to signal that no modification was required.
        Since:
        JavaMail 1.5.3
      • attachmentMismatch

        private static java.lang.RuntimeException attachmentMismatch​(java.lang.String msg)
        A factory used to create a common attachment mismatch type.
        Parameters:
        msg - the exception message.
        Returns:
        a RuntimeException to represent the type of error.
      • attachmentMismatch

        private static java.lang.RuntimeException attachmentMismatch​(int expected,
                                                                     int found)
        Outline the attachment mismatch message. See Bug ID 6533165.
        Parameters:
        expected - the expected array length.
        found - the array length that was given.
        Returns:
        a RuntimeException populated with a message.
      • attach

        private static MessagingException attach​(MessagingException required,
                                                 java.lang.Exception optional)
        Try to attach a suppressed exception to a MessagingException in any order that is possible.
        Parameters:
        required - the exception expected to see as a reported failure.
        optional - the suppressed exception.
        Returns:
        either the required or the optional exception.
      • getLocalHost

        private java.lang.String getLocalHost​(Service s)
        Gets the local host from the given service object.
        Parameters:
        s - the service to check.
        Returns:
        the local host or null.
        Since:
        JavaMail 1.5.3
      • getSession

        private Session getSession​(Message msg)
        Google App Engine doesn't support Message.getSession.
        Parameters:
        msg - the message.
        Returns:
        the session from the given message.
        Throws:
        java.lang.NullPointerException - if the given message is null.
        Since:
        JavaMail 1.5.3
      • allowRestrictedHeaders

        private boolean allowRestrictedHeaders()
        Determines if restricted headers are allowed in the current environment.
        Returns:
        true if restricted headers are allowed.
        Since:
        JavaMail 1.5.3
      • atIndexMsg

        private static java.lang.String atIndexMsg​(int i)
        Outline the creation of the index error message. See JDK-6533165.
        Parameters:
        i - the index.
        Returns:
        the error message.