/*

 * Created on Sep 19, 2003

 */

package isac.util.interfaces;

import java.rmi.Remote;

import java.rmi.RemoteException;

import isac.util.Formalization;

import isac.util.formulae.*;

import isac.util.tactics.*;

/**

 * Interface to be used to communicate in the direction towards the Math Engine.

 * 

 * @author Alan Krempler

 * WN040924 rename to ICalcTree !

 */

public interface IToCalc extends Remote {

	/**

	 * Get a new iterator referencing the root element of the calculation tree. 

	 * <p> The functionality for navigating the calculation 

	 * is implemented in the CalcIterator object.

	 * @return new instance of CalcIterator

	 */

	public ICalcIterator iterator()  throws RemoteException;

	/**

	 * Register a new listener who wants to be notified of changes in the data.

	 * The listener has to implement the IToUser interface.

	 * 

	 * @param listener New listener to be registered.

	 * @return false on success, true otherwise.

	 */  

	public boolean addDataChangeListener(IToUser listener)  throws RemoteException;

	/**

	 * @return an iterator referencing the current

	 * "hot spot" in the calculation, i.e. the active formula.

	 */

	public ICalcIterator getActiveFormula() throws RemoteException;

	/**

	 * Makes the passed formula the active formula, i.e. the formula 

	 * the next tactic is applied to.

	 * @param newActiveFormula Iterator referencing the new desired position

	 */

	public void moveActiveFormula(ICalcIterator newActiveFormula) throws RemoteException;

	 /**

	  * Enter the solving phase of the calculation.

	  * StartSpecifying must be called first

	  * Only possible with a complete and correct calcHead

	  * @param calcHead CalcHead for this calculation

	  * @return CalcTree represents the calculation on the java side

	  */

	 public void startSolving(/*CalcHead calcHead*/) throws Exception;

	 /**

	   * Modify a given CalcHead    

	   * The result is the same CalcHead with status flags for each item

	   * @see CalcHead for possible status flags

	   * @param calcHead CalcHead to be modified 

	   * @return new CalcHead with a status for each item   

	   */

	 public void modifyCalcHead(CalcHead calcHead);

	 /**

	   * Complete a given calcHead: Tell the Kernel to fill out 

	   * all the missing fields in the calcHead

	   * @param calcHead the calcHead to be completed

	   */

	 public void completeCalcHead(CalcHead calcHead);

	 /**

	  * Complete a given calcHead: Tell the Kernel to fill out 

	  * a missing fields in the calcHead, which is specified by an

	  * parameter

	  * @param calcHead the calcHead to be completed

	  * @param completeItem the item which should be added

	  * 

	  * WN040916 don't confuse with autCalculate(...CompleteCalcHead)

	  */

	 public void completeCalcHead(CalcHead calcHead, int completeItem);

	 /**

	 * Tries to replaces the active formula in the calculation tree by 

	 * the passed formula. This could fail if no valid derivation from 

	 * the preceding formula to the (new) active formula can be found. 

	 * <p>Parts of the calculation after the replaced 

	 * formula are likely to become invalid, listeners will be informed

	 * of this with the update message, which contains the last unchanged 

	 * formula.

	 * @param newFormula

	 * @return The method will return 0 on success or a nonzero value 

	 * indicating the status otherwise. 

	 */

	public int replaceFormula(Formula newFormula) throws RemoteException;

	/**

	Tries to append the passed formula after the active formula. 

	This could fail if no valid derivation from the preceding formula 

	to the (new) active formula can be found. The method will fail as 

	well if the active formula is not the last formula in the (sub)calculation.

	Parts of the calculation might become invalid.

	* @param newFormula

	* @return The method will return 0 on success or a nonzero value 

	indicating the status otherwise.

	*/

	public int appendFormula(Formula newFormula) throws RemoteException;

	/**

	 Set the tactic to be used in the next step of calculation.   

	 * @param tactic the Tactic to be used in the the next step

	 * @return The return value indicates success, failure or probable

	 * success at a later time.

	 */

	 public int setNextTactic(Tactic tactic) throws RemoteException;

	/**

	 * Retrieve the tactic proposed by the SML-Kernel for 

	 * the next step in the calculation.  

	 * @return proposed tactic.

	 * Can be null, if the kernel does

	 * not know what to do next, or if the end 

	 * of the calculation is reached 

	 */

	 public Tactic fetchProposedTactic() throws RemoteException;

	/**

	 * Fetch all tactics applicable to the current situation known to

	 * the system.

	 * @see #fetchApplicableTactics(int)

	 */

	 public static final int TACTICS_ALL = 1;

	/**

	 * Fetch all tactics applicable to the current situation, but restrict

	 * the result to tactics from the current theory.

	 * @see #fetchApplicableTactics(int)

	 */

	 public static final int TACTICS_CURRENT_THEORY = 2;

	/**

	 * Fetch all tactics applicable to the current situation, but restrict 

	 * the result to tactics from the method being applied.

	 * @see #fetchApplicableTactics(int)

	 */

	 public static final int TACTICS_CURRENT_METHOD = 3;

	/**

	 * Get a list of tactics applicable to the active formula. 

	 * @param scope The filter parameter selects the scope of

	 * search for applicable tactics.

	 * @return Array with applicable tactics

	 * @see #TACTICS_ALL

	 * @see #TACTICS_CURRENT_THEORY

	 * @see #TACTICS_CURRENT_METHOD

	 */

	 public Tactic[] fetchApplicableTactics(int scope) throws RemoteException;

	/**

	 * Do the number of steps requested, without any restrictions.

	 * autoCalculate ... CompleteCalc

	 * Do NOT change the value of this constant, as this 

	 * number has a specifig meaning in other parts of the system!

	 * @see #autoCalculate(int, int)

	 */	 

	 public static final int SCOPE_CALCULATION = 6;

	/**

	 * Do the number of steps requested, but do not leave the 

	 * current subcalculation into a subproblem: CompleteToSubpbl

	 * Do NOT change the value of this constant, as this 

	 * number has a specifig meaning in other parts of the system!

	 * @see #autoCalculate(int, int)

	 */	 

	 public static final int SCOPE_SUBCALCULATION = 5;

	/**

	 * Do the number of steps requested, but do not leave the 

	 * current subproblem: autoCalculate ... CompleteSubpbl

	 * Do NOT change the value of this constant, as this 

	 * number has a specifig meaning in other parts of the system!

	 * @see #autoCalculate(int, int)

	 */	 

	 public static final int SCOPE_SUBPROBLEM = 4;

	/**

	 * Calculate the next n steps starting from the active formula or until the 

	 * specified scope is left, whichever comes first.   

	 * @param scope The scope parameter can have following values:

	 * @param nSteps Specifies the count of steps to be autocalculated. 

	 * Passing 0 for nSteps will calculate until reaching a final result. 

	 * @return The method returns an unique id to identify the request when 

	 * notifying about updates in the tree.

	 * @see #SCOPE_CALCULATION

	 * @see #SCOPE_SUBCALCULATION

	 * @see #SCOPE_SUBPROBLEM

	 */

	/*WN040624: the above design is desirable, but currently not impl., rather:

	 * either steps == 0, then regard SCOPE_*

	 * or	  steps != 0, then SCOPE_* irrelevant !

	 */

	 public int autoCalculate(int scope, int nSteps) throws RemoteException;

}