JACK 5.4 Application Interface

aos.jack.jak.cursor
Class Cursor

java.lang.Object
  extended byaos.jack.jak.util.Watchable
      extended byaos.jack.jak.cursor.Cursor
All Implemented Interfaces:
ObservableInt
Direct Known Subclasses:
Again, ArrayCursor, BeliefSetCursor, Change, EnumerationCursor, FalseCursor, GateCursor, ObserverCursor, TimeCursor, TimeGateCursor, TrueOnceCursor

public abstract class Cursor
extends Watchable

The Cursor class is the underlying implementation for returning values from queries of any type.


Field Summary
static BeliefState FALSE
          Represents a false value.
static Cursor falseCursor
          Utility instance for queries that return false always.
static BeliefState TRUE
          Represents a true value.
static Cursor trueCursor
          Utility instance for queries that return true always.
static BeliefState UNKNOWN
          Represents an unknown value.
 
Constructor Summary
Cursor()
           
 
Method Summary
 void finished()
          This informs the cursor that it is not going to be used again.
 boolean isTriggered()
          Used by JACK to determine if the cursor provides triggering.
 Cursor negate()
          This is called to negate the value of the cursor.
abstract  boolean next()
          This method is called to provide a next binding by this cursor.
 void register(java.util.Observer o)
           
 Cursor reset(aos.jack.jak.core.Generator g, int index)
          Resets the cursor.
 void undo()
          Undo tells the cursor to backtrack anything it has done.
 boolean unRegister(java.util.Observer o)
           
 
Methods inherited from class aos.jack.jak.util.Watchable
addObserver, countObservers, deleteObserver, deleteObservers, hasChanged, notifyObservers, notifyObservers
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

TRUE

public static final BeliefState TRUE
Represents a true value.


FALSE

public static final BeliefState FALSE
Represents a false value.


UNKNOWN

public static final BeliefState UNKNOWN
Represents an unknown value.


trueCursor

public static final Cursor trueCursor
Utility instance for queries that return true always.


falseCursor

public static final Cursor falseCursor
Utility instance for queries that return false always.

Constructor Detail

Cursor

public Cursor()
Method Detail

next

public abstract boolean next()
This method is called to provide a next binding by this cursor. The first call provides the first binding, and successive calls provide successive bindings, until the binding alternatives are exhausted. The method returns true when it provides a binding, and false when it cannot provide a new alternative binding. Expected behaviour is that cursors will return while there are more bindings and from then on false until a call to reset(). This is very important especially when you consider an expression such as:
     db.query($x) && isWhatIWant($x) && db1.query($x, $y)
 
If the isWhatIWant() cursor simply tests its input and returns true for appropriate values then this expression would not work as expected and may go into an infinite loop.
For example if the beliefset had:
                db(1)
                db(2)
                db(3)

                db1(3,3)
 
and isWhatIWant() returned true on odd numbers. Then the correct behaviour would be one result with $x=3 $y=3. However if isWhatIWant.next() always returns true on odd numbers then: $x is bound to 1,
isWhatIWant(1).next() is true
db1(1, $y) fails, backtracks
isWhatIWant(1).next() is true
db1(1, $y) fails, backtracks
etc...


reset

public Cursor reset(aos.jack.jak.core.Generator g,
                    int index)
Resets the cursor. This is normally done by either undoing the last action or finishing the current cursor and returning a new one.

Parameters:
g - The generator that generates an equivalent cursor
index - The index of the equivalent cursor in the generator.
Returns:
The reset cursor, or an equivalent one.

negate

public Cursor negate()
This is called to negate the value of the cursor. By default it simply stores the fact that it has been negated. Some cursors may do more such as create a new cursor for the negated query. After the call the original cursor is lost so unless this call returns the old cursor, it will be discarded.


undo

public void undo()
Undo tells the cursor to backtrack anything it has done. It is a subset of the reset() functionality since it does not reinitialize the cursor. The only requirement is that any bindings made by the cursor are undone. The state of the cursor after the call is undefined. Most implementations will fail if next() is called after undo() without an intervening call to reset().


finished

public void finished()
This informs the cursor that it is not going to be used again. This is typically used to clean up data strutures and to remove itself from any notification paths.


isTriggered

public boolean isTriggered()
Used by JACK to determine if the cursor provides triggering. It is used by JACK to flag errors if an attempt is made to wait for or maintain a cursor that does not provide triggering.


register

public void register(java.util.Observer o)

unRegister

public boolean unRegister(java.util.Observer o)

JACK 5.4 Application Interface

Copyright (C) 1999-2008, Agent Oriented Software Pty. Ltd.

US Government Restricted Rights
The JACK Modules and relevant Software Material have been developed entirely at private expense and are accordingly provided with RESTRICTED RIGHTS. Use, duplication, or disclosure by Government is subject to restrictions as set forth in subparagraph (c)(1)(ii) of DFARS 252.227-7013 or subparagraph (c)(1) and (2) of the Commercial Computer Software Restricted Rights and 48 CFR 52.2270-19, as applicable.


Agent Oriented Software Pty. Ltd.     http://www.aosgrp.com
PO Box 639, Carlton South, Victoria 3053, Australia
Phone: +61 3 9349 5055, Fax: +61 3 9349 5088