com/intendico/gorite/ControlGoal.java

   1 /*********************************************************************
   2 Copyright 2012, Ralph Ronnquist.
   3
   4 This file is part of GORITE.
   5
   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.
  10
  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.
  15
  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 **********************************************************************/
  19
  20 package com.intendico.gorite;
  21
  22 import com.intendico.data.Query;
  23 import com.intendico.data.Ref;
  24
  25 import java.util.HashSet;
  26 import java.util.Iterator;
  27 import java.util.Vector;
  28
  29 /**
  30  * A ControlGoal is achieved by performing all its sub goals in
  31  * sequence, which results in a control effect on an enclosing
  32  * parallel execution by terminating all other branches when it
  33  * succeeds. Thus, the execution either fails, or continues after the
  34  * enclosing parallel goal.
  35  *
  36  * <p> The following code snippet illustrates an optional interrupt,
  37  * i.e., how to either interrupt or succeed (rather than either
  38  * interrupt or fail).
  39  * <pre>
  40  * new FailGoal( "not interrupting is fine", new Goal [] {
  41  *     new ControlGoal( "maybe interrupt", new Goal {
  42  *        // Goal sequence for causing interrupt if achieved successfully
  43  *     } );
  44  * }
  45  * </pre>
  46  *
  47  * <p> Note that the ControlGoal effect propagates up to the nearest
  48  * parallel type goal through {@link BDIGoal} execution, and it
  49  * therefore is not necessary for the ControlGoal to be explicitly
  50  * within the sub goal hiearachy of the parallel type goal of
  51  * concern.
  52  *
  53  * <p> In particular, a {@link Plan} of a {@link Team.Role} may
  54  * include a ControlGoal to express that a {@link TeamGoal} is
  55  * achieved by any one filler rather than requiring all of them.
  56  *
  57  * @see ParallelGoal
  58  * @see RepeatGoal
  59  * @see TeamGoal
  60  * @see FailGoal
  61  * @see Team.Role
  62  */
  63 public class ControlGoal extends SequenceGoal {
  64
  65     /**
  66      * Constructor.
  67      */
  68     public ControlGoal(String n,Goal [] sg) {
  69         super( n, sg );
  70     }
  71
  72     /**
  73      * Convenience constructor without sub goals.
  74      */
  75     public ControlGoal(String n) {
  76         this( n, null );
  77     }
  78
  79     /**
  80      * Creates and returns an instance object for achieving
  81      * a ControlGoal.
  82      */
  83     public Instance instantiate(String head,Data d) {
  84         return new ControlInstance( head );
  85     }
  86
  87     /**
  88      * Implements a control action for parallel execution.
  89      */
  90     public class ControlInstance extends SequenceInstance {
  91
  92         /**
  93          * Constructor.
  94          */
  95         public ControlInstance(String h) {
  96             super( h );
  97         }
  98
  99         /**
 100          * Process all subgoals in sequence, then throw a
 101          * LoopEndException if success. If a subgoals fail, then fail
 102          * without throwing exception.
 103          */
 104         public States action(String head,Data d)
 105             throws LoopEndException, ParallelEndException {
 106             States s = super.action( head, d );
 107             if ( s == States.PASSED ) {
 108                 throw new ParallelEndException( head );
 109             }
 110             return s;
 111         }
 112     }
 113
 114
 115 }