Package rs.mail.queue

Class MailQueue<T>

java.lang.Object
rs.mail.queue.MailQueue<T>
Type Parameters:
T - the email message object
public class MailQueue<T> extends Object
Abstract implementation of the queue that leaves the underlying mailing implemebtation open.
Author:
ralph

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    protected static class 
    MailQueue.MessageEntry<X>
    Helper class to store messages in the queue.

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final int
    DEFAULT_MAX_PRIORITY_SIZE
    Default size of the mail queue for priority emails
    static final int
    DEFAULT_MAX_RETRIES
    Default number of retries before giving up when sending fails
    static final int
    DEFAULT_MAX_SIZE
    Default size of the mail queue for non-priority emails
    static final long
    DEFAULT_QUEUING_TIMEOUT_SECONDS
    The default period of time a queuing operation shall wait before giving up.
    static final long
    DEFAULT_RETRY_PERIOD
    Default period of time after a failed message will be tried again

  • Constructor Summary

    Constructors
    Constructor
    Description
    MailQueue(MailSender<T> mailSender)
    Constructor.
    MailQueue(MailSender<T> mailSender, int maxSize)
    Constructor.
    MailQueue(MailSender<T> mailSender, int maxSize, int maxPrioritySize)
    Constructor.

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    addListener(MailQueueListener listener)
    Adds a listener to this queue.
    int
    capacity(boolean isPriority)
    Returns the total capacity of the normal or prioritized queue.
    protected boolean
    getBucketToken()
    Tries to consume a token from a bucket.
    int
    getMaxRetries()
    Returns the number of retries before giving up when sending fails.
    protected MailQueue.MessageEntry<T>
    getNext()
    Picks the next message for sending if available.
    protected MailQueue.MessageEntry<T>
    getNext(boolean isPriority)
    Picks the next message from the given queue.
    long
    getRetryPeriod()
    Returns the period in milliseconds that has to pass before a failed message will be tried again.
    com.github.cowwoc.tokenbucket.Bucket
    getTokenBucket()
    Returns the token bucket.
    protected void
    mailFailed(MailQueue.MessageEntry<T> entry, String reason)
    Informs listeners that a message failed.
    protected void
    mailQueued(MailQueue.MessageEntry<T> entry)
    Informs listeners that a message was queued.
    protected void
    mailSending(MailQueue.MessageEntry<T> entry)
    Informs listeners that a message is being sent.
    protected void
    mailSent(MailQueue.MessageEntry<T> entry)
    Informs listeners that a message was sent successfully.
    protected boolean
    queue(MailQueue.MessageEntry<T> message, LinkedBlockingDeque<MailQueue.MessageEntry<T>> queue, long timeoutInSeconds)
    Internal queuing implementation - queues the entry in th egiven queue using the given maximum waiting time.
    boolean
    queue(T message, String referenceId)
    Add the message to the queue for sending with normal priority.
    boolean
    queue(T message, String referenceId, boolean isPriority)
    Add the message to the queue for sending.
    boolean
    queue(T message, String referenceId, boolean isPriority, int previousErrorCount)
    Add the message to the queue for sending.
    boolean
    queue(T message, String referenceId, boolean isPriority, int previousErrorCount, long timeoutInSeconds)
    Add the message to the queue for sending.
    boolean
    queue(T message, String referenceId, boolean isPriority, long timeoutInSeconds)
    Add the message to the queue for sending.
    boolean
    queue(T message, String referenceId, long timeoutInSeconds)
    Add the message to the queue for sending with normal priority.
    int
    remainingCapacity(boolean isPriority)
    Returns the remaining capacity of the normal or prioritized queue.
    protected void
    remove(MailQueue.MessageEntry<T> entry)
    Removes the message from the queue
    void
    removeListener(MailQueueListener listener)
    Removes a listener from this queue.
    void
    run()
    Process the queue once.
    void
    setMaxRetries(int maxRetries)
    Sets the number of retries before giving up when sending fails.
    void
    setRetryPeriod(long retryPeriod)
    Sets the period in milliseconds that has to pass before a failed message will be tried again.
    void
    setTokenBucket(com.github.cowwoc.tokenbucket.Bucket tokenBucket)
    Sets the token bucket.
    int
    size()
    Returns the current size of the queue.
    int
    size(boolean isPriority)
    Returns the current size of the queue for normal or prioritized messages only.

    Methods inherited from class java.lang.Object

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

  • Field Details

    • DEFAULT_MAX_SIZE

      public static final int DEFAULT_MAX_SIZE
      Default size of the mail queue for non-priority emails
      See Also:

    • DEFAULT_MAX_PRIORITY_SIZE

      public static final int DEFAULT_MAX_PRIORITY_SIZE
      Default size of the mail queue for priority emails
      See Also:

    • DEFAULT_MAX_RETRIES

      public static final int DEFAULT_MAX_RETRIES
      Default number of retries before giving up when sending fails
      See Also:

    • DEFAULT_RETRY_PERIOD

      public static final long DEFAULT_RETRY_PERIOD
      Default period of time after a failed message will be tried again
      See Also:

    • DEFAULT_QUEUING_TIMEOUT_SECONDS

      public static final long DEFAULT_QUEUING_TIMEOUT_SECONDS
      The default period of time a queuing operation shall wait before giving up.
      See Also:

  • Constructor Details

    • MailQueue

      public MailQueue(MailSender<T> mailSender)
      Constructor.

      The queue will use the standard max capacity./p>

      Parameters:
      mailSender - the handler that actually sends the mail
      See Also:

    • MailQueue

      public MailQueue(MailSender<T> mailSender, int maxSize)
      Constructor.

      The queue will use the standard max capacity for priority messages./p>

      Parameters:
      mailSender - the handler that actually sends the mail
      maxSize - - the maximum size of the queue for non-priority messages
      See Also:

    • MailQueue

      public MailQueue(MailSender<T> mailSender, int maxSize, int maxPrioritySize)
      Constructor.
      Parameters:
      mailSender - the handler that actually sends the mail
      maxSize - - the maximum size of the queue for non-priority messages
      maxPrioritySize - - the maximum size of the queue for priority messages

  • Method Details

    • getTokenBucket

      public com.github.cowwoc.tokenbucket.Bucket getTokenBucket()
      Returns the token bucket.

      A token bucket control how many emails may be sent in a certain time window. There will be no restrictions when the bucket is not set.

      Returns:
      the token bucket

    • setTokenBucket

      public void setTokenBucket(com.github.cowwoc.tokenbucket.Bucket tokenBucket)
      Sets the token bucket.

      A token bucket control how many emails may be sent in a certain time window. There will be no restrictions when the bucket is not set.

      Parameters:
      tokenBucket - the token bucket to set

    • getMaxRetries

      public int getMaxRetries()
      Returns the number of retries before giving up when sending fails.
      Returns:
      the number of retries before giving up when sending fails

    • setMaxRetries

      public void setMaxRetries(int maxRetries)
      Sets the number of retries before giving up when sending fails.
      Parameters:
      maxRetries - the number of retries before giving up when sending fails

    • getRetryPeriod

      public long getRetryPeriod()
      Returns the period in milliseconds that has to pass before a failed message will be tried again.
      Returns:
      the retry period in millisecond (Default: 60000)

    • setRetryPeriod

      public void setRetryPeriod(long retryPeriod)
      Sets the period in milliseconds that has to pass before a failed message will be tried again.
      Parameters:
      retryPeriod - the retry period in milliseconds (Default: 60000)

    • queue

      public boolean queue(T message, String referenceId)
      Add the message to the queue for sending with normal priority.

      The message will be tried to be queued immediately without any blocking.

      Parameters:
      message - - message to be sent
      referenceId - - reference id for the client
      Returns:
      true when the message was queued, false when it cannot be queued at this time

    • queue

      public boolean queue(T message, String referenceId, long timeoutInSeconds)
      Add the message to the queue for sending with normal priority.
      Parameters:
      message - - message to be sent
      referenceId - - reference id for the client
      timeoutInSeconds - the maximum waiting time to queue before giving up
      Returns:
      true when the message was queued, false when it cannot be queued at this time

    • queue

      public boolean queue(T message, String referenceId, boolean isPriority)
      Add the message to the queue for sending.

      The message will be tried to be queued immediately without any blocking.

      Parameters:
      message - - message to be sent
      referenceId - - reference id for the client
      isPriority - - when the mail shall be sent with priority
      Returns:
      true when the message was queued, false when it cannot be queued at this time

    • queue

      public boolean queue(T message, String referenceId, boolean isPriority, long timeoutInSeconds)
      Add the message to the queue for sending.
      Parameters:
      message - - message to be sent
      referenceId - - reference id for the client
      isPriority - - when the mail shall be sent with priority
      timeoutInSeconds - the maximum waiting time to queue before giving up
      Returns:
      true when the message was queued, false when it cannot be queued at this time

    • queue

      public boolean queue(T message, String referenceId, boolean isPriority, int previousErrorCount)
      Add the message to the queue for sending.

      This method is intended to be used when you need you re-populate the queue after a system restart. You can pass the additional errorCount parameter to re-establish the previous queue status.

      The message will be tried to be queued immediately without any blocking.

      Parameters:
      message - - message to be sent
      referenceId - - reference id for the client
      isPriority - - when the mail shall be sent with priority
      previousErrorCount - - error count from previous attempts
      Returns:
      true when the message was queued, false when it cannot be queued at this time

    • queue

      public boolean queue(T message, String referenceId, boolean isPriority, int previousErrorCount, long timeoutInSeconds)
      Add the message to the queue for sending.

      This method is intended to be used when you need you re-populate the queue after a system restart. You can pass the additional errorCount parameter to re-establish the previous queue status.

      Parameters:
      message - - message to be sent
      referenceId - - reference id for the client
      isPriority - - when the mail shall be sent with priority
      previousErrorCount - - error count from previous attempts
      timeoutInSeconds - the maximum waiting time to queue before giving up
      Returns:
      true when the message was queued, false when it cannot be queued at this time

    • queue

      protected boolean queue(MailQueue.MessageEntry<T> message, LinkedBlockingDeque<MailQueue.MessageEntry<T>> queue, long timeoutInSeconds)
      Internal queuing implementation - queues the entry in th egiven queue using the given maximum waiting time.
      Parameters:
      message - the message to be queued
      queue - the queue to be used
      timeoutInSeconds - the maximum waiting time to queue before giving up
      Returns:
      true when the message was queued, false when it cannot be queued at this time

    • size

      public int size()
      Returns the current size of the queue.
      Returns:
      the size of the queue

    • size

      public int size(boolean isPriority)
      Returns the current size of the queue for normal or prioritized messages only.
      Parameters:
      isPriority - whether the priority or normal number of messages shall be returned
      Returns:
      the size of the queue

    • capacity

      public int capacity(boolean isPriority)
      Returns the total capacity of the normal or prioritized queue.
      Parameters:
      isPriority - whether the capacity for priority or normal messages shall be returned
      Returns:
      the total capacity

    • remainingCapacity

      public int remainingCapacity(boolean isPriority)
      Returns the remaining capacity of the normal or prioritized queue.
      Parameters:
      isPriority - whether the capacity for priority or normal messages shall be returned
      Returns:
      the remaining capacity

    • addListener

      public void addListener(MailQueueListener listener)
      Adds a listener to this queue.
      Parameters:
      listener - the listener to add

    • removeListener

      public void removeListener(MailQueueListener listener)
      Removes a listener from this queue.
      Parameters:
      listener - the listener to remove

    • mailQueued

      protected void mailQueued(MailQueue.MessageEntry<T> entry)
      Informs listeners that a message was queued.
      Parameters:
      entry - the message entry

    • mailSending

      protected void mailSending(MailQueue.MessageEntry<T> entry)
      Informs listeners that a message is being sent.
      Parameters:
      entry - the message entry

    • mailSent

      protected void mailSent(MailQueue.MessageEntry<T> entry)
      Informs listeners that a message was sent successfully.
      Parameters:
      entry - the message entry

    • mailFailed

      protected void mailFailed(MailQueue.MessageEntry<T> entry, String reason)
      Informs listeners that a message failed.
      Parameters:
      entry - the message entry
      reason - the reson why sending failed

    • run

      public void run() throws Exception
      Process the queue once.

      The method must be called periodically. The method stops when

      • The queue is empty and no more messages to be sent, or
      • The rate limit has been reached and we need to wait before sending
      Throws:
      Exception - when the processing caused a severe faiulure

    • getNext

      protected MailQueue.MessageEntry<T> getNext()
      Picks the next message for sending if available.

      The method does not yet remove the message from the queue.

      Returns:
      a message cleared to be sent

    • getNext

      protected MailQueue.MessageEntry<T> getNext(boolean isPriority)
      Picks the next message from the given queue.

      The method does not yet remove the message from the queue.

      Parameters:
      isPriority - the queue to check (priority or normal)
      Returns:
      a message cleared to be sent

    • remove

      protected void remove(MailQueue.MessageEntry<T> entry)
      Removes the message from the queue
      Parameters:
      entry - the message to be removed

    • getBucketToken

      protected boolean getBucketToken()
      Tries to consume a token from a bucket.

      The method will ask the token bucket if available and consume one token if possible. If no token is available, the method will not block and return false.

      Always returns true when no token bucket was set.

      Returns:
      true when a token was consumed, false otherwise.