Fix for HASCO to update best seen solution during node expansion of the

search.

Added documentation to AOptimizer.

JAICore/jaicore-basic/src/main/java/jaicore/basic/algorithm/AOptimizer.java

@@ -11,29 +11,51 @@
 import jaicore.basic.algorithm.events.SolutionCandidateFoundEvent;
 import jaicore.basic.algorithm.exceptions.AlgorithmException;
 
+/**
+ * The AOptimizer represents an algorithm that is meant to optimize for a single best solution.
+ * While it may observe multiple candidates for the best solution and report them via events
+ * when running, eventually it will return only the single best observed one.
+ *
+ * @author fmohr, wever
+ *
+ * @param <I> The type of input instances (problems) to be solved by the algorithm.
+ * @param <O> The type of output that is obtained by running the algorithm on the input.
+ * @param <V> The type performance values will have to compare different solutions.
+ */
 public abstract class AOptimizer<I, O extends ScoredItem<V>, V extends Comparable<V>> extends ASolutionCandidateIterator<I, O> implements IOptimizationAlgorithm<I, O, V> {
 
 	/* Logger variables */
 	private Logger logger = LoggerFactory.getLogger(AOptimizer.class);
 	private String loggerName;
 
+	/* currently best solution candidate observed so far */
 	private O bestSeenSolution;
 
+	/**
+	 * C'tor taking only an input as a parameter.
+	 * @param input The input of the algorithm.
+	 */
 	public AOptimizer(final I input) {
 		super(input);
 	}
 
+	/**
+	 * C'tor taking a configuration of the algorithm and an input for the algorithm as arguments.
+	 * @param config The parameterization of the algorithm.
+	 * @param input The input to the algorithm (the problem to solve).
+	 */
 	protected AOptimizer(final IAlgorithmConfig config, final I input) {
 		super(config, input);
 	}
 
 	/**
 	 * Updates the best seen solution if the new solution is better. Returns true iff the best seen solution has been updated.
 	 *
-	 * @param candidate
-	 * @return
+	 * @param candidate A candidate for a new best seen solution. It is only updated iff the candidate performs better than the bestSeenSolution observed so far.
+	 * @return Returns true iff the candidate is the best seen solution.
 	 */
 	protected boolean updateBestSeenSolution(final O candidate) {
+		assert (candidate != null) : "Cannot update best solution with null.";
 		if (this.bestSeenSolution == null || (candidate.getScore() != null && candidate.getScore().compareTo(this.bestSeenSolution.getScore()) < 0)) {
 			this.bestSeenSolution = candidate;
 			return true;
@@ -61,6 +83,9 @@ public SolutionCandidateFoundEvent<O> nextSolutionCandidateEvent() throws Interr
 		throw new NoSuchElementException();
 	}
 
+	/**
+	 * @return The best seen solution, yet.
+	 */
 	public O getBestSeenSolution() {
 		return this.bestSeenSolution;
 	}