/*

 * Created on Sep 19, 2003

 */

package isac.util.interfaces;

import isac.util.formulae.Assumptions;

import isac.util.formulae.KEStoreID;

import isac.util.formulae.Match;

import isac.util.formulae.Position;

import isac.util.formulae.ProblemID;

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

     * 

     * FIXXXME.WN050624 review calls when getFormula is deleted

     */

    public ICalcElement getElement() throws RemoteException;

    /**

     * get the Formulae and CalcHeads of the calcTree between this.iterator

     * ('from')and the argument iterator ('to'), excluding the 'from' and

     * including 'to' iterator, i.e. the elements the iterators are pointing to

     * 

     * @see isac.util.CalcChangedEvent.last_unchanged_formula_ which is to be

     *      set this.iterator, and

     * @see isac.util.CalcChangedEvent.last_generated_formula_ which is to be

     *      set to iterator_to

     * 

     * @param iterator_to

     *            The iterator pointing at the last element of the returned

     *            range

     * @param level

     *            The maximum level of the elements in the range, element with a

     *            higher level (which are "deeper" in the hierarchie are not

     *            returned null if everything should be displayed

     * @param result_includes_tactics

     *            true if the result should include the tactics, false otherwise

     * 

     * @return an Vector containing the Formulae and CalcHeads of the calcTree

     * @author Alois Kirchsteiger 12.01.2005 16:51:43

     */

    public Vector getElementsFromTo(ICalcIterator iterator_to, Integer level,

            boolean result_includes_tactics) throws RemoteException;

    /**

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

     * 

     * @deprecated in favour if getElement FIXXXME.WN050624

     */

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

    /**

     * Match the problem referenced by ProblemID with the CalcHead at or just

     * above the Position in the CalcTree this CalcIterator is pointing to.

     * 

     * @param ProblemID

     *            or MethodID

     * 

     * @return Match with the fields Given, Find, Where, Related with status

     *         etc.

     */

    public Match tryMatchProblem(ProblemID problemID) throws RemoteException;

    /**

     * Refine the problem referenced by ProblemID with the CalcHead at or just

     * above the Position in the CalcTree this CalcIterator is pointing to. The

     * problem to be refined may remain the same.

     * 

     * @param ProblemID

     *            or MethodID

     * 

     * @return Match with the fields Given, Find, Where, Related with status,

     *         the problemID pointing at the refined problem etc.

     */

    public Match tryRefineProblem(ProblemID problemID) throws RemoteException;

    /**

     * matches the Model on the Worksheet with the guard (Given, Where, Find,

     * Relate) of the Method. The model is marked by the ActiveFormula (either

     * on the CalcHead containing the Model or on a child-node of the CalcHead.

     * There is no tryRefineMethod, because the hierarchy of Method's has no

     * 'refine" yet.

     * 

     * @see isac.util.interfaces.ICalcIterator#tryMatchProblem(KEStoreID)

     */

    public Match tryMatchMethod(KEStoreID KEStoreID) throws RemoteException;

}