* A Goal embodies both an action and the precursors for that
* action. A Goal's precursors will be satisfied before
* attempting to perform the target Goal's action. There may be
* a case that once precursors have been satisfied there is no further action
* required to be perform for a particular Goal.
*
* A Goal's postcursors are also tracked so that if a
* Goal's state has been changed and the Goals
* ahead of it in the hierarchy need to be notified, it can
* percolate forward and have it's postcursors satisfied.
*
Goal array. */
public static final Goal[] EMPTY_ARRAY = new Goal[0];
// ------------------------------------------------------------
// Class members
// ------------------------------------------------------------
/** Unique name. */
private String name;
/** Ordered list of precursor Goals. */
private List precursors;
/** Ordered list of postcursor Goals. */
private List postcursors;
/** Action to perform. */
private Action action;
/** Pre-goal callbacks. */
private List preGoalCallbacks;
/** Post-goal callbacks. */
private List postGoalCallbacks;
/** Pre-action callbacks. */
private List preActionCallbacks;
/** Post-action callbacks. */
private List postActionCallbacks;
/** Description of the goal (for auto-documenting). */
private String description;
// ------------------------------------------------------------
// Constructors
// ------------------------------------------------------------
/**
* Construct a new Goal with the specified name.
*
* @param name
* The name of the Goal.
*/
public Goal(String name) {
this.name = name;
this.precursors = Collections.EMPTY_LIST;
this.postcursors = Collections.EMPTY_LIST;
this.preGoalCallbacks = Collections.EMPTY_LIST;
this.postGoalCallbacks = Collections.EMPTY_LIST;
this.preActionCallbacks = Collections.EMPTY_LIST;
this.postActionCallbacks = Collections.EMPTY_LIST;
}
/**
* Construct a new Goal with the specified name and
* Action.
*
* @param name
* The name of the Goal.
* @param action
* The Action for this Goal.
*/
public Goal(String name, Action action) {
this(name);
setAction(action);
}
// ------------------------------------------------------------
// Instance methods
// ------------------------------------------------------------
/**
* Retrieve the name of this Goal.
*
* @return This Goal's name.
*/
public String getName() {
return this.name;
}
/**
* Retrieve the description of this Goal.
*
* @return The description of this goal.
*/
public String getDescription() {
return this.description;
}
/**
* Set the description for this Goal.
*
* @param description
* The description of this goal.
*/
public void setDescription(String description) {
this.description = description;
}
/**
* Retrieve the Action of this Goal.
*
* @return The Action of this Goal.
*/
public Action getAction() {
return this.action;
}
/**
* Set the Action of this Goal.
*
* @param action
* The Action of this Goal.
*/
public void setAction(Action action) {
this.action = action;
}
// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
// PRE GOAL
// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
/**
* Add a pre-goal callback to this Goal.
*
* @param callback
* The callback to add.
*/
public void addPreGoalCallback(PreGoalCallback callback) {
if (Collections.EMPTY_LIST.equals(this.preGoalCallbacks)) {
this.preGoalCallbacks = new ArrayList(3);
}
this.preGoalCallbacks.add(callback);
}
/**
* Remove all occurences of a pre-goal callback from this
* Goal.
*
* @param callback
* The callback to remove.
*/
public void removePreGoalCallback(PreGoalCallback callback) {
while (this.preGoalCallbacks.remove(callback)) {
// intentionally left blank;
}
}
/**
* Retrieve an unmodifiable list of the pre-goal callbacks.
*
* @return An unmodifiable List of
* PreGoalCallbacks.
*/
public List getPreGoalCallbacks() {
return Collections.unmodifiableList(this.preGoalCallbacks);
}
// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
// POST GOAL
// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
/**
* Add a post-goal callback to this Goal.
*
* @param callback
* The callback to add.
*/
public void addPostGoalCallback(PostGoalCallback callback) {
if (Collections.EMPTY_LIST.equals(this.postGoalCallbacks)) {
this.postGoalCallbacks = new ArrayList(3);
}
this.postGoalCallbacks.add(callback);
}
/**
* Remove all occurences of a post-goal callback from this
* Goal.
*
* @param callback
* The callback to remove.
*/
public void removePostGoalCallback(PostGoalCallback callback) {
while (this.postGoalCallbacks.remove(callback)) {
// intentionally left blank;
}
}
/**
* Retrieve an unmodifiable list of the post-goal callbacks.
*
* @return An unmodifiable List of
* PostGoalCallbacks.
*/
public List getPostGoalCallbacks() {
return Collections.unmodifiableList(this.postGoalCallbacks);
}
// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
// PRE ACTION
// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
/**
* Add a pre-action callback to this Goal.
*
* @param callback
* The callback to add.
*/
public void addPreActionCallback(PreActionCallback callback) {
if (this.preActionCallbacks.equals(Collections.EMPTY_LIST)) {
this.preActionCallbacks = new ArrayList(3);
}
this.preActionCallbacks.add(callback);
}
/**
* Remove all occurences of a pre-action callback from this
* Goal.
*
* @param callback
* The callback to remove.
*/
public void removePreActionCallback(PreActionCallback callback) {
while (this.preActionCallbacks.remove(callback)) {
// intentionally left blank;
}
}
/**
* Retrieve an unmodifiable list of the pre-action callbacks.
*
* @return An unmodifiable List of
* PreActionCallbacks.
*/
public List getPreActionCallbacks() {
return Collections.unmodifiableList(this.preActionCallbacks);
}
// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
// POST ACTION
// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
/**
* Add a post-action callback to this Goal.
*
* @param callback
* The callback to add.
*/
public void addPostActionCallback(PostActionCallback callback) {
if (this.postActionCallbacks.equals(Collections.EMPTY_LIST)) {
this.postActionCallbacks = new ArrayList(3);
}
this.postActionCallbacks.add(callback);
}
/**
* Remove all occurences of a post-action callback from this
* Goal.
*
* @param callback
* The callback to remove.
*/
public void removePostActionCallback(PostActionCallback callback) {
while (this.postActionCallbacks.remove(callback)) {
// intentionally left blank;
}
}
/**
* Retrieve an unmodifiable list of the post-action callbacks.
*
* @return An unmodifiable List of
* PostActionCallbacks.
*/
public List getPostActionCallbacks() {
return Collections.unmodifiableList(this.postActionCallbacks);
}
// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
/**
* Determine if this Goal has been satisfied for the
* specified Session.
*
* @param session
* The Session context in which to test for goal
* satisfaction.
*
* @return true if this Goal has been
* satisfied within the Session, otherwise
* false.
*/
public boolean isSatisfied(Session session) {
return session.isGoalSatisfied(this);
}
/**
* Add a precursor Goal to this Goal.
*
* @param precursor
* The precursor Goal that must be satisfied
* before performing this Goal.
*
* @throws CyclicGoalChainException
* if adding the precursor would result in a cyclic dependency.
*/
public void addPrecursor(Goal precursor) throws CyclicGoalChainException {
if (Collections.EMPTY_LIST.equals(this.precursors)) {
this.precursors = new ArrayList();
}
this.precursors.add(precursor);
try {
checkForCycles();
precursor.addInternalPostcursor(this);
} catch (CyclicGoalChainException e) {
e.fillInStackTrace();
this.precursors.remove(precursor);
throw e;
}
}
/**
* Add a postcursor Goal to this Goal.
*
* @param postcursor
* The postcursor Goal that depends on this
* Goal.
*
* @throws CyclicGoalChainException
* if adding the postcursor would result in a cyclic dependency.
*/
public void addPostcursor(Goal postcursor) throws CyclicGoalChainException {
postcursor.addPrecursor(this);
}
/**
* Adds a postcursor Goal without looping back to the
* postcursor.addPrecursor and entering an infinite loop.
*
* @param postcursor
* The postcursor Goal that is already tracking
* this Goal as a precursor and is letting this
* Goal know that it is a postcursor.
*/
private void addInternalPostcursor(Goal postcursor) {
if (Collections.EMPTY_LIST.equals(this.postcursors)) {
this.postcursors = new ArrayList();
}
this.postcursors.add(postcursor);
}
/**
* Retrieve an unmodifiable List of this Goal's
* precursor Goals.
*
* @return The List of precursor Goals.
*/
public List getPrecursors() {
return Collections.unmodifiableList(this.precursors);
}
/**
* Retrive an unmodifiable List of this Goal's
* postcursor Goals.
*
* @return The List of postcursor Goals.
*/
public List getPostcursors() {
return Collections.unmodifiableList(this.postcursors);
}
/**
* Attempt to attain this Goal's precursor Goals.
*
* @param session
* The context in which to attain goals.
*
* @throws UnattainableGoalException
* if unable to satisfy a precursor.
* @throws NoActionDefinitionException
* if this goal contains no action definition.
*/
void attainPrecursors(Session session) throws UnattainableGoalException,
NoActionDefinitionException {
Iterator precursorIter = getPrecursors().iterator();
Goal eachPrereq = null;
while (precursorIter.hasNext()) {
eachPrereq = (Goal) precursorIter.next();
eachPrereq.attain(session);
}
}
/**
* Attempt to attain this Goal's postcursor
* Goals.
*
* @param session
* The context in which to attain goals.
*
* @throws UnattainableGoalException
* if unable to satisfy a postcursor.
* @throws NoActionDefinitionException
* if this goal contains no action definition.
*/
void percolatePostcursors(Session session)
throws UnattainableGoalException, NoActionDefinitionException {
Iterator postreqIter = getPostcursors().iterator();
Goal eachPostreq = null;
while (postreqIter.hasNext()) {
eachPostreq = (Goal) postreqIter.next();
eachPostreq.percolate(session);
}
}
/**
* Perform a cyclic dependency check.
*
* @throws CyclicGoalChainException
* if a dependency cycle is discovered.
*/
void checkForCycles() throws CyclicGoalChainException {
Set visited = new HashSet();
checkForCyclesFast(this, visited);
}
/**
* Perform a cyclic dependency check.
*
* @param initialGoal
* The root Goal initiating the cycle check.
* @param visited
* The Set of all Goals visited
* between the root initialGoal and this
* Goal.
*
* @throws CyclicGoalChainException
* if a cyclic dependency is detected.
*/
void checkForCycles(Goal initialGoal, Set visited)
throws CyclicGoalChainException {
if (visited.contains(this)) {
throw new CyclicGoalChainException(initialGoal);
}
visited.add(this);
Iterator precursorIter = getPrecursors().iterator();
Goal eachPrereq = null;
while (precursorIter.hasNext()) {
eachPrereq = (Goal) precursorIter.next();
eachPrereq.checkForCycles(initialGoal, new HashSet(visited));
}
}
void checkForCyclesFast(Goal initialGoal, Set visited)
throws CyclicGoalChainException {
if (visited.contains(this)) {
throw new CyclicGoalChainException(initialGoal);
}
visited.add(this);
Iterator precursorIter = getPrecursors().iterator();
Goal eachPrereq = null;
while (precursorIter.hasNext()) {
eachPrereq = (Goal) precursorIter.next();
eachPrereq.checkForCyclesFast(initialGoal, visited);
visited.remove(eachPrereq);
}
}
/**
* Attempt to attain this Goal.
*
* @param session
* The context in which to attain goals.
*
* @throws UnattainableGoalException
* if unable to attain this Goal or one of its
* precursor Goals.
* @throws NoActionDefinitionException
* if this goal contains no action definition.
*/
public final void attain(Session session) throws UnattainableGoalException,
NoActionDefinitionException {
if (session.isGoalSatisfied(this)) {
// session.info( getName() + ":" );
// session.info( "" );
return;
}
// session.info( getName() + ": checking precursors." );
attainPrecursors(session);
fire(session);
}
/**
* Attempt to percolate this Goal through to its Postcursors.
*
* @param session
* The context in which to percolate goals.
*
* @throws UnattainableGoalException
* if unable to attain this Goal or one of its
* precursor Goals.
* @throws NoActionDefinitionException
* if this goal contains no action definition.
*/
public final void percolate(Session session)
throws UnattainableGoalException, NoActionDefinitionException {
if (session.isGoalSatisfied(this)) {
return;
}
fire(session);
percolatePostcursors(session);
}
/**
* Fires pre-goal callbacks, the Goal's action, if need be,
* and the post-goal callbacks.
*
* @param session
* The context in which to fire the goal.
*
* @throws UnattainableGoalException
* if unable to attain this Goal or one of its
* precursor Goals.
* @throws NoActionDefinitionException
* if this goal contains no action definition.
*/
private final void fire(Session session) throws UnattainableGoalException,
NoActionDefinitionException {
session.info(getName() + ":");
// log.info( "begin goal" );
try {
// session.info( getName() + ": firing pre-goal callbacks." );
firePreGoalCallbacks();
} catch (Exception e) {
throw new UnattainableGoalException(getName(), e);
}
Action action = getAction();
if (action == null) {
throw new NoActionDefinitionException(this);
}
if (action.requiresAction()) {
try {
// session.info( getName() + ": firing pre-action callbacks." );
// log.info( "begin action" );
firePreActionCallbacks();
// session.info( getName() + ": firing goal action." );
getAction().performAction(session);
// session.info( getName() + ": firing post-action callbacks."
// );
firePostActionCallbacks();
// log.info( "end action" );
} catch (Exception e) {
throw new UnattainableGoalException(getName(), e);
}
}
try {
// session.info( getName() + ": firing post-goal callbacks." );
firePostGoalCallbacks();
} catch (Exception e) {
throw new UnattainableGoalException(getName(), e);
}
// log.info( "end goal" );
// session.info( getName() + ": checking done." );
session.addSatisfiedGoal(this);
session.info("");
}
/**
* Fire the pre-goal callbacks.
*
* @throws Exception
* if an error occurs while firing a callback.
*/
void firePreGoalCallbacks() throws Exception {
Iterator callbackIter = this.preGoalCallbacks.iterator();
PreGoalCallback eachCallback = null;
if (!callbackIter.hasNext()) {
return;
}
// log.info( "begin pre-goal callbacks" );
while (callbackIter.hasNext()) {
eachCallback = (PreGoalCallback) callbackIter.next();
eachCallback.firePreGoal(this);
}
// log.info( "end pre-goal callbacks" );
}
/**
* Fire the post-goal callbacks.
*
* @throws Exception
* if an error occurs while firing a callback.
*/
void firePostGoalCallbacks() throws Exception {
Iterator callbackIter = this.postGoalCallbacks.iterator();
PostGoalCallback eachCallback = null;
while (callbackIter.hasNext()) {
eachCallback = (PostGoalCallback) callbackIter.next();
eachCallback.firePostGoal(this);
}
}
/**
* Fire the pre-action callbacks.
*
* @throws Exception
* if an error occurs while firing a callback.
*/
void firePreActionCallbacks() throws Exception {
Iterator callbackIter = this.preActionCallbacks.iterator();
PreActionCallback eachCallback = null;
while (callbackIter.hasNext()) {
eachCallback = (PreActionCallback) callbackIter.next();
eachCallback.firePreAction(this);
}
}
/**
* Fire the post-action callbacks.
*
* @throws Exception
* if an error occurs while firing a callback.
*/
void firePostActionCallbacks() throws Exception {
Iterator callbackIter = this.postActionCallbacks.iterator();
PostActionCallback eachCallback = null;
while (callbackIter.hasNext()) {
eachCallback = (PostActionCallback) callbackIter.next();
eachCallback.firePostAction(this);
}
}
// ------------------------------------------------------------
// java.lang.Object implementation
// ------------------------------------------------------------
/**
* Retrieve the hash-code of this object.
*
*
* The hash-code is derrived only from the name of the
* Goal as returned by {@link #getName}.
*
*
* @return The hash-code of this object.
*/
public int hashCode() {
return getName().hashCode();
}
/**
* Determine if two Goal objects are equivelant.
*
*
* Equivelancy is determined only from the names of the
* Goals as return by {@link #getName}.
*
*
* @param thatObj
* The object to compare to this object.
*
* @return The hash-code of this object.
*/
public boolean equals(Object thatObj) {
Goal that = (Goal) thatObj;
return this.getName().equals(that.getName());
}
/**
* Produce a textual representation suitable for debugging.
*
* @return A textual representation suitable for debugging.
*/
public String toString() {
return "[Goal: name=\"" + getName() + "\"]" + "; precursor="
+ getPrecursors() + "]";
}
}