jade.core.behaviours
Class ReceiverBehaviour

java.lang.Object
  jade.core.behaviours.Behaviour
      jade.core.behaviours.ReceiverBehaviour

All Implemented Interfaces:

java.io.Serializable

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: 2003-11-25 09:24:45 +0100 (mar, 25 nov 2003) $ $Revision: 4601 $

Author:

Giovanni Rimassa - Universita' di Parma

See Also:

SenderBehaviour, Agent.receive(), ACLMessage, Serialized Form

Nested Class Summary

static interface	ReceiverBehaviour.Handle An interface representing ACL messages due to arrive within a time limit.
static class	ReceiverBehaviour.NotYetReady Exception class for timeouts.
static class	ReceiverBehaviour.TimedOut Exception class for timeouts.

Nested classes/interfaces inherited from class jade.core.behaviours.Behaviour

Behaviour.RunnableChangedEvent

Field Summary

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)
Receive any ACL message matching the given template, witing at most millis milliseconds (infinite time if millis < 1.

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, getExecutionState, getParent, getRestartCounter, handle, handleBlockEvent, handleRestartEvent, isRunnable, onEnd, onStart, restart, root, setAgent, setBehaviourName, setDataStore, setExecutionState

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)

Receive any ACL message matching the given template, witing at most millis milliseconds (infinite time if millis < 1. When calling this constructor, a suitable Handle must be created and passed to it.

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.

mt - A Message template to match incoming messages against, null to indicate no template and receive any message that arrives.

See Also:

ReceiverBehaviour(Agent a, Handle h, long millis)

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.

Specified by:

action in class Behaviour

See Also:

CompositeBehaviour

done

public boolean done()

Checks whether this behaviour ended.

Specified by:

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.