iteratedachievereinitiator.java

来自「java实现的P2P多agent中间件」· Java 代码 · 共 223 行

/*****************************************************************
 JADE - Java Agent DEvelopment Framework is a framework to develop
 multi-agent systems in compliance with the FIPA specifications.
 Copyright (C) 2000 CSELT S.p.A.
 
 GNU Lesser General Public License
 
 This library is free software; you can redistribute it and/or
 modify it under the terms of the GNU Lesser General Public
 License as published by the Free Software Foundation, 
 version 2.1 of the License. 
 
 This library is distributed in the hope that it will be useful,
 but WITHOUT ANY WARRANTY; without even the implied warranty of
 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 Lesser General Public License for more details.
 
 You should have received a copy of the GNU Lesser General Public
 License along with this library; if not, write to the
 Free Software Foundation, Inc., 59 Temple Place - Suite 330,
 Boston, MA  02111-1307, USA.
 *****************************************************************/

package jade.proto;

//#CUSTOM_EXCLUDE_FILE

import jade.core.*;
import jade.core.behaviours.*;
import jade.lang.acl.*;
import java.util.Vector;

/**
 This class implements the initiator role in the iterated version of
 fipa-request like interaction protocols. In the iterated version, having 
 received all the result notifications from the responders, the initiator
 may send further initiation messages.
 The session of such a protocol with a given responder terminates when 
 one of the followings occurs:
 i) The initiator sends an explicit CANCEL message instead of the next 
 initiation message to the responder.
 ii) The responder replies with a negative reply i.e. REFUSE, NOT_UNDERSTOOD 
 or FAILURE 
 ii) The responder attaches a termination flag to an INFORM result notification. 
 That termination flag can be detected using the 
 <code>isSessionTerminated()</code> method.   
 
 @author Giovanni Caire - TILab
 */
public class IteratedAchieveREInitiator extends AchieveREInitiator {
	/** 
	 Key to retrieve from the DataStore of the behaviour the vector of
	 ACLMessage objects that will be sent at next round.
	 */
	public final String ALL_NEXT_REQUESTS_KEY = "__all-next-requests" + hashCode();
	
	public static final String REINIT = "Reinit";
	
	/**
	 Construct an <code>IteratedAchieveREInitiator</code> with an empty DataStore
	 */
	public IteratedAchieveREInitiator(Agent a, ACLMessage msg){
		this(a,msg,new DataStore());
	}
	
	/**
	 Construct an <code>IteratedAchieveREInitiator</code> with a given DataStore
	 @param a The agent performing the protocol
	 @param msg The message that must be used to initiate the protocol.
	 Notice that the default implementation of the 
	 <code>prepareRequest()</code> method returns an array composed of 
	 only this message. The values of the slot 
	 <code>reply-with</code> is ignored and a different value is assigned
	 automatically by this class for each receiver.
	 @param store The <code>DataStore</code> that will be used by this 
	 <code>AchieveREInitiator</code>
	 */
	public IteratedAchieveREInitiator(Agent a, ACLMessage msg, DataStore store) {
		super(a, msg, store);
		
		// Register the FSM transitions specific to the Iterated-Achieve-RE protocol
		registerDefaultTransition(HANDLE_ALL_RESULT_NOTIFICATIONS, REINIT);					
		registerDefaultTransition(REINIT, SEND_INITIATIONS);		
		
		// The HANDLE_ALL_RESULT_NOTIFICATIONS state must no longer be final
		Behaviour b = deregisterState(HANDLE_ALL_RESULT_NOTIFICATIONS);
		b.setDataStore(getDataStore());
		registerState(b, HANDLE_ALL_RESULT_NOTIFICATIONS);
		
		// REINIT
		b = new OneShotBehaviour(myAgent) {
			public void action() {
				prepareForNextRound();
			}
		};
		b.setDataStore(getDataStore());
		registerState(b, REINIT);
	}
	
	//#APIDOC_EXCLUDE_BEGIN
	protected void prepareForNextRound() {
		// Reset local variables, clean data store, reset children and copy the
		// "next-requests" of previous round to the "requests" of the next round.
		Vector v = (Vector) getDataStore().get(ALL_NEXT_REQUESTS_KEY);
		reinit();
		resetChildren();
		initializeDataStore(null);
		getDataStore().put(ALL_REQUESTS_KEY, v);
	}
	
