jade.proto
Class FipaContractNetInitiatorBehaviour

java.lang.Object
  |
  +--jade.core.behaviours.Behaviour
        |
        +--jade.core.behaviours.SimpleBehaviour
              |
              +--jade.proto.FipaContractNetInitiatorBehaviour

public abstract class FipaContractNetInitiatorBehaviour
extends SimpleBehaviour

Behaviour class for fipa-contract-net Initiator role. This abstract behaviour implements the fipa-contract-net interaction protocol from the point of view of the agent initiating the protocol, that is the agent that sends the cfp message (Call for Proposal) to a set of agents. In order to use correctly this behaviour, the programmer should do the following:

This behaviour can be hot reset, i.e. it is sensitive to the call of the reset method and it is able to react in every state of the protocol.

For this reason, this class can also be used to implement the FIPA-ITERATED-CONTRACT-NET PROTOCOL. In such a case, the following should be done:

Author:
Fabio Bellifemine - CSELT
See Also:
FipaContractNetResponderBehaviour, Serialized Form

Inner classes inherited from class jade.core.behaviours.Behaviour
Behaviour.RunnableChangedEvent
 
Field Summary
protected  ACLMessage cfpMsg
          This is the cfpMsg sent in the first state of the protocol
protected  boolean finished
          This boolean should be set to true in order to finish abnormally the protocol.
 
Fields inherited from class jade.core.behaviours.Behaviour
myAgent, myEvent, NOTIFY_DOWN, NOTIFY_UP, parent
 
Constructor Summary
FipaContractNetInitiatorBehaviour(Agent a, ACLMessage msg)
          constructor of the behaviour.
FipaContractNetInitiatorBehaviour(Agent a, ACLMessage msg, java.util.List responders)
          constructor of the behaviour.
 
Method Summary
 void action()
          Action method of the behaviour.
 java.lang.String createCfpContent(java.lang.String cfpContent, AID receiver)
          Some content languages require that the name of the actor be included within the proposed action itself.
 boolean done()
          This method is called by the JADE scheduler of agent behaviours and it should usually be ignored by application code.
abstract  java.util.Vector handleFinalMessages(java.util.Vector messages)
          After having sent the messages returned by handleProposeMessages(), the protocol waits for the expiration of the maximum timeout specified in those messages (reply-by parameter), or until all the answers are received.
abstract  void handleOtherMessages(ACLMessage msg)
          This method must be implemented by all subclasses.
abstract  java.util.Vector handleProposeMessages(java.util.Vector proposals)
          This method is called after all the propose messages have been collected or after the timeout has expired.
 void reset()
          This method resets this behaviour object so that it restarts from the initial state of the protocol.
 void reset(ACLMessage msg, java.util.List responders)
           
 
Methods inherited from class jade.core.behaviours.Behaviour
block, block, handle, isRunnable, restart, root
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

cfpMsg

protected ACLMessage cfpMsg
This is the cfpMsg sent in the first state of the protocol

finished

protected boolean finished
This boolean should be set to true in order to finish abnormally the protocol.
Constructor Detail

FipaContractNetInitiatorBehaviour

public FipaContractNetInitiatorBehaviour(Agent a,
                                         ACLMessage msg,
                                         java.util.List responders)
constructor of the behaviour.
Parameters:
a - is the current agent. The protected variable Agent myAgent contains then the pointer to the agent class. A common usage of this variable is to cast it to the actual type of Agent class and use the methods of the extended class. For instance appointments = (AppointmentAgent)myAgent.getAppointments()
msg - is the Call for Proposal message to be sent. If not set already in the parameter, the protocol is set to the value FIPA-Contract-Net
responders - is the group of agents to which the cfp must be sent sintactically it is a List of AID

FipaContractNetInitiatorBehaviour

public FipaContractNetInitiatorBehaviour(Agent a,
                                         ACLMessage msg)
constructor of the behaviour. In this case the group of responder agents is extracted directly by the receiver field of the ACLMessage that has been passed as parameter.
See Also:
FipaContractNetInitiatorBehaviour(Agent a, ACLMessage msg, List responders)
Method Detail

