/**

  * @author Alan Krempler

  * Created on Sep 19, 2003

  */

 package isac.interfaces;

 import java.rmi.Remote;

 import java.rmi.RemoteException;

 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 {

     /** remove the CalcTree in the math-engine

      */

     public boolean destruct() throws RemoteException;

     /**

      * 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;

     /**

      * Set the Descriptions for all ModelItems given by the problem which is

      * specified in the CalcHead held in the MathEngine (this may still be

      * hidden from the front-end).

      * 

      * in contrary to isac.interfaces.IToCalc#setNextTactic this method has a

      * returnvalue from the calculation.

      * 

      * @return CalcHead with Descriptions (e.g. equality, solveFor)

      * @exception RemoteException

      */

     public CalcHead modelProblem() throws RemoteException;

     /**

      * Add _ONE_ item to the Model or to the Specification, as long as the

      * CalcHead is not complete.

      * 

      * in contrary to the methods for the solve-phase this method returns a

      * value from the calculation.

      * 

      * @return CalcHead with one item added; if the CalcHead was complete, the

      *         CalcHead remains unchanged

      * @exception RemoteException

      */

     public CalcHead nextSpecify() throws RemoteException;

     /**

      * Check a given CalcHead. The result is the same CalcHead with status flags

      * for each item

      * 

      * in contrary to the methods for the solve-phase this method returns a

      * value from the calculation.

      * 

      * @see CalcHead for possible status flags

      * @param calc_head

      *            CalcHead to be checked

      * @return new CalcHead with a status for each item

      */

     public CalcHead checkCalcHead(CalcHead calc_head) throws RemoteException;

     /**

      * Complete the Model of a CalcHead: Tell the Kernel to fill out all the

      * missing fields in the Model; this may not succeed if the (manual) input

      * is too messed up (in this case first a resetCalcHead must be done).

      * 

      * in contrary to the methods for the solve-phase this method returns a

      * value from the calculation.

      * 

      * @return the CalcHead with the completed Model

      */

     public CalcHead completeModel() throws RemoteException;

     /**

      * Transfer the Theory selected in the TheoryBrowser to the SML-kernel. This

      * method is used for transferring the Theory to the Worksheet (i.e. the

      * CalcHead with the Theory inserted and checked has to be fetched from the

      * SML-kernel by the front-end)

      * 

      * in contrary to the methods for the solve-phase this method returns a

      * value from the calculation.

      * 

      * @param thy_id

      *            the identifier of the theory

      * @return CalcHead with the Theory inserted; the new Theory may cause parse

      *         errors (because parts of a formula are unknown in this Theory)

      *         displayed in the Model (or in the guard)

      * @exception RemoteException

      */

     public CalcHead setTheory(String thy_id) throws RemoteException;

     /**

      * Transfer the Problem selected in the ProblemBrowser to the SML-kernel.

      * This method is used for transferring the Problem to the Worksheet (i.e.

      * the CalcHead with the Problem inserted and checked has to be fetched from

      * the SML-kernel by the front-end)

      * 

      * in contrary to the methods for the solve-phase this method returns a

      * value from the calculation.

      * 

      * @return CalcHead with the Problem inserted; the new Problem may cause

      *         error-status for some ModelItems already input (because they do

      *         not match the Problem selected)

      * @exception RemoteException

      */

     public CalcHead setProblem(ProblemID id) throws RemoteException;

     /**

      * Transfer the Method selected in the MethodBrowser to the SML-kernel. This

      * method is used for transferring the Method to the Worksheet (i.e. the

      * CalcHead with the Method inserted and checked has to be fetched from the

      * SML-kernel by the front-end)

      * 

      * in contrary to the methods for the solve-phase this method returns a

      * value from the calculation.

      * 

      * @return CalcHead with the Method inserted; the new Method may cause

      *         error-status for some ModelItems in the guard (because they do

      *         not match the Method selected)

      * @exception RemoteException

      */

     public CalcHead setMethod(MethodID id) throws RemoteException;

     /**

      * Complete a given CalcHead: Tell the Kernel to fill out all the missing

      * fields in the Model _and_ in the Specification; this may not succeed if

      * the (manual) input is too messed up (in this case first a resetCalcHead

      * must be done).

      * 

      * in contrary to the methods for the solve-phase this method returns a

      * value from the calculation.

      * 

      * @return the completed CalHead

      */

     public CalcHead completeCalcHead() throws RemoteException;

     /**

      * Reset the CalcHead to the state as it was after startCalculation. This

      * may help to escape from a CalcHead with messed input, which may not allow

      * for a successful completeCalcHead.

      * 

      * in contrary to the methods for the solve-phase this method returns a

      * value from the calculation.

      * 

      * @return an empty CalcHead

      * @exception RemoteException

      */

     public CalcHead resetCalcHead() throws RemoteException;

     /**

      * Complete a given calc_head_: Tell the Kernel to fill out a missing field

      * in the calc_head_, which is specified by an parameter

      * 

      * in contrary to the methods for the solve-phase this method returns a

      * value from the calculation.

      * 

      * @param calc_head_

      *            the calc_head_ to be completed

      * @param completeItem

      *            the item which should be added TODO: return int like

      *            replaceFormula etc. WN040916 don't confuse with

      *            autCalculate(...CompleteCalcHead) WN0504 this case is notyet

      *            designed: how indicate the field ???

      * @return the completed CalHead

      */

     public CalcHead completeCalcHead(CalcHead calcHead, int completeItem)

             throws RemoteException;

     /**

      * 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(CalcFormula 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(CalcFormula newFormula) throws RemoteException;

     /**

      * requests the intermediate steps leading to the Formula at the Iterator

      * (i.e. these steps might be calculated by the math-engine)

      * 

      * @param Iterator

      * 

      * @return transactionID also returned in the CalcChanged

      */

     public int intermediateSteps(ICalcIterator ic) 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 = 7;

     /**

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

      * ... CompleteModel 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_MODEL = 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. in the

      * math-engine, rather: either steps == 0, then regard SCOPE_* or steps !=

      * 0, then SCOPE_* irrelevant !

      */

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

 }