1.1 --- a/src/java/isac/util/interfaces/IToCalc.java Thu May 12 18:03:51 2005 +0200
1.2 +++ b/src/java/isac/util/interfaces/IToCalc.java Thu May 12 18:06:13 2005 +0200
1.3 @@ -20,277 +20,278 @@
1.4
1.5 public interface IToCalc extends Remote {
1.6
1.7 - /**
1.8 - * Get a new iterator referencing the root element of the calculation tree.
1.9 - * <p>
1.10 - * The functionality for navigating the calculation is implemented in the
1.11 - * CalcIterator object.
1.12 - *
1.13 - * @return new instance of CalcIterator
1.14 - */
1.15 - public ICalcIterator iterator() throws RemoteException;
1.16 + /**
1.17 + * Get a new iterator referencing the root element of the calculation tree.
1.18 + * <p>
1.19 + * The functionality for navigating the calculation is implemented in the
1.20 + * CalcIterator object.
1.21 + *
1.22 + * @return new instance of CalcIterator
1.23 + */
1.24 + public ICalcIterator iterator() throws RemoteException;
1.25
1.26 - /**
1.27 - * Register a new listener who wants to be notified of changes in the data.
1.28 - * The listener has to implement the IToUser interface.
1.29 - *
1.30 - * @param listener
1.31 - * New listener to be registered.
1.32 - * @return false on success, true otherwise.
1.33 - */
1.34 - public boolean addDataChangeListener(IToUser listener)
1.35 - throws RemoteException;
1.36 + /**
1.37 + * Register a new listener who wants to be notified of changes in the data.
1.38 + * The listener has to implement the IToUser interface.
1.39 + *
1.40 + * @param listener
1.41 + * New listener to be registered.
1.42 + * @return false on success, true otherwise.
1.43 + */
1.44 + public boolean addDataChangeListener(IToUser listener)
1.45 + throws RemoteException;
1.46
1.47 - /**
1.48 - * @return an iterator referencing the current "hot spot" in the
1.49 - * calculation, i.e. the active formula.
1.50 - */
1.51 - public ICalcIterator getActiveFormula() throws RemoteException;
1.52 + /**
1.53 + * @return an iterator referencing the current "hot spot" in the
1.54 + * calculation, i.e. the active formula.
1.55 + */
1.56 + public ICalcIterator getActiveFormula() throws RemoteException;
1.57
1.58 - /**
1.59 - * Makes the passed formula the active formula, i.e. the formula the next
1.60 - * tactic is applied to.
1.61 - *
1.62 - * @param newActiveFormula
1.63 - * Iterator referencing the new desired position
1.64 - */
1.65 - public void moveActiveFormula(ICalcIterator newActiveFormula)
1.66 - throws RemoteException;
1.67 + /**
1.68 + * Makes the passed formula the active formula, i.e. the formula the next
1.69 + * tactic is applied to.
1.70 + *
1.71 + * @param newActiveFormula
1.72 + * Iterator referencing the new desired position
1.73 + */
1.74 + public void moveActiveFormula(ICalcIterator newActiveFormula)
1.75 + throws RemoteException;
1.76
1.77 -// /**
1.78 -// * Start the a calculation by providing initial values to the Dialog On
1.79 -// * success, the Dialog is in DIALOGPHASE_SOLVE
1.80 -// *
1.81 -// * @param user_id
1.82 -// * The user
1.83 -// * @param f
1.84 -// * Formalization from the example collection or null
1.85 -// * @param started_from
1.86 -// * STARTFROM_*
1.87 -// * @return @throws
1.88 -// * RemoteException
1.89 -// *
1.90 -// * @see isac.util.Formalization
1.91 -// */
1.92 -// public CalcTree startCalculation(int user_id, Formalization f,
1.93 -// int started_from/* , int requested_calchead_view */)
1.94 -// throws RemoteException;
1.95 + // /**
1.96 + // * Start the a calculation by providing initial values to the Dialog On
1.97 + // * success, the Dialog is in DIALOGPHASE_SOLVE
1.98 + // *
1.99 + // * @param user_id
1.100 + // * The user
1.101 + // * @param f
1.102 + // * Formalization from the example collection or null
1.103 + // * @param started_from
1.104 + // * STARTFROM_*
1.105 + // * @return @throws
1.106 + // * RemoteException
1.107 + // *
1.108 + // * @see isac.util.Formalization
1.109 + // */
1.110 + // public CalcTree startCalculation(int user_id, Formalization f,
1.111 + // int started_from/* , int requested_calchead_view */)
1.112 + // throws RemoteException;
1.113
1.114 -// /**
1.115 -// * Enter the solving phase of the calculation. StartSpecifying must be
1.116 -// * called first Only possible with a complete and correct calcHead
1.117 -// *
1.118 -// * @param calcHead
1.119 -// * CalcHead for this calculation
1.120 -// * @return CalcTree represents the calculation on the java side
1.121 -// */
1.122 -// public void startSolving(/* CalcHead calcHead */) throws Exception;
1.123 + // /**
1.124 + // * Enter the solving phase of the calculation. StartSpecifying must be
1.125 + // * called first Only possible with a complete and correct calcHead
1.126 + // *
1.127 + // * @param calcHead
1.128 + // * CalcHead for this calculation
1.129 + // * @return CalcTree represents the calculation on the java side
1.130 + // */
1.131 + // public void startSolving(/* CalcHead calcHead */) throws Exception;
1.132
1.133 - /**
1.134 - * Modify a given CalcHead The result is the same CalcHead with status flags
1.135 - * for each item
1.136 - *
1.137 - * @see CalcHead for possible status flags
1.138 - * @param calcHead
1.139 - * CalcHead to be modified
1.140 - * @return new CalcHead with a status for each item TODO: return int like
1.141 - * replaceFormula etc.
1.142 - */
1.143 - public void modifyCalcHead(CalcHead calcHead) throws RemoteException;
1.144 + /**
1.145 + * Modify a given CalcHead The result is the same CalcHead with status flags
1.146 + * for each item
1.147 + *
1.148 + * @see CalcHead for possible status flags
1.149 + * @param calcHead
1.150 + * CalcHead to be modified
1.151 + * @return new CalcHead with a status for each item TODO: return int like
1.152 + * replaceFormula etc.
1.153 + */
1.154 + public void modifyCalcHead(CalcHead calcHead) throws RemoteException;
1.155
1.156 - /**
1.157 - * Complete a given calcHead: Tell the Kernel to fill out all the missing
1.158 - * fields in the calcHead
1.159 - *
1.160 - * @param calcHead
1.161 - * the calcHead to be completed TODO: return int like
1.162 - * replaceFormula etc.
1.163 - */
1.164 - public void completeCalcHead() throws RemoteException;
1.165 + /**
1.166 + * Complete a given calcHead: Tell the Kernel to fill out all the missing
1.167 + * fields in the calcHead
1.168 + *
1.169 + * @param calcHead
1.170 + * the calcHead to be completed TODO: return int like
1.171 + * replaceFormula etc.
1.172 + */
1.173 + public void completeCalcHead() throws RemoteException;
1.174
1.175 - /**
1.176 - * Complete a given calcHead: Tell the Kernel to fill out a missing field
1.177 - * in the calcHead, which is specified by an parameter
1.178 - *
1.179 - * @param calcHead
1.180 - * the calcHead to be completed
1.181 - * @param completeItem
1.182 - * the item which should be added TODO: return int like
1.183 - * replaceFormula etc.
1.184 - *
1.185 - * WN040916 don't confuse with autCalculate(...CompleteCalcHead)
1.186 - * WN0504 this case is notyet designed: how indicate the field ???
1.187 - */
1.188 - public void completeCalcHead(CalcHead calcHead, int completeItem)
1.189 - throws RemoteException;
1.190 + /**
1.191 + * Complete a given calcHead: Tell the Kernel to fill out a missing field in
1.192 + * the calcHead, which is specified by an parameter
1.193 + *
1.194 + * @param calcHead
1.195 + * the calcHead to be completed
1.196 + * @param completeItem
1.197 + * the item which should be added TODO: return int like
1.198 + * replaceFormula etc.
1.199 + *
1.200 + * WN040916 don't confuse with autCalculate(...CompleteCalcHead) WN0504 this
1.201 + * case is notyet designed: how indicate the field ???
1.202 + */
1.203 + public void completeCalcHead(CalcHead calcHead, int completeItem)
1.204 + throws RemoteException;
1.205
1.206 - /**
1.207 - * Tries to replaces the active formula in the calculation tree by the
1.208 - * passed formula. This could fail if no valid derivation from the preceding
1.209 - * formula to the (new) active formula can be found.
1.210 - * <p>
1.211 - * Parts of the calculation after the replaced formula are likely to become
1.212 - * invalid, listeners will be informed of this with the update message,
1.213 - * which contains the last unchanged formula.
1.214 - *
1.215 - * @param newFormula
1.216 - * @return The method will return 0 on success or a nonzero value indicating
1.217 - * the status otherwise.
1.218 - */
1.219 - public int replaceFormula(CalcFormula newFormula) throws RemoteException;
1.220 + /**
1.221 + * Tries to replaces the active formula in the calculation tree by the
1.222 + * passed formula. This could fail if no valid derivation from the preceding
1.223 + * formula to the (new) active formula can be found.
1.224 + * <p>
1.225 + * Parts of the calculation after the replaced formula are likely to become
1.226 + * invalid, listeners will be informed of this with the update message,
1.227 + * which contains the last unchanged formula.
1.228 + *
1.229 + * @param newFormula
1.230 + * @return The method will return 0 on success or a nonzero value indicating
1.231 + * the status otherwise.
1.232 + */
1.233 + public int replaceFormula(CalcFormula newFormula) throws RemoteException;
1.234
1.235 - /**
1.236 - * Tries to append the passed formula after the active formula. This could
1.237 - * fail if no valid derivation from the preceding formula to the (new)
1.238 - * active formula can be found. The method will fail as well if the active
1.239 - * formula is not the last formula in the (sub)calculation. Parts of the
1.240 - * calculation might become invalid.
1.241 - *
1.242 - * @param newFormula
1.243 - * @return The method will return 0 on success or a nonzero value indicating
1.244 - * the status otherwise.
1.245 - */
1.246 - public int appendFormula(CalcFormula newFormula) throws RemoteException;
1.247 + /**
1.248 + * Tries to append the passed formula after the active formula. This could
1.249 + * fail if no valid derivation from the preceding formula to the (new)
1.250 + * active formula can be found. The method will fail as well if the active
1.251 + * formula is not the last formula in the (sub)calculation. Parts of the
1.252 + * calculation might become invalid.
1.253 + *
1.254 + * @param newFormula
1.255 + * @return The method will return 0 on success or a nonzero value indicating
1.256 + * the status otherwise.
1.257 + */
1.258 + public int appendFormula(CalcFormula newFormula) throws RemoteException;
1.259
1.260 - /**
1.261 - * requests the intermediate steps leading to the Formula at the Iterator
1.262 - * (i.e. these steps might be calculated by the math-engine)
1.263 - * @param Iterator
1.264 - *
1.265 - * @return transactionID also returned in the CalcChangedEvent
1.266 - */
1.267 - public int intermediateSteps(ICalcIterator ic) throws RemoteException;
1.268 + /**
1.269 + * requests the intermediate steps leading to the Formula at the Iterator
1.270 + * (i.e. these steps might be calculated by the math-engine)
1.271 + *
1.272 + * @param Iterator
1.273 + *
1.274 + * @return transactionID also returned in the CalcChangedEvent
1.275 + */
1.276 + public int intermediateSteps(ICalcIterator ic) throws RemoteException;
1.277
1.278 - /**
1.279 - * Set the tactic to be used in the next step of calculation.
1.280 - *
1.281 - * @param tactic
1.282 - * the Tactic to be used in the the next step
1.283 - * @return The return value indicates success, failure or probable success
1.284 - * at a later time.
1.285 - */
1.286 - public int setNextTactic(Tactic tactic) throws RemoteException;
1.287 + /**
1.288 + * Set the tactic to be used in the next step of calculation.
1.289 + *
1.290 + * @param tactic
1.291 + * the Tactic to be used in the the next step
1.292 + * @return The return value indicates success, failure or probable success
1.293 + * at a later time.
1.294 + */
1.295 + public int setNextTactic(Tactic tactic) throws RemoteException;
1.296
1.297 - /**
1.298 - * Retrieve the tactic proposed by the SML-Kernel for the next step in the
1.299 - * calculation.
1.300 - *
1.301 - * @return proposed tactic. Can be null, if the kernel does not know what to
1.302 - * do next, or if the end of the calculation is reached
1.303 - */
1.304 - public Tactic fetchProposedTactic() throws RemoteException;
1.305 + /**
1.306 + * Retrieve the tactic proposed by the SML-Kernel for the next step in the
1.307 + * calculation.
1.308 + *
1.309 + * @return proposed tactic. Can be null, if the kernel does not know what to
1.310 + * do next, or if the end of the calculation is reached
1.311 + */
1.312 + public Tactic fetchProposedTactic() throws RemoteException;
1.313
1.314 - /**
1.315 - * Fetch all tactics applicable to the current situation known to the
1.316 - * system.
1.317 - *
1.318 - * @see #fetchApplicableTactics(int)
1.319 - */
1.320 - public static final int TACTICS_ALL = 1;
1.321 + /**
1.322 + * Fetch all tactics applicable to the current situation known to the
1.323 + * system.
1.324 + *
1.325 + * @see #fetchApplicableTactics(int)
1.326 + */
1.327 + public static final int TACTICS_ALL = 1;
1.328
1.329 - /**
1.330 - * Fetch all tactics applicable to the current situation, but restrict the
1.331 - * result to tactics from the current theory.
1.332 - *
1.333 - * @see #fetchApplicableTactics(int)
1.334 - */
1.335 - public static final int TACTICS_CURRENT_THEORY = 2;
1.336 + /**
1.337 + * Fetch all tactics applicable to the current situation, but restrict the
1.338 + * result to tactics from the current theory.
1.339 + *
1.340 + * @see #fetchApplicableTactics(int)
1.341 + */
1.342 + public static final int TACTICS_CURRENT_THEORY = 2;
1.343
1.344 - /**
1.345 - * Fetch all tactics applicable to the current situation, but restrict the
1.346 - * result to tactics from the method being applied.
1.347 - *
1.348 - * @see #fetchApplicableTactics(int)
1.349 - */
1.350 - public static final int TACTICS_CURRENT_METHOD = 3;
1.351 + /**
1.352 + * Fetch all tactics applicable to the current situation, but restrict the
1.353 + * result to tactics from the method being applied.
1.354 + *
1.355 + * @see #fetchApplicableTactics(int)
1.356 + */
1.357 + public static final int TACTICS_CURRENT_METHOD = 3;
1.358
1.359 -// /**
1.360 -// * Get a list of tactics applicable to the active formula.
1.361 -// *
1.362 -// * @param scope
1.363 -// * The filter parameter selects the scope of search for
1.364 -// * applicable tactics.
1.365 -// * @return Array with applicable tactics
1.366 -// * @see #TACTICS_ALL
1.367 -// * @see #TACTICS_CURRENT_THEORY
1.368 -// * @see #TACTICS_CURRENT_METHOD
1.369 -// */
1.370 -// public Tactic[] fetchApplicableTactics(int scope) throws RemoteException;
1.371 + // /**
1.372 + // * Get a list of tactics applicable to the active formula.
1.373 + // *
1.374 + // * @param scope
1.375 + // * The filter parameter selects the scope of search for
1.376 + // * applicable tactics.
1.377 + // * @return Array with applicable tactics
1.378 + // * @see #TACTICS_ALL
1.379 + // * @see #TACTICS_CURRENT_THEORY
1.380 + // * @see #TACTICS_CURRENT_METHOD
1.381 + // */
1.382 + // public Tactic[] fetchApplicableTactics(int scope) throws RemoteException;
1.383
1.384 - /**
1.385 - * Do the number of steps requested, without any restrictions. autoCalculate
1.386 - * ... CompleteCalc Do NOT change the value of this constant, as this number
1.387 - * has a specifig meaning in other parts of the system!
1.388 - *
1.389 - * @see #autoCalculate(int, int)
1.390 - */
1.391 - public static final int SCOPE_CALCULATION = 6;
1.392 + /**
1.393 + * Do the number of steps requested, without any restrictions. autoCalculate
1.394 + * ... CompleteCalc Do NOT change the value of this constant, as this number
1.395 + * has a specifig meaning in other parts of the system!
1.396 + *
1.397 + * @see #autoCalculate(int, int)
1.398 + */
1.399 + public static final int SCOPE_CALCULATION = 6;
1.400
1.401 - /**
1.402 - * Do the number of steps requested, but do not leave the current
1.403 - * subcalculation into a subproblem: CompleteToSubpbl Do NOT change the
1.404 - * value of this constant, as this number has a specifig meaning in other
1.405 - * parts of the system!
1.406 - *
1.407 - * @see #autoCalculate(int, int)
1.408 - */
1.409 - public static final int SCOPE_SUBCALCULATION = 5;
1.410 + /**
1.411 + * Do the number of steps requested, but do not leave the current
1.412 + * subcalculation into a subproblem: CompleteToSubpbl Do NOT change the
1.413 + * value of this constant, as this number has a specifig meaning in other
1.414 + * parts of the system!
1.415 + *
1.416 + * @see #autoCalculate(int, int)
1.417 + */
1.418 + public static final int SCOPE_SUBCALCULATION = 5;
1.419
1.420 - /**
1.421 - * Do the number of steps requested, but do not leave the current
1.422 - * subproblem: autoCalculate ... CompleteSubpbl Do NOT change the value of
1.423 - * this constant, as this number has a specifig meaning in other parts of
1.424 - * the system!
1.425 - *
1.426 - * @see #autoCalculate(int, int)
1.427 - */
1.428 - public static final int SCOPE_SUBPROBLEM = 4;
1.429 + /**
1.430 + * Do the number of steps requested, but do not leave the current
1.431 + * subproblem: autoCalculate ... CompleteSubpbl Do NOT change the value of
1.432 + * this constant, as this number has a specifig meaning in other parts of
1.433 + * the system!
1.434 + *
1.435 + * @see #autoCalculate(int, int)
1.436 + */
1.437 + public static final int SCOPE_SUBPROBLEM = 4;
1.438
1.439 - /**
1.440 - * Calculate the next n steps starting from the active formula or until the
1.441 - * specified scope is left, whichever comes first.
1.442 - *
1.443 - * @param scope
1.444 - * The scope parameter can have following values:
1.445 - * @param nSteps
1.446 - * Specifies the count of steps to be autocalculated. Passing 0
1.447 - * for nSteps will calculate until reaching a final result.
1.448 - * @return The method returns an unique id to identify the request when
1.449 - * notifying about updates in the tree.
1.450 - * @see #SCOPE_CALCULATION
1.451 - * @see #SCOPE_SUBCALCULATION
1.452 - * @see #SCOPE_SUBPROBLEM
1.453 - */
1.454 - /*
1.455 - * WN040624: the above design is desirable, but currently not impl., rather:
1.456 - * either steps == 0, then regard SCOPE_* or steps != 0, then SCOPE_*
1.457 - * irrelevant !
1.458 - */
1.459 - public int autoCalculate(int scope, int nSteps) throws RemoteException;
1.460 + /**
1.461 + * Calculate the next n steps starting from the active formula or until the
1.462 + * specified scope is left, whichever comes first.
1.463 + *
1.464 + * @param scope
1.465 + * The scope parameter can have following values:
1.466 + * @param nSteps
1.467 + * Specifies the count of steps to be autocalculated. Passing 0
1.468 + * for nSteps will calculate until reaching a final result.
1.469 + * @return The method returns an unique id to identify the request when
1.470 + * notifying about updates in the tree.
1.471 + * @see #SCOPE_CALCULATION
1.472 + * @see #SCOPE_SUBCALCULATION
1.473 + * @see #SCOPE_SUBPROBLEM
1.474 + */
1.475 + /*
1.476 + * WN040624: the above design is desirable, but currently not impl., rather:
1.477 + * either steps == 0, then regard SCOPE_* or steps != 0, then SCOPE_*
1.478 + * irrelevant !
1.479 + */
1.480 + public int autoCalculate(int scope, int nSteps) throws RemoteException;
1.481
1.482 - /**
1.483 - * get the Formulae and CalcHeads of the calcTree between the two iterators
1.484 - * (including the elements the two iterators a pointing to)
1.485 - *
1.486 - * @param iterator_from
1.487 - * The iterator pointing to the element immediately before of the
1.488 - * returned range (which supports direct use of ...
1.489 - * @see isac.util.CalcChangedEvent.last_unchanged_formula_
1.490 - * @param iterator_to
1.491 - * The iterator pointing at the last element of the returned
1.492 - * range
1.493 - * @param level
1.494 - * The maximum level of the elements in the range, element with a
1.495 - * higher level (who are "deeper" in the hierarchie are not
1.496 - * returned null if everything should be displayed
1.497 - * @param result_includes_tactics
1.498 - * true if the result should include the tactics, false otherwise
1.499 - *
1.500 - * @return an Vector containing the Formulae and CalcHeads of the calcTree
1.501 - * @author Alois Kirchsteiger 12.01.2005 16:51:43
1.502 - */
1.503 - public Vector getElementsFromTo(ICalcIterator iterator_from,
1.504 - ICalcIterator iterator_to, Integer level,
1.505 - boolean result_includes_tactics) throws RemoteException;
1.506 + /**
1.507 + * get the Formulae and CalcHeads of the calcTree between the two iterators
1.508 + * (including the elements the two iterators a pointing to)
1.509 + *
1.510 + * @param iterator_from
1.511 + * The iterator pointing to the element immediately before of the
1.512 + * returned range (which supports direct use of ...
1.513 + * @see isac.util.CalcChangedEvent.last_unchanged_formula_
1.514 + * @param iterator_to
1.515 + * The iterator pointing at the last element of the returned
1.516 + * range
1.517 + * @param level
1.518 + * The maximum level of the elements in the range, element with a
1.519 + * higher level (who are "deeper" in the hierarchie are not
1.520 + * returned null if everything should be displayed
1.521 + * @param result_includes_tactics
1.522 + * true if the result should include the tactics, false otherwise
1.523 + *
1.524 + * @return an Vector containing the Formulae and CalcHeads of the calcTree
1.525 + * @author Alois Kirchsteiger 12.01.2005 16:51:43
1.526 + */
1.527 + public Vector getElementsFromTo(ICalcIterator iterator_from,
1.528 + ICalcIterator iterator_to, Integer level,
1.529 + boolean result_includes_tactics) throws RemoteException;
1.530
1.531 }
1.532 \ No newline at end of file