action

public final void action()
Action method of the behaviour. This method cannot be overriden by subclasses because it implements the actual FipaContractNet protocol
Overrides:
action in class Behaviour

done

public boolean done()
This method is called by the JADE scheduler of agent behaviours and it should usually be ignored by application code. It returns true when the behaviour has terminated and should be removed from the queue of active behaviours.
Overrides:
done in class Behaviour

handleOtherMessages

public abstract void handleOtherMessages(ACLMessage msg)
This method must be implemented by all subclasses. After the agent has sent the cfp message, this method is called everytime a new message arrives that is different from a propose message. The method should react to this message in an application-dependent way.

The class variable myAgent can be used to send messages or, after casting, to execute other application-dependent methods that belongs to the Agent object.

Parameters:
msg - is the ACLMessage just arrived

handleProposeMessages

public abstract java.util.Vector handleProposeMessages(java.util.Vector proposals)
This method is called after all the propose messages have been collected or after the timeout has expired. By default an infinite timeout is used. That default is overriden by the reply-by parameter of the cfp message, if set.
Parameters:
proposals - is the Vector that contains the received propose ACL messages.
Returns:
a Vector of ACLMessages to be sent in the next phase of the protocol. Usually, these messages should be of type accept-proposal or reject-proposal. If null is returned instead, then the protocol is prematurely terminated.

REMEMBER to set the value of :in-reply-to parameter in all the returned messages of this vector. This implementation of the protocol is not able to set that value on your behalf because it implements a one-to-many protocol and, unfortunately, each of the many might use a different value of :in-reply-to.

NOTICE that all the returned messages are sent even if the reset method is called. That allows the implementation of the FIPA-Iterated-Contract-Net protocol. See at the top for some usefull instructions.


handleFinalMessages

public abstract java.util.Vector handleFinalMessages(java.util.Vector messages)
After having sent the messages returned by handleProposeMessages(), the protocol waits for the expiration of the maximum timeout specified in those messages (reply-by parameter), or until all the answers are received. If no reply-by parameter was set, an infinite timeout is used, instead. After this timeout, this method is called to react to all the received messages. At the next state of the protocol, all the returned messages are sent and then the protocol terminates.
Parameters:
messages - is the Vector of ACL messages received so far
Returns:
a Vector of ACL messages to be sent in the next state of the protocol. return null to terminate the protocol REMEMBER to set the value of :in-reply-to parameter in all the returned messages of this vector. This implementation of the protocol is not able to set that value on your behalf because it implements a one-to-many protocol and, unfortunately, each of the many might use a different value of :in-reply-to.

createCfpContent

public java.lang.String createCfpContent(java.lang.String cfpContent,
                                         AID receiver)
Some content languages require that the name of the actor be included within the proposed action itself. For instance, in order to request to N sellers (s1,s2, ..., sN) the cost of a car, the cfp message should have this content (by using SL0 content language): You can notice that the content changes for every receiver because the actor is the name of the receiver itself. The purpose of this abstract method is to return the actual content for the cfp message to be sent to the given receiver. A suggestion for the implementation is to insert a special symbol within the cfpContent that, at every call, is replaced with the AID of the receiver. Unfortunatelly, this default implementation cannot be provided by this behaviour because there exist no such a universal special symbol. Instead, the provided default implementation returns the passed cfpContent argument without any modification at all.
Parameters:
cfpContent - this is the content of the cfp message that was passed in the constructor of the behaviour
receiver - this is the AID of the receiver agent to which this content is destinated
Returns:
the actual content to be sent to this receiver

reset

public void reset()
This method resets this behaviour object so that it restarts from the initial state of the protocol.

Care must be taken to where this method is called because, in some intermediate states of the contract net protocol, restarting may cause unwanted side effects (e.g. not receiving some propose messages that refers to the previous cfp message).

Overrides:
reset in class SimpleBehaviour

reset

public void reset(ACLMessage msg,
                  java.util.List responders)
Parameters:
msg - updates the cfp message to be sent
responders - updates the group of agents to which the cfp message should be sent
See Also:
reset()