/*

  * Created on Sep 19, 2003

  */

 package isac.util.interfaces;

 import isac.util.formulae.Assumptions;

 import isac.util.formulae.CalcFormula;

 import isac.util.formulae.Position;

 import isac.util.tactics.Tactic;

 import java.rmi.Remote;

 import java.rmi.RemoteException;

 import java.util.Vector;

 /**

  * References a certain position in a CalcTree.

  * 

  * At such a Position there is (a) a Formula or a CalcHead (b) a Tactic which is

  * applicable to this Formula (Apply_Method is the only Tactic applicable to a

  * CalcHead) (c) an Assumption generated by application of this Tactic to this

  * Formula

  * Invariant: The Level changes at most +/- ONE when moveUp or moveDown.

  * 

  * a CalcIterator may be invalid,

  * 

  * @see isac.util.CalcChangedEvent#

  * 

  * Comments for the Dialog Guide # on 'applicable Tactic': if a Formula is also

  * a parent of some children (one LevelDown), there is also a 'DETAILED

  * applicable Tactic' generating the children. WN040920 presentation unclear #

  * on 'causal Tactic': this direction of investigation is opposite to the

  * applicablility of Tactics; investigating in this direction, for each Formula

  * the Tactic can befound which generated the Formula. The causal Tactic is

  * unique for each Formula, with the exception of Positions with moveLevelUp

  * (there is a 'DETAILED causal Tactic' analogously to 'DETAILED applicable

  * Tactic' at LevelDown)

  * 

  * @see isac.util.formulae.CalcElement

  * @see isac.bridge.CalcTree

  * @author Alan Krempler

  */

 public interface ICalcIterator extends Comparable, Cloneable, Remote {

     /**

      * get the marker 'Position' unique within a CalcTree (i.e. a CalcIterator)

      * 

      * @return Position

      */

     public Position getPosition() throws RemoteException;

     /**

      * Reference the first (root) element in the attached calculation tree.

      * 

      * @return Like all the moveXXX methods this returns true on success, false

      *         if there is no element to move to.

      */

     public boolean moveRoot() throws RemoteException;

     /**

      * Reference the next enclosing CalcHead element in the attached calculation

      * tree. This will be the subproblem being solved at the moment, or, if not

      * solving subproblems, the root problem of the calculation.

      * 

      * @return Like all the moveXXX methods this returns true on success, false

      *         if there is no element to move to.

      */

     public boolean moveCalcHead() throws RemoteException;

     /**

      * Reference the previous formula in the attached calculation tree.

      * 

      * @return Like all the moveXXX methods this returns true on success, false

      *         if there is no element to move to.

      */

     public boolean moveUp() throws RemoteException;

     /**

      * Reference the next formula in the attached calculation tree.

      * 

      * @return Like all the moveXXX methods this returns true on success, false

      *         if there is no element to move to.

      * 

      * moveRoot() plus moveDown() reaches all nodes in a CalcTree

      */

     public boolean moveDown() throws RemoteException;

     /**

      * Enter the next coarser level of refinement in the attached calculation

      * tree.

      * 

      * @return Like all the moveXXX methods this returns true on success, false

      *         if there is no element to move to.

      */

     public boolean moveLevelUp() throws RemoteException;

     /**

      * Enter the next more detailed level of refinement in the attached

      * calculation tree.

      * 

      * @return Like all the moveXXX methods this returns true on success, false

      *         if there is no element to move to.

      */

     public boolean moveLevelDown() throws RemoteException;

     /**

      * Reference the formula which resulted in the currently selected element of

      * the attached calculation tree.

      */

     public boolean moveFormula() throws RemoteException;

     /**

      * Ask whether this is the last Item, which is equivalent to whwther there

      * is another item where moveDown() could move to.

      * 

      * @return true, if moveDown() would not yield any new elements false, if

      *         moveDown() would move to another element WN040819 awaiting

      *         problems with parallel branches (OR, AND, etc.) in calcTree

      * @deprecated due to calcChangedEvent since 0512

      */

     public boolean isLast() throws RemoteException;

     /**

      * is the Iterator on a CalcHead or not

      */

     public boolean onCalcHead() throws RemoteException;

     /**

      * Use this to get the current element and check the type by calling

      * getType().

      * 

      * @return The currently referenced Element

      * @see #getType()

      * @deprecated due to getFormula, getTactic, getAssumption

      */

     public ICalcElement getElement() throws RemoteException;

     /**

      * @return Formula, which may also be a CalcHead !

      */

     public ICalcElement getFormula() throws RemoteException;

     /**

      * @return Tactic applicable to the formula under the Iterator

      */

     public Tactic getTactic() throws RemoteException;

     /**

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

      * 

      * @param scope

      *            WN0502 not yet impl. The filter parameter selects the scope of

      *            search for applicable tactics.

      * @return Vector with applicable tactics

      * @see #TACTICS_ALL

      * @see #TACTICS_CURRENT_THEORY

      * @see #TACTICS_CURRENT_METHOD

      */

     public Vector getApplicableTactics(int scope) throws RemoteException;

     /**

      * @return Assumptions generated by the Tactic applied to the formula, both

      *         under the same Iterator

      */

     public Assumptions getAssumptions() throws RemoteException;

     /**

      * @return Assumptions accumulated during calculation down to the formula

      *         under the Iterator ATTENTION: this returnvalue is also used by

      *         getAssumptions as long as getAccumulatedAssumptions does not

      *         include references to their _several_ sources -- i.e. change

      *         _this_ return, not that in getAssumptions !

      */

     public Assumptions getAccumulatedAssumptions() throws RemoteException;

     /**

      * The current level of nesting into subcalculations.

      * 

      * @return An int representing level of nesting (higher == more detailed)

      *         <p>

      *         Special values:

      *         <p>

      *         0: outmost level: only first and last step of calculation are on

      *         this level

      */

     public int getLevel() throws RemoteException;

     /**

      * Create a copy of this Iterator: the clone will point to the same formula

      * in the calcTree

      * 

      * @return a cloned Iterator

      */

     public Object clone();

     /**

      * for test-output

      * 

      * @return 'position', i.e. unique identifier in a CalcTree

      */

     public String toSMLString();

     //	/**

     //	 * Create a copy of this Iterator: the clone will point to the Position

     //	 * in the calcTree (Position may come from a formula in the worksheet)

     //	 *

     //	 * @return a cloned Iterator

     //	 */

     //	public ICalcIterator clone(Position p);

     //	/**

     //	 * @return the position unique within a calctree

     //	 * @see isac.uti.interfaces.ICalcIterator#clone(Position)

     //	 */

     //	public Position getSmlPos();

 }