Class MailSender

java.lang.Object
com.iizix.mail.MailSender

public class MailSender extends Object
The mail sender can send emails directly or queued, with a reply callback. It must be configured in either the Designer or the Server.

All mails that are queued are stored in a mail queue folder. This means that if you stop the e.g. server and restart it, no mail will be unsent: the mails left in the folder are queued again at the next start. A queued mail the mail server refuses is tried again with a bounded backoff (DEFAULT_RETRY_DELAYS) when the failure is transient; one that keeps failing, and one the relay refused for good (a 5xx reply, MailFailure: never tried again), is moved aside into the FAILED_DIRECTORY with one WARNING, never deleted; a queued mail to the placeholder address of the installation is dropped at the start (MDV-D-38), and a mail to a reserved domain is refused at its enqueue unless the relay is on this machine (refusedRecipient(Address [])). The worst that might happen is that a mail is sent twice (but this is a very thin chance to happen).

No send waits without a bound (CC-FIX-MAIL-SENDER-TIMEOUTS): the connection to the mail host, each reply of the host and each write to it have a timeout - DEFAULT_CONNECT_TIMEOUT, the configured MailProps.TIMEOUT or else DEFAULT_READ_TIMEOUT, and DEFAULT_WRITE_TIMEOUT. A send that runs into one fails with a MessagingException; for a queued mail that is a transient failure, tried again.

Author:
Christopher Mindus
  • Field Details

    • FAILED_DIRECTORY

      public static final String FAILED_DIRECTORY
      The subdirectory of a mail queue directory where a mail that kept failing is moved, with its attachments: "failed". Nothing is deleted there; a mail moved back into the queue directory is tried again at the next start.
      See Also:
    • DEFAULT_CONNECT_TIMEOUT

      public static final int DEFAULT_CONNECT_TIMEOUT
      The connect timeout of every mail sender in milliseconds, 10000: how long the connection to the mail host may take (CC-FIX-MAIL-SENDER-TIMEOUTS). JavaMail's own default is no timeout: a host that does not answer - a port a firewall drops - then holds the sending thread for as long as the operating system's own connect takes (measured on Windows 11: 21 seconds).
      See Also:
    • DEFAULT_READ_TIMEOUT

      public static final int DEFAULT_READ_TIMEOUT
      The read timeout of a mail sender whose properties name none (MailProps.TIMEOUT) in milliseconds, 15000: how long ONE reply of the mail host is waited for - its greeting, its reply to a command, its reply to the mail's data, and under TLS its part of the handshake (CC-FIX-MAIL-SENDER-TIMEOUTS). JavaMail's own default is no timeout: a host that accepts the connection and then says nothing holds the sending thread for ever.
      See Also:
    • DEFAULT_WRITE_TIMEOUT

      public static final int DEFAULT_WRITE_TIMEOUT
      The write timeout of every mail sender in milliseconds, 15000: how long ONE write to the mail host may block, as it does when the host stops reading while the mail's data is sent (CC-FIX-MAIL-SENDER-TIMEOUTS). JavaMail's own default is no timeout. JavaMail times the writes of a connection with one thread of its own, not a daemon thread: it lives while the sender keeps its connection and ends when the connection is closed (dispose()).
      See Also:
  • Constructor Details

    • MailSender

      public MailSender(MailProps pc, ExecutorService executorService, File mailQueueDirectory) throws IOException, NoSuchProviderException, AddressException
      Creates a new instance of the mail sender with the specified settings. Any previous mail sender with remaining messages to send will still do its work.
      Parameters:
      pc - The mail property container.
      executorService - Executor service for mail sending, null when not queueing mails, just for test sending.
      mailQueueDirectory - Mail queue directory. If it doesn't exist, it is created.
      Throws:
      IOException - If the mail queue directory does not exist.
      NoSuchProviderException - If the "smtp" or "smtps" providers do not exist!
      AddressException - If the default sender failed to parse.
  • Method Details

    • getInstance

      public static MailSender getInstance()
      Gets the default instance of the mail sender.
      Returns:
      The default instance, null if none is configured.
    • getInstance

      public static MailSender getInstance(String name)
      Gets the default instance of the mail sender.
      Parameters:
      name - The name of the mail sender, null for default.
      Returns:
      The default instance, null if none is configured.
    • getInstances

      public static MailSender[] getInstances()
      Returns all configured mail senders.
      Returns:
      The array may be empty if no mail senders are configured.
    • stopAll

      public static int stopAll(long timeout) throws InterruptedException
      Requests to stop all mail senders.
      Parameters:
      timeout - Timeout in milliseconds to wait.
      Returns:
      Number of mails left to send (in all mail queues), zero means none.
      Throws:
      InterruptedException - If the wait is interrupted.
    • getDescription

      public String getDescription()
      Gets the description of this mail sender.
      Returns:
      A description string, or null if none is defined.
    • getDefaultSender

      public InternetAddress getDefaultSender()
      The default 'Sender' for mails.
      Returns:
      The default 'Sender' for mails, null for none.
    • getDefaultReplyTo

      public InternetAddress getDefaultReplyTo()
      The default 'Reply To' for mails.
      Returns:
      The default 'Reply To' for mails, null for none.
    • getDefaultCCs

      public InternetAddress[] getDefaultCCs()
      The default CC's for mails.
      Returns:
      The default CC's for mails, null for none.
    • getDefaultBCCs

      public InternetAddress[] getDefaultBCCs()
      The default BCC's for mails.
      Returns:
      The default BCC's for mails, null for none.
    • isDisposed

      public boolean isDisposed()
      Checks if the mail sender is disposed of.
      Returns:
      true if disposed of, false otherwise.
    • isDefaultSender

      public boolean isDefaultSender()
      Checks if this is the default mail sender, as its container was marked when the sender was built (MailProps.isDefaultSender(): the one rule of the default sender, CC-SERVERADMIN-MAIL-SENDERS).
      Returns:
      true for the default sender, false otherwise.
    • createMail

      public Mail createMail()
      Creates a new mail to send.
      Returns:
      An uninitialized mail with a MimeMessage as the mail's message. It can be retrieved using Mail.getMessage() and then cast to MimeMessage.
    • createMailWithDefaults

      public Mail createMailWithDefaults() throws MessagingException
      Creates a new mail to send with all defaults that are defined set:
      Returns:
      An new mail initialized only with default Sender, Reply To, CC's and BCC's where defined, with a MimeMessage as the mail's message. It can be retrieved using Mail.getMessage() and then cast to MimeMessage.
      Throws:
      MessagingException - For messaging failures.
    • getQueuedMailCount

      public int getQueuedMailCount()
      Returns how mail mails are currently queued for sending.
      Returns:
      The number of queued mails.
    • dispose

      public void dispose()
      Disposes of the current mail sender and leaves unsent mail queued.
    • deleteMailDirectory

      public void deleteMailDirectory() throws IOException
      Deletes all unsent mails and the mail folder. This call should be made in preference once the mail sender has been disposed of.
      Throws:
      IOException - If the mail folder failed to be deleted.