Class Mail


  • public class Mail
    extends java.lang.Object
    Creates a new mail to send.

    This class is not thread safe.

    Author:
    Christopher Mindus
    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      boolean addAttachment​(java.io.File file)
      Adds a file to the contents.
      void addBCC​(java.lang.String bccs)
      Adds the BCC address(es).
      void addBCC​(InternetAddress... bccs)
      Adds the BCC address(es).
      void addCC​(java.lang.String ccs)
      Adds the CC address(es).
      void addCC​(InternetAddress... ccs)
      Adds the CC address(es).
      void addDestination​(java.lang.String dest)
      Adds the destination address(es).
      void addDestination​(InternetAddress... dests)
      Adds the destination address(es).
      protected void finalize()
      Finalize, just in case to delete attachments.
      Message getMessage()
      Gets the javax.mail.Message for advanced purposes.
      boolean queue()
      Queues the mail for sending when time comes.
      boolean queue​(boolean log)
      Queues the mail for sending when time comes.
      boolean send()
      Sends the mail directly without passing through the queue.
      boolean send​(boolean log)
      Sends the mail directly without passing through the queue.
      void setFrom​(java.lang.String from)
      Sets the From address, normally configured in the Server.
      void setFrom​(InternetAddress from)
      Sets the From address, normally configured in the Server.
      void setSubject​(java.lang.String subject)
      Sets the subject.
      void setText​(PlainKString text, IKStringInfoProvider provider)
      Sets a KString text with either HTML or plain text contents.
      void setText​(java.lang.String text)
      Sets a simple text encoded as UTF-8.
      void setText​(java.lang.String htmlPrefix, KString text, java.lang.String htmlSuffix, IKStringInfoProvider provider)
      Sets a KString text with either HTML or plain text contents.
      void setText​(java.lang.String text, java.util.Map<java.lang.String,​java.lang.String> map, boolean doLineBreaks)
      Sets the text from a HTML document with a set of parameters that will replace the contents of the HTML document text.
      • Methods inherited from class java.lang.Object

        clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
    • Method Detail

      • finalize

        protected void finalize()
                         throws java.lang.Throwable
        Finalize, just in case to delete attachments.
        Overrides:
        finalize in class java.lang.Object
        Throws:
        java.lang.Throwable
      • getMessage

        public Message getMessage()
        Gets the javax.mail.Message for advanced purposes.
        Returns:
        The message, or null if it already has been send or queued.
      • setSubject

        public void setSubject​(java.lang.String subject)
                        throws java.lang.IllegalStateException,
                               IllegalWriteException,
                               MessagingException
        Sets the subject.
        Parameters:
        subject - The subject of the mail, null for no subject (not recommended).
        Throws:
        IllegalWriteException - If the underlying implementation does not support modification of existing values.
        java.lang.IllegalStateException - If this message is obtained from a READ_ONLY folder, or if the message is already sent.
        MessagingException - For other failures.
      • addDestination

        public void addDestination​(java.lang.String dest)
                            throws java.lang.IllegalStateException,
                                   AddressException,
                                   MessagingException
        Adds the destination address(es). Adresses are separated by commas.

        The address(es) are parsed with given sequence of addresses into InternetAddress objects. The RFC822 syntax rules are enforced.

        Parameters:
        dest - The destination(s) to add.
        Throws:
        IllegalWriteException - If the underlying implementation does not support modification of existing values.
        java.lang.IllegalStateException - If this message is obtained from a READ_ONLY folder, or if the message is already sent.
        AddressException - If the address is invalid.
        MessagingException - For other failures.
      • addDestination

        public void addDestination​(InternetAddress... dests)
                            throws java.lang.IllegalStateException,
                                   MessagingException
        Adds the destination address(es).
        Parameters:
        dests - A list of destination address(es).
        Throws:
        IllegalWriteException - If the underlying implementation does not support modification of existing values.
        java.lang.IllegalStateException - If this message is obtained from a READ_ONLY folder, or if the message is already sent.
        MessagingException - For other failures.
      • addCC

        public void addCC​(java.lang.String ccs)
                   throws java.lang.IllegalStateException,
                          AddressException,
                          MessagingException
        Adds the CC address(es). Adresses are separated by commas.

        The address(es) are parsed with given sequence of addresses into InternetAddress objects. The RFC822 syntax rules are enforced.

        Parameters:
        ccs - The CC address(es) to add.
        Throws:
        IllegalWriteException - If the underlying implementation does not support modification of existing values.
        java.lang.IllegalStateException - If this message is obtained from a READ_ONLY folder, or if the message is already sent.
        AddressException - If the address is invalid.
        MessagingException - For other failures.
      • addCC

        public void addCC​(InternetAddress... ccs)
                   throws java.lang.IllegalStateException,
                          MessagingException
        Adds the CC address(es).
        Parameters:
        ccs - List of CC addresses.
        Throws:
        IllegalWriteException - If the underlying implementation does not support modification of existing values.
        java.lang.IllegalStateException - If this message is obtained from a READ_ONLY folder, or if the message is already sent.
        MessagingException - For other failures.
      • addBCC

        public void addBCC​(java.lang.String bccs)
                    throws java.lang.IllegalStateException,
                           AddressException,
                           MessagingException
        Adds the BCC address(es). Adresses are separated by commas.

        The address(es) are parsed with given sequence of addresses into InternetAddress objects. The RFC822 syntax rules are enforced.

        Parameters:
        bccs - The BCC destination address(es) to add.
        Throws:
        IllegalWriteException - If the underlying implementation does not support modification of existing values.
        java.lang.IllegalStateException - If this message is obtained from a READ_ONLY folder, or if the message is already sent.
        AddressException - If the address is invalid.
        MessagingException - For other failures.
      • addBCC

        public void addBCC​(InternetAddress... bccs)
                    throws java.lang.IllegalStateException,
                           MessagingException
        Adds the BCC address(es).
        Parameters:
        bccs - The list of BCC destination address(es) to add.
        Throws:
        IllegalWriteException - If the underlying implementation does not support modification of existing values.
        java.lang.IllegalStateException - If this message is obtained from a READ_ONLY folder, or if the message is already sent.
        MessagingException - For other failures.
      • setFrom

        public void setFrom​(java.lang.String from)
                     throws MessagingException,
                            AddressException
        Sets the From address, normally configured in the Server. This will parse the given string and create an InternetAddress. The address is parsed using "strict" parsing. No additional syntax checks that are performed here.

        This call is equivalent to InternetAddress(address, false).

        Parameters:
        from - The address in RFC822 format.
        Throws:
        IllegalWriteException - If the underlying implementation does not support modification of existing values.
        java.lang.IllegalStateException - If this message is obtained from a READ_ONLY folder, or if the message is already sent.
        AddressException - If the address is invalid.
        MessagingException - For other failures.
      • setFrom

        public void setFrom​(InternetAddress from)
                     throws MessagingException
        Sets the From address, normally configured in the Server.
        Parameters:
        from - The From address.
        Throws:
        IllegalWriteException - If the underlying implementation does not support modification of existing values.
        java.lang.IllegalStateException - If this message is obtained from a READ_ONLY folder, or if the message is already sent.
        MessagingException - For other failures.
      • setText

        public void setText​(java.lang.String text)
                     throws java.lang.IllegalStateException
        Sets a simple text encoded as UTF-8.

        This convenience method that sets the given String as this part's content with a MIME type of "text/plain".

        Any previous content is replaced.

        Parameters:
        text - The text.
        Throws:
        java.lang.IllegalStateException - If this message is obtained from a READ_ONLY folder, or if the message is already sent.
      • setText

        public void setText​(PlainKString text,
                            IKStringInfoProvider provider)
                     throws java.lang.IllegalStateException
        Sets a KString text with either HTML or plain text contents. Any references to images in the HTML KString are added into the mail as pure references, i.e. they will be loaded from the (this) sender server.

        This convenience method that sets the given String as this part's content with a MIME type of "text/plain".

        Any previous content is replaced.

        Parameters:
        text - The text in HTML or plain text.
        provider - The KString information provider.
        Throws:
        java.lang.IllegalStateException - If this message is obtained from a READ_ONLY folder, or if the message is already sent.
      • setText

        public void setText​(java.lang.String htmlPrefix,
                            KString text,
                            java.lang.String htmlSuffix,
                            IKStringInfoProvider provider)
                     throws java.lang.IllegalStateException
        Sets a KString text with either HTML or plain text contents. Any references to images in the HTML KString are added into the mail as pure references, i.e. they will be loaded from the (this) sender server.

        This convenience method that sets the given String as this part's content with a MIME type of "text/plain".

        The htmlPrefix and htmlSuffix are important to specify because they are not allowed in a KString.

        Any previous content is replaced.

        Parameters:
        htmlPrefix - The prefix string in HTML, including the starting <body> tag, null for default
                            <!DOCTYPE html>
                            <html>
                            <head>
                            <meta charset="utf-8">
                            <meta name="viewport" content="width=device-width, initial-scale=1">
                            </head>
                            <body>
                            
        text - The text in HTML or plain text.
        htmlSuffix - The suffix string in HTML, including the ending </body> tag, null for default
                            </body>
                            </html>
                            
        provider - The KString information provider.
        Throws:
        java.lang.IllegalStateException - If this message is obtained from a READ_ONLY folder, or if the message is already sent.
      • setText

        public void setText​(java.lang.String text,
                            java.util.Map<java.lang.String,​java.lang.String> map,
                            boolean doLineBreaks)
        Sets the text from a HTML document with a set of parameters that will replace the contents of the HTML document text. If a parameter is null, all HTML text within %%KEY(%% and %%)KEY%% will be removed. If the parameter is non-null, all HTML texts as %%KEY(%% and %%)KEY%% will be deleted and each occurrence of the %%KEY%% will have the Value of the Key replaced with the HTML escaped value.
        Parameters:
        text - The HTML document text.
        map - The map of keys and values, where a value can be null to remove HTML text from the document.
        doLineBreaks - Flag to replace CR/LF combinations with '<br>' when true, false not to replace and leave as is.
        Throws:
        java.lang.IllegalStateException - If this message is obtained from a READ_ONLY folder, or if the message is already sent.
        java.lang.IllegalArgumentException - If there is a mismatch in occurrences of %%KEY(%% and %%)KEY%%.
        See Also:
        HTMLUtilities.escapeString(String, boolean)
      • addAttachment

        public boolean addAttachment​(java.io.File file)
                              throws java.lang.IllegalStateException,
                                     java.io.IOException
        Adds a file to the contents. This will transform the message to a multipart message and requires a previous call to setText(String) or setText(PlainKString, IKStringInfoProvider).
        Parameters:
        file - The file attachment, do not overdo it, in general, 20 MB of attachments is accepted, but it depends on the providers.
        Returns:
        true if attachment is added, false if already attached.
        Throws:
        java.lang.IllegalStateException - If this message is obtained from a READ_ONLY folder, or if the message is already sent.
        java.io.IOException - If the attachment is not a file or can't be read.
      • send

        public boolean send()
                     throws MessagingException
        Sends the mail directly without passing through the queue. The current thread will wait until mail is sent.

        Any errors are logged, i.e. same as calling send(boolean) with true as parameter.

        Any left-overs (directories, attached file copies) are disposed of directly.

        Returns:
        true if OK, false if the mail is already sent or queued for sending.
        Throws:
        MessagingException - For mail sending errors.
      • send

        public boolean send​(boolean log)
                     throws MessagingException
        Sends the mail directly without passing through the queue. The current thread will wait until mail is sent.

        Any left-overs (directories, attached file copies) are disposed of directly.

        Parameters:
        log - Flag to log the error, if any.
        Returns:
        true if OK, false if the mail is already sent or queued for sending.
        Throws:
        MessagingException - For mail sending errors.
      • queue

        public boolean queue()
                      throws MessagingException,
                             java.io.IOException
        Queues the mail for sending when time comes. The current thread does not have to wait for the sending process.

        Any errors are logged, i.e. same as calling queue(boolean). true as parameter.

        Returns:
        true if OK, false if the mail is already sent or queued for sending. false is also returned if the mail sender is disposed of.
        Throws:
        MessagingException - For mail sending errors.
        java.io.IOException - If the mail failed to be saved.
      • queue

        public boolean queue​(boolean log)
                      throws MessagingException,
                             java.io.IOException
        Queues the mail for sending when time comes. The current thread does not have to wait for the sending process.
        Parameters:
        log - Flag to log the failure.
        Returns:
        true if OK, false if the mail is already sent or queued for sending. false is also returned if the mail sender is disposed of.
        Throws:
        MessagingException - For mail sending errors.
        java.io.IOException - If the mail failed to be saved.