com/intendico/gorite/Context.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 import com.intendico.data.Condition;
  25
  26 /**
  27  * The Context interface is implemented by a plan (i.e. top level
  28  * goal) that has different variants for different contexts. The
  29  * different contexts are defined by means of a {@link Query} that
  30  * provides multiple bindings, and each binding defines a variant
  31  * execution of the plan.
  32  * @see Plan
  33  * @see BDIGoal
  34  */
  35
  36 public interface Context {
  37
  38     /**
  39      * A constant that a {@link #context} method may return when a
  40      * plan doesn't have any applicable variants. Returning this
  41      * {@link Query}, which is eternally false, has the same effect as
  42      * throwing a {@link None} exception in marking that the plan does
  43      * not have any applicable variants.  The point is that a null
  44      * return from the {@link #context} method means that there is no
  45      * context query, and that the goal with this context is
  46      * applicable once.
  47      */
  48     public static final Query EMPTY = new Condition() {
  49             public boolean condition() {
  50                 return false;
  51             }
  52         };
  53
  54     /**
  55      * A constant that a {@link #context} method may return when a
  56      * plan has a single applicable variant without bindings to {@link
  57      * Ref} objects. Returning this {@link Query}, which in fact is
  58      * null, has the same effect as returning null in marking that the
  59      * plan has a single applicable variant.  The point is that a null
  60      * return from the {@link #context} method means that there is no
  61      * context query, and therefore the plan with this context is
  62      * applicable.
  63      */
  64     public static final Query TRUE = null;
  65
  66     /**
  67      * A constant that a {@link #context} method may return when a
  68      * plan doesn't have any applicable variants. This is merely an
  69      * alias for {@link #EMPTY} added for convenience.
  70      */
  71     public static final Query FALSE = EMPTY;
  72
  73     /**
  74      * An exception that a {@link #context} method may throw in
  75      * order to mark that there is no applicable context.
  76      * @see #EMPTY
  77      */
  78     public static class None extends Exception {
  79
  80         /**
  81          * A default constructor.
  82          */
  83         public None() {
  84             super( "no applicable context" );
  85         }
  86
  87         /**
  88          * Version identity required for serialization.
  89          */
  90         public static final long serialVersionUID = 1L;
  91     }
  92
  93     /**
  94      * The context method returns the {@link Query} that defines the
  95      * multiple alternative contexts for the execution.  The {@link
  96      * #context} method is invoked for defining the {@link Query}. The
  97      * method may return null, which means that the plan has a single
  98      * applicable variant, or it may return {@link #EMPTY} or throw
  99      * the {@link None} excpetion, which both indicate that the plan
 100      * does not have any applicable variant (right now). Any other
 101      * query is taken as defining the alternative applicable contexts.
 102      * @see BDIGoal.BDIInstance#contextual
 103      */
 104     public Query context(Data d) throws Exception;
 105
 106
 107 }