fsmbehaviour.java

来自「java实现的P2P多agent中间件」· Java 代码 · 共 688 行 · 第 1/2 页

/*****************************************************************
 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.core.behaviours;

//#CUSTOM_EXCLUDE_FILE

import java.util.Hashtable;
import jade.util.leap.*;
import jade.util.leap.Serializable;
import jade.util.Logger;

import jade.core.Agent;

/**
 Composite behaviour with Finite State Machine based children scheduling. 
 It is a <code>CompositeBehaviour</code> that executes its children 
 behaviours according to a FSM defined by the user. More specifically 
 each child represents a state in the FSM.
 The class provides methods to register states (sub-behaviours) and 
 transitions that defines how sub-behaviours will be scheduled.
 <p> At a minimum, the following steps are needed in order to properly
 define a <code>FSMBehaviour</code>:
 <ul>
 <li> register a single Behaviour as the initial state of the FSM by calling
 the method <code>registerFirstState</code>;
 <li> register one or more Behaviours as the final states of the FSM
 by calling the method <code>registerLastState</code>;
 <li> register one or more Behaviours as the intermediate states of the FSM
 by calling the method <code>registerState</code>;
 <li> for each state of the FSM, register the transitions to the other
 states by calling the method <code>registerTransition</code>;
 <li> the method <code>registerDefaultTransition</code> is also useful
 in order to register a default transition from a state to another state
 independently on the termination event of the source state.
 </ul>
 A number of other methods are available in this class for generic
 tasks, such as getting the current state or the name of a state, ...
 @see jade.core.behaviours.SequentialBehaviour
 @see jade.core.behaviours.ParallelBehaviour
 
 @author Giovanni Caire - CSELT
 @version $Date: 2008-04-15 11:09:57 +0200 (mar, 15 apr 2008) $ $Revision: 6029 $
 
 */
public class FSMBehaviour extends SerialBehaviour {
	
	private Map states = new HashMap();
	private Behaviour current = null;
	// Protected for debugging purposes only
	protected List lastStates = new ArrayList();
	protected String currentName = null;
	private String previousName = null;
	private String firstName = null;
	private int lastExitValue;
	
	// These variables are used to force a transition on a given state at runtime
	private boolean transitionForced = false;
	private String forcedTransitionDest = null;
	
	private TransitionTable theTransitionTable = new TransitionTable();
	
	//#J2ME_EXCLUDE_BEGIN
	private Logger myLogger = Logger.getMyLogger(FSMBehaviour.class.getName());
	//#J2ME_EXCLUDE_END
	
	/**
	 Default constructor, does not set the owner agent.
	 */
	public FSMBehaviour() {
		super();
	}
	
	/**
	 This constructor sets the owner agent.
	 @param a The agent this behaviour belongs to.
	 */
	public FSMBehaviour(Agent a) {
		super(a);
	} 
	
	/** 
	 Register a <code>Behaviour</code> as a state of this 
	 <code>FSMBehaviour</code>. When the FSM reaches this state
	 the registered <code>Behaviour</code> will be executed.
	 @param state The <code>Behaviour</code> representing the state
	 @param name The name identifying the state.
	 */
	public void registerState(Behaviour state, String name) {
		state.setBehaviourName(name);
		state.setParent(this);
		state.setAgent(myAgent);
		states.put(name, state);
		
		// Maybe we are over-writing the state that is currently in execution
		if (name.equals(currentName)) {
			current = state;
		}
	}
	
	/** 
	 Register a <code>Behaviour</code> as the initial state of this 
	 <code>FSMBehaviour</code>. 
	 @param state The <code>Behaviour</code> representing the state
	 @param name The name identifying the state.
	 */
	public void registerFirstState(Behaviour state, String name) {
		registerState(state, name);
		firstName = name;
	}
	
	/** 
	 Register a <code>Behaviour</code> as a final state of this 
	 <code>FSMBehaviour</code>. When the FSM reaches this state
	 the registered <code>Behaviour</code> will be executed and, 
	 when completed, the <code>FSMBehaviour</code> will terminate too. 
	 @param state The <code>Behaviour</code> representing the state
	 @param name The name identifying the state.
	 */
	public void registerLastState(Behaviour state, String name) {
		registerState(state, name);
		if (!lastStates.contains(name)) {
			lastStates.add(name);
		}
	}
	
	/** 
	 Deregister a state of this <code>FSMBehaviour</code>. 
	 @param name The name of the state to be deregistered.
	 @return the Behaviour if any that was registered as the 
	 deregistered state.
	 */
	public Behaviour deregisterState(String name) {
		Behaviour b = (Behaviour) states.remove(name);
		if (b != null) {
			b.setParent(null);
		}
		theTransitionTable.removeTransitionsFromState(name);
		if (name.equals(firstName)) {
			firstName = null;
		}
		lastStates.remove(name);
		return b;
	}
	
	/** 
	 Register a transition in the FSM defining the policy for
	 children scheduling of this <code>FSMBehaviour</code>.
	 @param s1 The name of the state this transition starts from
	 @param s2 The name of the state this transition leads to
	 @param event The termination event that fires this transition
	 as returned by the <code>onEnd()</code> method of the 
	 <code>Behaviour</code> representing state s1.
	 @see jade.core.behaviours.Behaviour#onEnd()
	 */
	public void registerTransition(String s1, String s2, int event) {
		registerTransition(s1, s2, event, null);
	}
	
