jade.core.behaviours
Class ReceiverBehaviour

java.lang.Object
  |
  +--jade.core.behaviours.Behaviour
        |
        +--jade.core.behaviours.ReceiverBehaviour

public final class ReceiverBehaviour
extends Behaviour

Behaviour for receiving an ACL message. This class encapsulates a receive() as an atomic operation. This behaviour terminates when an ACL message is received. The method getMessage() allows to get the received message.

Version:
$Date: 2002/12/13 13:05:30 $ $Revision: 2.7 $
Author:
Giovanni Rimassa - Universita` di Parma
See Also:
SenderBehaviour, Agent.receive(), ACLMessage, Serialized Form

Inner Class Summary
static interface ReceiverBehaviour.Handle
          An interface representing ACL messages due to arrive within a time limit.
static interface ReceiverBehaviour.NotYetReady
          Exception class for timeouts.
static interface ReceiverBehaviour.TimedOut
          Exception class for timeouts.
 
Inner classes inherited from class jade.core.behaviours.Behaviour
Behaviour.RunnableChangedEvent
 
Fields inherited from class jade.core.behaviours.Behaviour
myAgent, myEvent, NOTIFY_DOWN, NOTIFY_UP, parent, STATE_BLOCKED, STATE_READY, STATE_RUNNING
 
Constructor Summary
ReceiverBehaviour(Agent a, long millis, MessageTemplate mt)
          This constructor creates a ReceiverBehaviour object that ends as soon as an ACL message matching a given MessageTemplate arrives or the passed millis timeout expires.
ReceiverBehaviour(Agent a, ReceiverBehaviour.Handle h, long millis)
          Receive any ACL message, waiting at most millis milliseconds (infinite time if millis<1).
ReceiverBehaviour(Agent a, ReceiverBehaviour.Handle h, long millis, MessageTemplate mt)
           
 
Method Summary
 void action()
          Actual behaviour implementation.
 boolean done()
          Checks whether this behaviour ended.
 ACLMessage getMessage()
          This method allows the caller to get the received message.
static ReceiverBehaviour.Handle newHandle()
          Factory method for message handles.
 void reset()
          Resets this behaviour.
 
Methods inherited from class jade.core.behaviours.Behaviour
actionWrapper, block, block, getBehaviourName, getDataStore, handle, isRunnable, onEnd, onStart, restart, root, setAgent, setBehaviourName, setDataStore
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

ReceiverBehaviour

public ReceiverBehaviour(Agent a,
                         long millis,
                         MessageTemplate mt)
This constructor creates a ReceiverBehaviour object that ends as soon as an ACL message matching a given MessageTemplate arrives or the passed millis timeout expires. The received message can then be got via the method getMessage.
Parameters:
a - The agent this behaviour belongs to, and that will receive() the message.
millis - The timeout expressed in milliseconds, an infinite timeout can be expressed by a value < 0.
mt - A Message template to match incoming messages against, null to indicate no template and receive any message that arrives.

ReceiverBehaviour

public ReceiverBehaviour(Agent a,
                         ReceiverBehaviour.Handle h,
                         long millis)
Receive any ACL message, waiting at most millis milliseconds (infinite time if millis<1). When calling this constructor, a suitable Handle must be created and passed to it. When this behaviour ends, some other behaviour will try to get the ACL message out of the handle, and an exception will be thrown in case of a time out. The following example code explains this:
// ReceiverBehaviour creation, e.g. in agent setup() method
h = ReceiverBehaviour.newHandle(); // h is an agent instance variable
addBehaviour(new ReceiverBehaviour(this, h, 10000); // Wait 10 seconds

...

// Some other behaviour, later, tries to read the ACL message
// in its action() method
try {
ACLMessage msg = h.getMessage();
// OK. Message received within timeout.
}
catch(ReceiverBehaviour.TimedOut rbte) {
// Receive timed out
}
catch(ReceiverBehaviour.NotYetReady rbnyr) {
// Message not yet ready, but timeout still active
}
Parameters:
a - The agent this behaviour belongs to.
h - An Handle representing the message to receive.
millis - The maximum amount of time to wait for the message, in milliseconds.
See Also:
ReceiverBehaviour.Handle, newHandle()

ReceiverBehaviour

public ReceiverBehaviour(Agent a,
                         ReceiverBehaviour.Handle h,
                         long millis,
                         MessageTemplate mt)
Method Detail

newHandle

public static ReceiverBehaviour.Handle newHandle()
Factory method for message handles. This method returns a new Handle object, which can be used to retrieve an ACL message out of a ReceiverBehaviour object.
Returns:
A new Handle object.
See Also:
ReceiverBehaviour.Handle

action

public void action()
Actual behaviour implementation. This method receives a suitable ACL message and copies it into the message provided by the behaviour creator. It blocks the current behaviour if no suitable message is available.
Overrides:
action in class Behaviour
Tags copied from class: Behaviour
See Also:
CompositeBehaviour

done

public boolean done()
Checks whether this behaviour ended.
Overrides:
done in class Behaviour
Returns:
true when an ACL message has been received.

reset

public void reset()
Resets this behaviour. This method allows to receive another ACLMessage with the same ReceiverBehaviour without creating a new object.
Overrides:
reset in class Behaviour

getMessage

public ACLMessage getMessage()
                      throws ReceiverBehaviour.TimedOut,
                             ReceiverBehaviour.NotYetReady
This method allows the caller to get the received message.
Returns:
the received message
Throws:
ReceiverBehaviour.TimedOut - if the timeout passed in the constructor of this class expired before any message (that eventually matched the passed message template) arrived
ReceiverBehaviour.NotYetReady - if the message is not yet arrived and the timeout is not yet expired.