	protected void initializeDataStore(ACLMessage msg) {
		super.initializeDataStore(msg);
		Vector v = new Vector();
		getDataStore().put(ALL_NEXT_REQUESTS_KEY, v);
	}  		
	
	protected ProtocolSession getSession(ACLMessage msg, int sessionIndex) {
		if (msg.getPerformative() == ACLMessage.CANCEL) {
			return null;
		}
		else {
			return super.getSession(msg, sessionIndex);
		}
	}   
	//#APIDOC_EXCLUDE_END
	
	
	/**
	 This method is called every time an <code>inform</code>
	 message is received, which is not out-of-sequence according
	 to the protocol rules.
	 This default implementation does nothing; programmers might
	 wish to override this method in case they need to react to this event.
	 @param inform the received inform message
	 @param nextRequest the Vector of ACLMessage objects to be sent at 
	 next round
	 */
	protected void handleInform(ACLMessage inform, Vector nextRequests) {
	}
	
	/** 
	 This method is redefined to call the proper overloaded method
	 */
	protected final void handleInform(ACLMessage inform) {
		Vector v = (Vector) getDataStore().get(ALL_NEXT_REQUESTS_KEY);
		handleInform(inform, v);  
	}
	
	/**
	 This method is called when all the result notification messages 
	 of the current round have been collected. 
	 By result notification message we intend here all the <code>inform, 
	 failure</code> received messages, which are not out-of-sequence 
	 according to the protocol rules.
	 This default implementation does nothing; programmers might
	 wish to override this method in case they need to react to this event
	 by analysing all the messages in just one call.
	 @param resultNodifications the Vector of ACLMessage object received 
	 @param nextRequest the Vector of ACLMessage objects to be sent at 
	 next round
	 */
	protected void handleAllResultNotifications(Vector resultNotifications, Vector nextRequests) {
	}
	
	/** 
	 This method is redefined to call the proper overloaded method
	 */
	protected final void handleAllResultNotifications(Vector resultNotifications) {
		Vector v = (Vector) getDataStore().get(ALL_NEXT_REQUESTS_KEY);
		handleAllResultNotifications(resultNotifications, v);  
	}
	
	/**
	 This method allows to register a user defined <code>Behaviour</code>
	 in the HANDLE_REFUSE state.
	 This behaviour would override the homonymous method.
	 This method also set the 
	 data store of the registered <code>Behaviour</code> to the
	 DataStore of this current behaviour.
	 The registered behaviour can retrieve the received <code>inform</code> 
	 ACLMessage object from the datastore at the <code>REPLY_KEY</code>
	 key and the Vector of ACLMessage objects to be sent at next round
	 at the <code>ALL_NEXT_REQUESTS_KEY</code>.
	 @param b the Behaviour that will handle this state
	 */
	public void registerHandleInform(Behaviour b) {
		// This is redefined for Javadoc purposes only.
		super.registerHandleInform(b);
	}
	
	/**
	 This method allows to register a user defined <code>Behaviour</code>
	 in the HANDLE_ALL_RESULT_NOTIFICATIONS state.
	 This behaviour would override the homonymous method.
	 This method also set the 
	 data store of the registered <code>Behaviour</code> to the
	 DataStore of this current behaviour.
	 The registered behaviour can retrieve
	 the Vector of ACLMessage objects, received as a result notification,
	 from the datastore at the <code>ALL_RESULT_NOTIFICATIONS_KEY</code>
	 key and the Vector of ACLMessage objects to be sent at next round
	 at the <code>ALL_NEXT_REQUESTS_KEY</code>.
	 @param b the Behaviour that will handle this state
	 */
	public void registerHandleAllResultNotifications(Behaviour b) {
		// Method redefined since HANDLE_ALL_RESULT_NOTIFICATION must not be 
		// registered as a final state
		registerState(b, HANDLE_ALL_RESULT_NOTIFICATIONS);
		b.setDataStore(getDataStore());
	}    
	
	/**
	 * Check if the responder has closed the session just after sending this <code>inform</code> message.
	 */
	public static boolean isSessionTerminated(ACLMessage inform) {
		String terminatedStr = inform.getUserDefinedParameter(SSIteratedAchieveREResponder.ACL_USERDEF_TERMINATED_SESSION);
		return "true".equals(terminatedStr);
	}
}