/*

 * Created on Sep 19, 2003

 */

package isac.util.interfaces;

import java.rmi.Remote;

import java.rmi.RemoteException;

import java.util.Vector;

import isac.bridge.CalcTree;

import isac.util.Formalization;

import isac.util.NotInSpecificationPhaseException;

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;

    //	/**

    //	 * Start the a calculation by providing initial values to the Dialog On

    //	 * success, the Dialog is in DIALOGPHASE_SOLVE

    //	 *

    //	 * @param user_id

    //	 * The user

    //	 * @param f

    //	 * Formalization from the example collection or null

    //	 * @param started_from

    //	 * STARTFROM_*

    //	 * @return @throws

    //	 * RemoteException

    //	 *

    //	 * @see isac.util.Formalization

    //	 */

    //	public CalcTree startCalculation(int user_id, Formalization f,

    //			int started_from/* , int requested_calchead_view */)

    //			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 TODO: return int like

     *         replaceFormula etc.

     */

    public void modifyCalcHead(CalcHead calcHead) throws RemoteException;

    /**

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

     * fields in the calcHead

     * 

     * @param calcHead

     *            the calcHead to be completed TODO: return int like

     *            replaceFormula etc.

     */

    public void completeCalcHead() throws RemoteException;

    /**

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

     * the calcHead, which is specified by an parameter

     * 

     * @param calcHead

     *            the calcHead 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 ???

     */

    public void 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 CalcChangedEvent

     */

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

    /**

     * get the Formulae and CalcHeads of the calcTree between the two iterators

     * (including the elements the two iterators a pointing to)

     * 

     * @param iterator_from

     *            The iterator pointing to the element immediately before of the

     *            returned range (which supports direct use of ...

     * @see isac.util.CalcChangedEvent.last_unchanged_formula_

     * @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 (who 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_from,

            ICalcIterator iterator_to, Integer level,

            boolean result_includes_tactics) throws RemoteException;

	/**

	 * Match a given problem for this CalcTree

	 * 

	 * @param problemID

	 * @param CalcHead FIXXXME.WN050610 drop !!!

	 * 

	 * @return CalcHead, if the operation was successful, else null

	 * ... replaced by ref-arg to be used instead

	 */

	public void tryMatch(CalcHead calcHead, CalcHeadCompoundID problemID)

			throws NotInSpecificationPhaseException;

}