gt: 			for(int i=0; i < states.length; i++){
context: /*****************************************************************
   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 jade.core.Agent;
  import jade.util.Logger;
  import jade.util.leap.*;
  
  import java.util.Hashtable;
  
  /**
   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 SequentialBehaviour
   @see 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 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 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 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 CompositeBehaviour#scheduleNext(boolean, int)
  	 */
  	protected void scheduleNext(boolean currentDone, int currentResult) {
  		if (currentDone) {
  			try {
  				previousName = currentName;
  				if (transitionForced) {
  					currentName = forcedTransitionDest;
  					transitionForced = false;
  				}
  				else {
  					// Normal case: use the TransitionTable to select the next state
  					Transition t = theTransitionTable.getTransition(currentName, currentResult);
  					resetStates(t.toBeReset);
  					currentName = t.dest;
  				}
  				current = getState(currentName);
  				if (current == null) {
  					throw new NullPointerException();
  				}
  				else {
  					handleStateEntered(current);
  				}
  			}
  			catch (NullPointerException npe) {
  				current = null;
  				handleInconsistentFSM(previousName, currentResult);
  			}
  			// DEBUG
  			//System.out.println(myAgent.getLocalName()+ " is Executing state "+currentName);
  		}
  	}
  	
  	protected void handleInconsistentFSM(String current, int event) {
  		throw new RuntimeException("Inconsistent FSM. State: "+current+" event: "+event);
  	}
  	
  	protected void handleStateEntered(Behaviour state) {
  	}
  	
  	/**
  	 Check whether this <code>FSMBehaviour</code> must terminate.
  	 @return true when the last child has terminated and it 
  	 represents a final state. false otherwise
  	 @see CompositeBehaviour#checkTermination
  	 */
  	protected boolean checkTermination(boolean currentDone, int currentResult) {
  		boolean ret = false;
  		if (currentDone) {
  			lastExitValue = currentResult;
  			ret = lastStates.contains(currentName);
  		}
  		//#J2ME_EXCLUDE_BEGIN
  		if (myLogger.isLoggable(Logger.FINE)) {
  			myLogger.log(Logger.FINE, "FSM-Behaviour "+getBehaviourName()+": checkTermination() returning "+ret);
  		}
  		//#J2ME_EXCLUDE_END
  		return ret;
  	}  		
  	
  	/** 
  	 Get the current child
  	 @see CompositeBehaviour#getCurrent
  	 */
  	protected Behaviour getCurrent() {
  		return current;
  	}
  	
  	/**
  	 Return a Collection view of the children of 
  	 this <code>SequentialBehaviour</code> 
  	 @see CompositeBehaviour#getChildren
  	 */
  	public Collection getChildren() {
  		return states.values();
  	}
  	
  	/**
  	 Temporarily disregards the FSM structure, and jumps to the given
  	 state. This method acts as a sort of <code>GOTO</code> statement
  	 between states, and replaces the currently active state without
  	 considering the trigger event or whether a transition was
  	 registered. It should be used only to handle exceptional
  	 conditions, if default transitions are not effective enough.
  	 
  	 @param next The name of the state to jump to at the next FSM
  	 cheduling quantum. If the FSM has no state with the given name,
  	 this method does nothing.
  	 */
  	protected void forceTransitionTo(String next) {
  		// Just check that the forced transition leads into a valid state
  		Behaviour b = getState(next);
  		if (b != null) {
  			transitionForced = true;
  			forcedTransitionDest = next;
  		}
  	}
  	
  	/** 
  	 Get the previously executed child
  	 @see CompositeBehaviour#getCurrent
  	 */
  	protected Behaviour getPrevious() {
  		return getState(previousName);
  	}
  	
  	/**
  	 Put this FSMBehaviour back in the initial condition.
  	 */ 
  	public void reset() {
  		super.reset();
  		transitionForced = false;
  		forcedTransitionDest = null;
  	}
  	
  	/**
  	 Reset the children behaviours registered in the states indicated in
  	 the <code>states</code> parameter.
  	 @param states the names of the states that have to be reset
  	 */
  	public void resetStates(String[] states) {	
  		if (states != null) {
  