/*

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

}