Class Mailbox

java.lang.Object
madkit.kernel.Mailbox
public final class Mailbox extends Object
This class represents the mailbox of an Agent
Since:
MaDKit 6.0

  • Method Summary

    Modifier and Type
    Method
    Description
    <M extends Message>
    List<M>
    getAll(Predicate<M> filter)
    Retrieves and removes all the messages from the message box.
    <T extends Message>
    T
    getNewest()
    Gets the last received message.
    <M extends Message>
    M
    getNewest(Predicate<M> filter)
    Gets the last received message according to a filter.
    <M extends Message>
    M
    getReply(Message originalMessage)
    /** Gets the next message which is a reply to the originalMessage.
    boolean
    isEmpty()
    Tells if there is a message in the mailbox
    <M extends Message>
    M
    next()
    Retrieves and removes the oldest received message contained in the mailbox.
    <M extends Message>
    M
    next(Predicate<M> filter)
    Retrieves and removes the first oldest message of the mailbox that matches the filter.
    <M extends Message>
    List<M>
    nextMatches(Predicate<M> filter)
    Retrieves all the messages of the mailbox, without taking those that match the filter, Messages are listed in the order they were received.
    <M extends Message>
    M
    purge()
    Purges the mailbox and returns the most recent received message at that time.
    <M extends Message>
    M
    purge(Predicate<M> filter)
    Purges the mailbox and returns the most recent received message at that time that matches the filter.
    List<Message>
    removeAll()
    Retrieves and removes all the messages from the mailbox.
    int
    size()
    Returns the number of messages in the mailbox.
    String
    toString()
     
    <M extends Message>
    List<M>
    waitAnswers(Message origin, int howMany, Integer timeOutMilliSeconds)
    Returns the next howMany messages that are replies to the origin message, waiting for ever if necessary until howMany replies become available.
    <M extends Message>
    List<M>
    waitMessages(Integer timeOutMilliseconds, int howMany, Predicate<M> filter)
    Returns the next howMany messages that match the filter, waiting for ever if necessary until howMany matching messages become available.
    <M extends Message>
    M
    waitNext()
    This method is the blocking version of nextMessage().
    <T extends Message>
    T
    waitNext(long timeoutMilliSeconds)
    Wait next message.
    <M extends Message>
    M
    waitNext(Integer timeOutMilliseconds, Predicate<M> filter)
    This method gets the next message of the mailbox or waits for a new incoming acceptable message up to a certain delay.
    <M extends Message>
    M
    waitNext(Predicate<M> filter)
    Retrieves and removes the next message that complies with the filter, waiting for ever if necessary until a matching message becomes available.

    Methods inherited from class java.lang.Object

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

  • Method Details

    • toString

      public String toString()
      Overrides:
      toString in class Object

    • next

      public <M extends Message> M next()
      Retrieves and removes the oldest received message contained in the mailbox. Beware that if T is not the type of the next message, a ClassCastException will be thrown. For instance, if the next message is a StringMessage and you call this method with T being StringMessage, it will work. But if you call it with T being Message, a ClassCastException will be thrown.

      However, if you are seeking for a message of type T in the mailbox, you can use next(Predicate) with a specific Predicate such as in

      StringMessage sm = next(StringMessage.class::isInstance)

      Type Parameters:
      M - the expected type of the message to get
      Returns:
      The next message or null if the message box is empty.

    • next

      public <M extends Message> M next(Predicate<M> filter)
      Retrieves and removes the first oldest message of the mailbox that matches the filter.
      Type Parameters:
      M - the expected type of the message to get
      Parameters:
      filter - the filter to use
      Returns:
      The next acceptable message or null if such message has not been found.

    • nextMatches

      public <M extends Message> List<M> nextMatches(Predicate<M> filter)
      Retrieves all the messages of the mailbox, without taking those that match the filter, Messages are listed in the order they were received.
      Parameters:
      filter - if null all the messages are returned and removed from the mailbox.
      Returns:
      the ordered list of matching messages, or an empty list if none has been found.

    • removeAll

      public List<Message> removeAll()
      Retrieves and removes all the messages from the mailbox.
      Returns:
      the list of messages in the order they were received

    • getAll

      public <M extends Message> List<M> getAll(Predicate<M> filter)
      Retrieves and removes all the messages from the message box.
      Type Parameters:
      M - the type of the message to get
      Parameters:
      filter - the filter to use to select the messages to remove
      Returns:
      the list of messages in the order they were received

    • getNewest

      public <T extends Message> T getNewest()
      Gets the last received message. Beware that if T is not the type of the next message, a ClassCastException will be thrown. For instance, if the newest message is a StringMessage and you call this method with T being StringMessage, it will work. But if you call it with T being Message, a ClassCastException will be thrown.

      However, if you are seeking for a message of type T, you can use getNewest(Predicate) with a specific Predicate such as in

      StringMessage sm = getNewest(StringMessage.class::isInstance)

      Type Parameters:
      T - the expected type of the message
      Returns:
      the last received message or null if the mailbox is empty.

    • getNewest

      public <M extends Message> M getNewest(Predicate<M> filter)
      Gets the last received message according to a filter.
      Parameters:
      filter - the message filter to use
      Returns:
      the last received message that matches the filter or null if such message has not been found.

    • purge

      public <M extends Message> M purge()
      Purges the mailbox and returns the most recent received message at that time. Beware that if T is not the type of the next message, a ClassCastException will be thrown. However, if you are seeking for a message of type T, you can use purge(Predicate) with a specific Predicate such as in

      StringMessage sm = purge(StringMessage.class::isInstance)

      Type Parameters:
      M - the expected type of the message
      Returns:
      the most recent received message or null if the mailbox is already empty.

    • purge

      public <M extends Message> M purge(Predicate<M> filter)
      Purges the mailbox and returns the most recent received message at that time that matches the filter.
      Type Parameters:
      M - the expected type of the message
      Parameters:
      filter - the filter to use
      Returns:
      the m most recent received message that matches the filter or null if no such message has been found.

    • getReply

      public <M extends Message> M getReply(Message originalMessage)
      /** Gets the next message which is a reply to the originalMessage.
      Parameters:
      originalMessage - the message to which a reply is searched.
      Returns:
      a reply to the originalMessage or null if no reply to this message has been received.

    • isEmpty

      public boolean isEmpty()
      Tells if there is a message in the mailbox
      Returns:
      true if there is no message in the mailbox.

    • waitNext

      public <M extends Message> M waitNext()
      This method is the blocking version of nextMessage(). If there is no message in the mailbox, it suspends the agent life until a message is received.

      Beware that if T is not the type of the received message, a ClassCastException will be thrown. For instance, if the next message is a StringMessage and you call this method with T being StringMessage, it will work. But if you call it with T being Message, a ClassCastException will be thrown.

      Type Parameters:
      M - the expected type of the message
      Returns:
      the first received message
      See Also:

    • waitNext

      public <T extends Message> T waitNext(long timeoutMilliSeconds)
      Wait next message. This is equivalent to calling waitNext(timeoutMilliSeconds, TimeUnit.MILLISECONDS)
      Type Parameters:
      T - the expected type
      Parameters:
      timeoutMilliSeconds - the timeout in milliseconds
      Returns:
      the t

    • waitNext

      public <M extends Message> M waitNext(Predicate<M> filter)
      Retrieves and removes the next message that complies with the filter, waiting for ever if necessary until a matching message becomes available.
      Type Parameters:
      M - the expected type of the message
      Parameters:
      filter - the filter to use
      Returns:
      the first received message that matches the filter

    • waitNext

      public <M extends Message> M waitNext(Integer timeOutMilliseconds, Predicate<M> filter)
      This method gets the next message of the mailbox or waits for a new incoming acceptable message up to a certain delay.
      Type Parameters:
      M - the expected type of the message
      Parameters:
      timeOutMilliseconds - the maximum time to wait, in milliseconds.
      filter - the filter to use
      Returns:
      a message that matches or null otherwise.

    • waitMessages

      public <M extends Message> List<M> waitMessages(Integer timeOutMilliseconds, int howMany, Predicate<M> filter)
      Returns the next howMany messages that match the filter, waiting for ever if necessary until howMany matching messages become available.
      Type Parameters:
      M - the expected type of the message
      Parameters:
      timeOutMilliseconds - the maximum time to wait, in milliseconds.
      howMany - the number of messages to wait for
      filter - the filter to use
      Returns:
      the list of messages that match the filter

    • waitAnswers

      public <M extends Message> List<M> waitAnswers(Message origin, int howMany, Integer timeOutMilliSeconds)
      Returns the next howMany messages that are replies to the origin message, waiting for ever if necessary until howMany replies become available. Beware that if T is not the type of the answers, a ClassCastException will be thrown.
      Type Parameters:
      M - the expected type of the message
      Parameters:
      origin - the message to which the replies are searched.
      howMany - the number of replies to wait for
      timeOutMilliSeconds - the maximum time to wait, in milliseconds.
      Returns:
      the list of replies to the origin message

    • size

      public int size()
      Returns the number of messages in the mailbox.
      Returns:
      the number of messages in the mailbox.