com/intendico/gorite/DataGoal.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 /**
  23  * A DataGoal is a goal that uses the value of the data element named
  24  * by the control attribute as the actual goal to achieve.  This value
  25  * is accessed and considered whenever the DataGoal is instantiated
  26  * (via {@link #instantiate(String,Data)}), where it either is a
  27  * {@link Goal}, a {@link Goal.Instance}, or some other non-null
  28  * object.
  29  * <ul>
  30  *
  31  * <li> If the value is null, the DataGoal will instantiate as a
  32  * FailGoal, and thus fail when executed.
  33  *
  34  * <li> A Goal is instantiated and executed in lieu of the DataGoal,
  35  * and likewise for a Goal.Instance, which is used as given and
  36  * executed in lieu of the DataGoal.
  37  *
  38  * Note that a Goal.Instance execution may then a different Data
  39  * object than for the DataGoal instantiation, and if so, there is no
  40  * support for data transfer between the Data objects. Further, the
  41  * Goal.Instance execution progresses from whatever execution state it
  42  * has.
  43  *
  44  * <li> For any other type of object, the DataGoal creates a vacuous
  45  * BDIGoal for the object, and that BDIGoal is instantiated and
  46  * executed in lieu of the DataGoal.
  47  * </ul>
  48  *
  49  * <p> Except for Goal.Instance values (which are already
  50  * instantiated), the DataGoal goal adds the suffix "[xx]", where xx
  51  * is the control data name, to the intention head, as its marker in
  52  * an execution trace output.
  53  */
  54 public class DataGoal extends Goal {
  55
  56     /**
  57      * Constructor with goal name and control data name.
  58      */
  59     public DataGoal(String n,String c) {
  60         super( n );
  61         setGoalControl( c );
  62     }
  63
  64     /**
  65      * Overrides the base class method {@link Goal#instantiate} to
  66      * provide the instance for the data goal.
  67      */
  68     public Instance instantiate(String h,Data d) {
  69         Object g = d.getValue( getGoalControl() );
  70         if ( g instanceof Instance ) {
  71             return (Instance) g;
  72         }
  73         String hh = h + "[" + getGoalControl() + "]";
  74         if ( g instanceof Goal ) {
  75             return ((Goal) g).instantiate( hh, d );
  76         }
  77         if ( g != null ) {
  78             return new BDIGoal( g ).instantiate( hh, d );
  79         }
  80         return new FailGoal( "Data getGoalControl() is null" ).
  81             instantiate( hh, d );
  82     }
  83 }