	/** 
	 Register a transition in the FSM defining the policy for
	 children scheduling of this <code>FSMBehaviour</code>. 
	 When this transition is fired the states indicated in the
	 <code>toBeReset</code> parameter are reset. This is
	 particularly useful for transitions that lead to states that
	 have already been visited.
	 @param s1 The name of the state this transition starts from
	 @param s2 The name of the state this transition leads to
	 @param event The termination event that fires this transition
	 as returned by the <code>onEnd()</code> method of the 
	 <code>Behaviour</code> representing state s1.
	 @param toBeReset An array of strings including the names of 
	 the states to be reset.
	 @see jade.core.behaviours.Behaviour#onEnd()
	 */
	public void registerTransition(String s1, String s2, int event, String[] toBeReset) {
		Transition t = new Transition(this, s1, s2, event, toBeReset);
		theTransitionTable.addTransition(t);
	}
	
	/** 
	 Register a default transition in the FSM defining the policy for
	 children scheduling of this <code>FSMBehaviour</code>.
	 This transition will be fired when state s1 terminates with 
	 an event that is not explicitly associated to any transition. 
	 @param s1 The name of the state this transition starts from
	 @param s2 The name of the state this transition leads to
	 */
	public void registerDefaultTransition(String s1, String s2) {
		registerDefaultTransition(s1, s2, null);
	}
	
	/** 
	 Register a default transition in the FSM defining the policy for
	 children scheduling of this <code>FSMBehaviour</code>.
	 This transition will be fired when state s1 terminates with 
	 an event that is not explicitly associated to any transition. 
	 When this transition is fired the states indicated in the
	 <code>toBeReset</code> parameter are reset. This is
	 particularly useful for transitions that lead to states that
	 have already been visited.
	 @param s1 The name of the state this transition starts from
	 @param s2 The name of the state this transition leads to
	 @param toBeReset An array of strings including the names of 
	 the states to be reset.
	 */
	public void registerDefaultTransition(String s1, String s2, String[] toBeReset) {
		Transition t = new Transition(this, s1, s2, toBeReset);
		theTransitionTable.addTransition(t);
	}
	
	/**
	 * Deregister the transition from a given source state and identfied by a 
	 * given termination event. 
	 * @param source The name of the source state
	 * @param event The termination event that identifies the transition to be removed
	 */
	public void deregisterTransition(String source, int event) {
		theTransitionTable.removeTransition(source, event);
	}
	
	/**
	 * Deregister the default transition from a given source state.
	 * @param source The name of the source state
	 */
	public void deregisterDefaultTransition(String source) {
		theTransitionTable.removeTransition(source);
	}
	
	/**
	 * Check if a default transition exits from a given source state.
	 * @param source The name of the source state
	 * @return <code>true</code> if a default transition exits from the given source state. <code>false</code> otherwise.
	 */
	public boolean hasDefaultTransition(String source) {
		return (theTransitionTable.getTransition(source) != null);
	}
	
	/** 
	 Retrieve the child behaviour associated to the FSM state with
	 the given name.
	 @return the <code>Behaviour</code> representing the state whose
	 name is <code>name</code>, or <code>null</code> if no such
	 behaviour exists.
	 */
	public Behaviour getState(String name) {
		Behaviour b = null;
		if (name != null) {
			b = (Behaviour) states.get(name);
		}
		return b;
	}
	
	/** 
	 Retrieve the name of the FSM state associated to the given child
	 behaviour.
	 @return the name of the state represented by
	 <code>Behaviour</code> state, or <code>null</code> if the given
	 behaviour is not a child of this FSM behaviour.
	 */
	public String getName(Behaviour state) {
		Iterator it = states.keySet().iterator();
		while (it.hasNext()) {
			String name = (String) it.next();
			Behaviour s = (Behaviour) states.get(name);
			if (state == s) {
				return name;
			}
		}
		return null;
	}
	
	/** 
	 Retrieve the exit value of the most recently executed
	 child. This is also the trigger value that selects the next FSM
	 transition.
	 @return the exit value of the last executed state.
	 */
	public int getLastExitValue() {
		return lastExitValue;
	}
	
	/** 
	 Override the onEnd() method to return the exit value of the
	 last executed state.
	 */
	public int onEnd() {
		return getLastExitValue();
	}
	
	/**
	 Prepare the first child for execution. The first child is the 
	 <code>Behaviour</code> registered as the first state of this
	 <code>FSMBehaviour</code>
	 @see jade.core.behaviours.CompositeBehaviour#scheduleFirst
	 */
	protected void scheduleFirst() {
		if (transitionForced) {
			currentName = forcedTransitionDest;
			transitionForced = false;
		}
		else {
			// Normal case: go to the first state
			currentName = firstName;
		}
		current = getState(currentName);
		handleStateEntered(current);
		// DEBUG
		//System.out.println(myAgent.getLocalName()+" is Executing state "+currentName);
	}
	
	/**
	 This method schedules the next child to be executed. It checks 
	 whether the current child is completed and, in this case, fires
	 a suitable transition (according to the termination event of 
	 the current child) and schedules the child representing the 
	 new state.
	 @param currentDone a flag indicating whether the just executed
	 child has completed or not.
	 @param currentResult the termination value (as returned by
	 <code>onEnd()</code>) of the just executed child in the case this
	 child has completed (otherwise this parameter is meaningless)
	 @see jade.core.behaviours.CompositeBehaviour#scheduleNext(boolean, int)
	 */