diff --git a/bdi-jade-extensions/src/bdi4jade/extension/undo/reasoning/RevertingOptionGenerationFunction.java b/bdi-jade-extensions/src/bdi4jade/extension/undo/reasoning/RevertingOptionGenerationFunction.java
index b850fd7..524f8c8 100644
--- a/bdi-jade-extensions/src/bdi4jade/extension/undo/reasoning/RevertingOptionGenerationFunction.java
+++ b/bdi-jade-extensions/src/bdi4jade/extension/undo/reasoning/RevertingOptionGenerationFunction.java
@@ -36,7 +36,9 @@ import bdi4jade.goal.PredicateGoal;
import bdi4jade.reasoning.OptionGenerationFunction;
/**
- * This class does blablabla.
+ * This class implements the {@link OptionGenerationFunction} interface. It is
+ * responsible for performing the reversion of actions recorded by existing goal
+ * achievement metadata.
*
* @author João Faccin
*/
@@ -45,14 +47,20 @@ public class RevertingOptionGenerationFunction implements OptionGenerationFuncti
private Capability capability;
/**
+ * Initializes a new option generation function and sets its related capability.
+ *
* @param capability
+ * the capability to be set.
*/
public RevertingOptionGenerationFunction(Capability capability) {
setCapability(capability);
}
- /* (non-Javadoc)
- * @see bdi4jade.reasoning.OptionGenerationFunction#generateGoals(bdi4jade.core.GoalUpdateSet)
+ /*
+ * (non-Javadoc)
+ *
+ * @see bdi4jade.reasoning.OptionGenerationFunction#generateGoals(bdi4jade.core.
+ * GoalUpdateSet)
*/
@Override
public void generateGoals(GoalUpdateSet goalUpdateSet) {
@@ -87,8 +95,14 @@ public class RevertingOptionGenerationFunction implements OptionGenerationFuncti
}
/**
+ * Generates achievement goals with the aim of reverting the evaluation value of
+ * each predicate in predicates according to the beliefBase.
+ *
* @param predicates
+ * the list of predicates to be reverted.
* @param beliefBase
+ * the belief base that must contain the updated evaluation values of
+ * the given predicates.
* @return
*/
public ArrayList<PredicateGoal<?>> generateReversionGoals(ArrayList<Predicate> predicates, BeliefBase beliefBase) {
@@ -102,8 +116,11 @@ public class RevertingOptionGenerationFunction implements OptionGenerationFuncti
return reversionGoals;
}
- /* (non-Javadoc)
- * @see bdi4jade.reasoning.ReasoningStrategy#setCapability(bdi4jade.core.Capability)
+ /*
+ * (non-Javadoc)
+ *
+ * @see
+ * bdi4jade.reasoning.ReasoningStrategy#setCapability(bdi4jade.core.Capability)
*/
@Override
public void setCapability(Capability capability) {
diff --git a/bdi-jade-extensions/src/bdi4jade/extension/undo/RevertingBDIAgent.java b/bdi-jade-extensions/src/bdi4jade/extension/undo/RevertingBDIAgent.java
index 8100f2f..14d216c 100644
--- a/bdi-jade-extensions/src/bdi4jade/extension/undo/RevertingBDIAgent.java
+++ b/bdi-jade-extensions/src/bdi4jade/extension/undo/RevertingBDIAgent.java
@@ -34,7 +34,9 @@ import bdi4jade.goal.Goal;
import bdi4jade.goal.PredicateGoal;
/**
- * This class does blablabla.
+ * This class is an extension of {@link AbstractBDIAgent}. It provides a method
+ * to add reversible goals, i.e. goals with a corresponding
+ * {@link GoalAchievementMetadata}, to the set of agent goals.
*
* @author João Faccin
*/
@@ -42,6 +44,31 @@ public class RevertingBDIAgent extends AbstractBDIAgent {
private static final long serialVersionUID = 7351855722581311736L;
+ /**
+ * Adds a new goal to be achieved by this agent. Additionally, it creates and
+ * sets a corresponding {@link GoalAchievementMetadata} for the new goal.
+ *
+ * @param dispatcher
+ * the capability that dispatched this goal.
+ * @param goal
+ * the goal to be achieved.
+ * @param goalListener
+ * the listener to be notified.
+ * @param reversionTrigger
+ * a list of {@link Predicate} that specifies the condition in which
+ * a reversion of the actions performed to achieve this goal will be
+ * activated.
+ * @param rollback
+ * a flag that indicates the desire of a rollback in case of a plan
+ * failure when achieving this goal.
+ * @param maxExecutedPlans
+ * the number of plans that can be executed after achieving this goal
+ * before the corresponding goal achievement metadata is discarded.
+ * @param maxTime
+ * the time that can pass after achieving this goal before the
+ * corresponding goal achievement metadata is discarded.
+ * @return true if the goal was added, false otherwise.
+ */
public final boolean addGoal(Capability dispatcher, Goal goal, GoalListener goalListener,
List<Predicate> reversionTrigger, Boolean rollback, Integer maxExecutedPlans, Integer maxTime) {
@@ -51,7 +78,7 @@ public class RevertingBDIAgent extends AbstractBDIAgent {
Intention intention = this.getIntentions().stream().filter(g -> g.getGoal().equals(goal))
.collect(Collectors.toList()).get(0);
((RevertingCapability) dispatcher).createGoalAchievementMetadata((PredicateGoal<?>) goal, intention,
- reversionTrigger, rollback, maxExecutedPlans, maxTime);
+ rollback, reversionTrigger, maxExecutedPlans, maxTime);
}
}
return true;
diff --git a/bdi-jade-extensions/src/bdi4jade/extension/undo/RevertingCapability.java b/bdi-jade-extensions/src/bdi4jade/extension/undo/RevertingCapability.java
index 00c9f06..c249f9d 100644
--- a/bdi-jade-extensions/src/bdi4jade/extension/undo/RevertingCapability.java
+++ b/bdi-jade-extensions/src/bdi4jade/extension/undo/RevertingCapability.java
@@ -41,7 +41,13 @@ import bdi4jade.goal.GoalStatus;
import bdi4jade.goal.PredicateGoal;
/**
- * This class does blablabla.
+ * This class is an extension of {@link Capability}. It implements the
+ * {@link BeliefListener} and {@link GoalListener} interfaces and has the
+ * {@link RevertingOptionGenerationFunction} as its default option generation
+ * function. This capability provides agents with the ability to revert actions
+ * performed with the aim of achieving particular goals. For this purpose, it
+ * stores a mapping between goals and their corresponding achievement metadata,
+ * as well as a mapping between child and parent goals.
*
* @author João Faccin
*/
@@ -52,6 +58,10 @@ public class RevertingCapability extends Capability implements BeliefListener, G
private final Map<Goal, GoalAchievementMetadata> gams;
private final Map<Goal, Goal> parentGoals;
+ /**
+ * Creates a new capability and sets {@link RevertingOptionGenerationFunction}
+ * as its default option generation function.
+ */
public RevertingCapability() {
this.gams = new HashMap<>();
this.parentGoals = new HashMap<>();
@@ -60,20 +70,63 @@ public class RevertingCapability extends Capability implements BeliefListener, G
this.getBeliefBase().addBeliefListener(this);
}
+ /**
+ * Adds a mapping between the goal and the goal achievement metadata to the
+ * existing map.
+ *
+ * @param goal
+ * the goal to be associated with the goal achievement metadata.
+ * @param gam
+ * the goal achievement metadata to which the goal will be
+ * associated.
+ */
public void addGoalAchievementMetadata(Goal goal, GoalAchievementMetadata gam) {
this.gams.put(goal, gam);
}
- public void addParentGoal(Goal goal, Goal parent) {
- this.parentGoals.put(goal, parent);
+ /**
+ * Adds a mapping between the child goal and its parent to the existing map.
+ *
+ * @param child
+ * the child goal to be associated with the parent.
+ * @param parent
+ * the parent goal to which the child will be associated.
+ */
+ public void addParentGoal(Goal child, Goal parent) {
+ this.parentGoals.put(child, parent);
}
+ /**
+ * Creates a new {@link GoalAchievementMetadata} with its related goal and
+ * intention, and adds the mapping between the goal and the goal achievement
+ * metadata to the existing map.
+ *
+ * @param goal
+ * the goal related to the goal achievement metadata.
+ * @param intention
+ * the intention related to the goal achievement metadata.
+ * @return the created goal achievement metadata.
+ */
public GoalAchievementMetadata createGoalAchievementMetadata(PredicateGoal<?> goal, Intention intention) {
GoalAchievementMetadata gam = new GoalAchievementMetadata(goal, intention);
addGoalAchievementMetadata(goal, gam);
return gam;
}
+ /**
+ * Creates a new {@link GoalAchievementMetadata} with its related goal,
+ * intention, and rollback flag. It also adds the mapping between the goal and
+ * the goal achievement metadata to the existing map.
+ *
+ * @param goal
+ * the goal related to the goal achievement metadata
+ * @param intention
+ * the intention related to the goal achievement metadata.
+ * @param rollback
+ * a flag that indicates the desire of a rollback in case of a plan
+ * failure.
+ * @return the created goal achievement metadata.
+ */
public GoalAchievementMetadata createGoalAchievementMetadata(PredicateGoal<?> goal, Intention intention,
Boolean rollback) {
GoalAchievementMetadata gam = new GoalAchievementMetadata(goal, intention, rollback);
@@ -81,14 +134,43 @@ public class RevertingCapability extends Capability implements BeliefListener, G
return gam;
}
+ /**
+ * Creates a new {@link GoalAchievementMetadata} with its related goal,
+ * intention, reversion trigger, rollback flag and discarding conditions. It
+ * also adds the mapping between the goal and the goal achievement metadata to
+ * the existing map.
+ *
+ * @param goal
+ * the goal related to the goal achievement metadata
+ * @param intention
+ * the intention related to the goal achievement metadata.
+ * @param rollback
+ * a flag that indicates the desire of a rollback in case of a plan
+ * failure.
+ * @param reversionTrigger
+ * a list of {@link Predicate} that specifies the condition in which
+ * a reversion will be activated.
+ * @param maxExecutedPlans
+ * the number of plans that can be executed after achieving the
+ * related goal before this goal achievement metadata is discarded.
+ * @param maxTime
+ * the time that can pass after achieving the related goal before
+ * this goal achievement metadata is discarded.
+ * @return the created goal achievement metadata.
+ */
public GoalAchievementMetadata createGoalAchievementMetadata(PredicateGoal<?> goal, Intention intention,
- List<Predicate> reversionTrigger, Boolean rollback, Integer maxExecutedPlans, Integer maxTime) {
+ Boolean rollback, List<Predicate> reversionTrigger, Integer maxExecutedPlans, Integer maxTime) {
GoalAchievementMetadata gam = new GoalAchievementMetadata((PredicateGoal<?>) goal, intention, rollback,
reversionTrigger, maxExecutedPlans, maxTime);
addGoalAchievementMetadata(goal, gam);
return gam;
}
+ /*
+ * (non-Javadoc)
+ *
+ * @see bdi4jade.event.BeliefListener#eventOccurred(bdi4jade.event.BeliefEvent)
+ */
@Override
public void eventOccurred(BeliefEvent beliefEvent) {
if (beliefEvent.getAction().equals(Action.BELIEF_UPDATED) && beliefEvent.getArgs() != null) {
@@ -106,10 +188,26 @@ public class RevertingCapability extends Capability implements BeliefListener, G
}
}
+ /**
+ * Returns the mapping between goals and their corresponding goal achievement
+ * metadata.
+ *
+ * @return the goal achievement metadata map.
+ */
public Map<Goal, GoalAchievementMetadata> getGoalAchievementMetadata() {
return gams;
}
+ /**
+ * Returns the oldest parent of goal with a mapping in the goal achievement map.
+ * If there is no such parent and the goal is in the mapping, returns the goal
+ * itself, otherwise, returns null.
+ *
+ * @param goal
+ * the goal whose oldest reversible parent is to be found.
+ * @return the oldest reversible parent of goal if it exists, or null,
+ * otherwise.
+ */
private Goal getOldestReversibleParent(Goal goal) {
Goal parent = null;
Goal aux = goal;
@@ -128,10 +226,20 @@ public class RevertingCapability extends Capability implements BeliefListener, G
return parent;
}
+ /**
+ * Returns the mapping between child goals and their parents.
+ *
+ * @return the parentGols map.
+ */
public Map<Goal, Goal> getParentGoals() {
return parentGoals;
}
+ /*
+ * (non-Javadoc)
+ *
+ * @see bdi4jade.event.GoalListener#goalPerformed(bdi4jade.event.GoalEvent)
+ */
@Override
public void goalPerformed(GoalEvent event) {
for (GoalAchievementMetadata gam : gams.values()) {
diff --git a/bdi-jade-extensions/src/bdi4jade/extension/undo/RevertingPlanBody.java b/bdi-jade-extensions/src/bdi4jade/extension/undo/RevertingPlanBody.java
index b1c1dce..9b19a97 100644
--- a/bdi-jade-extensions/src/bdi4jade/extension/undo/RevertingPlanBody.java
+++ b/bdi-jade-extensions/src/bdi4jade/extension/undo/RevertingPlanBody.java
@@ -26,7 +26,10 @@ import bdi4jade.goal.Goal;
import bdi4jade.plan.planbody.BeliefGoalPlanBody;
/**
- * This class does blablabla.
+ * This class is an extension of the {@link BeliefGoalPlanBody}. It overrides
+ * the {@link BeliefGoalPlanBody#dispatchGoal(Goal)} and
+ * {@link BeliefGoalPlanBody#dispatchSubgoalAndListen(Goal)} methods in order to
+ * set the parent of the subgoal being dispatched.
*
* @author João Faccin
*/
@@ -34,8 +37,11 @@ public abstract class RevertingPlanBody extends BeliefGoalPlanBody {
private static final long serialVersionUID = -678344739581158097L;
- /* (non-Javadoc)
- * @see bdi4jade.plan.planbody.AbstractPlanBody#dispatchSubgoal(bdi4jade.goal.Goal)
+ /*
+ * (non-Javadoc)
+ *
+ * @see
+ * bdi4jade.plan.planbody.AbstractPlanBody#dispatchSubgoal(bdi4jade.goal.Goal)
*/
@Override
public boolean dispatchSubgoal(Goal subgoal) {
@@ -43,8 +49,12 @@ public abstract class RevertingPlanBody extends BeliefGoalPlanBody {
return super.dispatchSubgoal(subgoal);
}
- /* (non-Javadoc)
- * @see bdi4jade.plan.planbody.AbstractPlanBody#dispatchSubgoalAndListen(bdi4jade.goal.Goal)
+ /*
+ * (non-Javadoc)
+ *
+ * @see
+ * bdi4jade.plan.planbody.AbstractPlanBody#dispatchSubgoalAndListen(bdi4jade.
+ * goal.Goal)
*/
@Override
public boolean dispatchSubgoalAndListen(Goal subgoal) {
@@ -53,7 +63,10 @@ public abstract class RevertingPlanBody extends BeliefGoalPlanBody {
}
/**
+ * Sets the parent goal of the subgoal being dispatched when it is possible.
+ *
* @param subgoal
+ * the subgoal whose parent will be set.
*/
private void setParentGoal(Goal subgoal) {
if (this.getCapability() instanceof RevertingCapability) {
