Package com.tnsai.planning

Class PlanningFailureException

java.lang.Object

java.lang.Throwable

java.lang.Exception

java.lang.RuntimeException

com.tnsai.exceptions.TnsAIException

com.tnsai.planning.PlanningFailureException

All Implemented Interfaces:

Serializable

public final class PlanningFailureException
extends com.tnsai.exceptions.TnsAIException

Typed failure raised when planning cannot produce a plan for an unsatisfied goal, or when a produced plan stops holding while it executes.

An empty plan from Planner.plan(java.util.Map) means every goal was already satisfied. Anything else is a failure and arrives here, so a caller cannot mistake "nothing to do" for "the planner gave up".

reason() separates the four ways planning ends without a plan: the goal is simply PlanningFailureException.Reason.UNREACHABLE, the precondition graph is cyclic, the depth budget ran out, or the bounded search budget did. goalName() and maxDepth() are always populated on the exception that escapes the planner; actionName() and precondition() carry the action-level detail when the failure happened inside precondition search.

Two reasons are raised after planning rather than during it, because a plan that no longer holds is a planning failure and travels on this same channel. PlanningFailureException.Reason.PRECONDITION_STALE reports a step whose precondition had stopped holding by the time execution reached it, with actionName() and precondition() naming the refused step. PlanningFailureException.Reason.GOAL_UNSATISFIED_AFTER_EXECUTION reports a goal the plan set out to establish and the executed bodies did not, with goalName() naming it — the first such goal the planner's own ordering yields, which for BackwardChainingPlanner is the highest-priority one.

See Also:

• Serialized Form

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static enum	PlanningFailureException.Reason	Why planning ended without a plan.

Method Summary

Modifier and Type	Method	Description
String	actionName()	Returns the action the failure concerns: the one whose precondition search failed, or — for PlanningFailureException.Reason.PRECONDITION_STALE — the planned step that was refused.
String	goalName()	Returns the unsatisfied goal planning was working on.
int	maxDepth()	Returns the depth budget in force when planning failed.
String	precondition()	Returns the precondition the failure concerns: the one being searched when the failure occurred, or — for PlanningFailureException.Reason.PRECONDITION_STALE — the clause that no longer held.
PlanningFailureException.Reason	reason()	Returns why planning ended without a plan.

Methods inherited from class com.tnsai.exceptions.TnsAIException

getContext, getErrorCode, getMaxRetryAttempts, getMessage, getSuggestedRetryDelayMs, getThrownAt, isRetryable, wrap

Methods inherited from class java.lang.Throwable

addSuppressed, fillInStackTrace, getCause, getLocalizedMessage, getStackTrace, getSuppressed, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace, toString

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

Method Details

reason

public PlanningFailureException.Reason reason()

Returns why planning ended without a plan.

Returns:

failure category

goalName

public String goalName()

Returns the unsatisfied goal planning was working on.

Returns:

goal name; empty on a failure that never escaped the planner, and on PlanningFailureException.Reason.PRECONDITION_STALE, which is raised after planning has already produced a plan and names a step rather than a goal. PlanningFailureException.Reason.GOAL_UNSATISFIED_AFTER_EXECUTION populates it with the goal the plan promised

actionName

public String actionName()

Returns the action the failure concerns: the one whose precondition search failed, or — for PlanningFailureException.Reason.PRECONDITION_STALE — the planned step that was refused.

Returns:

action name, empty for a goal-level failure

precondition

public String precondition()

Returns the precondition the failure concerns: the one being searched when the failure occurred, or — for PlanningFailureException.Reason.PRECONDITION_STALE — the clause that no longer held.

Returns:

precondition expression, possibly empty

maxDepth

public int maxDepth()

Returns the depth budget in force when planning failed.

Returns:

configured max depth; 0 for the two execution-time reasons, PlanningFailureException.Reason.PRECONDITION_STALE and PlanningFailureException.Reason.GOAL_UNSATISFIED_AFTER_EXECUTION, which are not raised during search and so have no budget to report