1 /*********************************************************************
2 Copyright 2012, Ralph Ronnquist.
4 This file is part of GORITE.
6 GORITE is free software: you can redistribute it and/or modify it
7 under the terms of the Lesser GNU General Public License as published
8 by the Free Software Foundation, either version 3 of the License, or
9 (at your option) any later version.
11 GORITE is distributed in the hope that it will be useful, but WITHOUT
12 ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public
14 License for more details.
16 You should have received a copy of the Lesser GNU General Public
17 License along with GORITE. If not, see <http://www.gnu.org/licenses/>.
18 **********************************************************************/
20 package com.intendico.gorite;
22 import com.intendico.data.Query;
23 import com.intendico.data.Ref;
25 import java.util.HashSet;
26 import java.util.Iterator;
27 import java.util.Vector;
30 * An EndGoal is achieved by means of achieving its sub goals in
31 * sequence, and it will then cause an enclosing {@link LoopGoal} goal
32 * to be achieved. If any sub goal fails, the EndGoal will just
33 * succeed without causing the enclosing {@link LoopGoal} to
34 * succeed. An EndGoal never fails; either it succeeds or it causes
35 * the enclosing {@link LoopGoal} to succeed.
37 * The usage pattern for {@link LoopGoal} and EndGoal is as follows:
40 * new LoopGoal( "loop", new Goal [] {
41 * .. // steps in the loop
42 * .. new EndGoal( "break if", new Goal [] {
43 * // optional sub goals for ending the loop if they succeed
45 * .. // more steps in the loop
49 * <p> There may be any number of {@link EndGoal} to end the loop
50 * although of course only one will take effect. The {@link EndGoal}
51 * may be at any level within the LoopGoal goal hierarchy, except
52 * nested within another LoopGoal.
54 * <p> The EndLoop effect may be thought of as throwing an {@link
55 * Exception} that the nearest enclosing {@link LoopGoal} catches,
56 * interrupting the progress of any intermediate composite goal,
57 * including {@link ParallelGoal} and {@link RepeatGoal}. Ongoing
58 * branches of intermediate parallel goals will be cancelled.
60 * <p> The EndLoop effect does not propagate up through a {@link
61 * BDIGoal} execution of a {@link Plan} with non-null {@link
62 * Context#context(Data)} {@link Query}. I.e., the EndGoal must
63 * typically be explicitely within the sub goal hierarchy of the
64 * {@link LoopGoal} of concern.
66 * <p> However, the EndGoal effect does propagate up through a {@link
67 * BDIGoal} execution if the {@link Plan} has a null {@link
68 * Context#context(Data)}, or is an implementing {@link Goal}
69 * hierarchy without {@link Context}.
76 public class EndGoal extends SequenceGoal {
81 public EndGoal(String n,Goal [] sg) {
86 * Convenience constructor without sub goals.
88 public EndGoal(String n) {
93 * Creates and returns an instance object for achieving
96 public Instance instantiate(String head,Data d) {
97 return new EndInstance( head );
101 * Implements a loop-end action ("break")
103 public class EndInstance extends SequenceInstance {
108 public EndInstance(String h) {
113 * Process all subgoals in sequence, then throw a
114 * LoopEndException if success. If subgoals fail, then succeed
115 * without throwing exception.
117 public States action(String head,Data d)
118 throws LoopEndException, ParallelEndException {
119 States s = super.action( head, d );
120 if ( s == States.PASSED )
121 throw new LoopEndException( head );
122 if ( s == States.FAILED )
123 return States.PASSED;