GH-4899 Add more documentation and throw errors if things are not used as they are supposed to

Signed-off-by: Jerven Bolleman <jerven.bolleman@sib.swiss>

Author: JervenBolleman

core/queryalgebra/evaluation/src/main/java/org/eclipse/rdf4j/query/algebra/evaluation/iterator/PathIteration.java

@@ -44,7 +44,7 @@ public class PathIteration extends LookAheadIteration<BindingSet> {
 	private static final String START = "$start_from_path_iteration";
 
 	/**
-	 *
+	 * Required as we can't prepare the queries yet.
 	 */
 	private final EvaluationStrategy strategy;
 
@@ -81,8 +81,16 @@ public class PathIteration extends LookAheadIteration<BindingSet> {
 	private final Set<String> namedIntermediateJoins = new HashSet<>();
 
 	private final CollectionFactory collectionFactory;
+	/**
+	 * Instead of depending on hash codes not colliding we instead make sure that each element is unique per iteration.
+	 * Which is why this is a static volatile field. As more than one path iteration can be present in the same query.
+	 */
 	private static volatile int PATH_ITERATOR_ID_GENERATOR = 0;
 
+	/**
+	 * Using the ++ to increment the volatile shared id generator, the id in this iterator must remain constant during
+	 * execution.
+	 */
 	private final int pathIteratorId = PATH_ITERATOR_ID_GENERATOR++;
 	private final String endVarName = "END_" + JOINVAR_PREFIX + pathIteratorId;
 
@@ -117,6 +125,12 @@ public PathIteration(EvaluationStrategy strategy, Scope scope, Var startVar,
 		createIteration();
 	}
 
+	/**
+	 * Used to turn a method call into a direct field access
+	 *
+	 * @param s the name of the variable to see if it is in the bindingset
+	 * @return the value of the start or end or if asked for a different field a null.
+	 */
 	private static final BiConsumer<Value, MutableBindingSet> getSet(String s) {
 		switch (s) {
 		case START:
@@ -125,29 +139,46 @@ private static final BiConsumer<Value, MutableBindingSet> getSet(String s) {
 			return (v, vp) -> ((ValuePair) vp).endValue = v;
 		default:
 			return (v, vp) -> {
+				throw new IllegalStateException("A value is being asked to be set where we never expected one");
 			};
 		}
 	}
 
+	/**
+	 * Used to turn a method call into a direct field access
+	 *
+	 * @param s the name of the variable to see if it is in the bindingset
+	 * @return the value of the start or end, if asked for a different field throw an illegalstate exception
+	 */
 	private static final Function<BindingSet, Value> getGet(String s) {
 		switch (s) {
 		case START:
 			return (vp) -> ((ValuePair) vp).startValue;
 		case END:
 			return (vp) -> ((ValuePair) vp).endValue;
 		default:
-			return (vp) -> null;
+			return (vp) -> {
+				throw new IllegalStateException("A value is being asked to be set where we never expected one");
+			};
 		}
 	};
 
+	/**
+	 * Used to turn a method call into a direct field access
+	 *
+	 * @param s the name of the variable to see if it is in the bindingset
+	 * @return true if start or end is not null, if asked for a different field throw an illegalstate exception
+	 */
 	private static final Predicate<BindingSet> getHas(String s) {
 		switch (s) {
 		case START:
 			return (vp) -> ((ValuePair) vp).startValue != null;
 		case END:
 			return (vp) -> ((ValuePair) vp).endValue != null;
 		default:
-			return (vp) -> false;
+			return (vp) -> {
+				throw new IllegalStateException("A value is being asked to be set where we never expected one");
+			};
 		}
 	};
 
@@ -397,6 +428,10 @@ protected boolean isUnbound(Var var, BindingSet bindings) {
 		}
 	}
 
+	/**
+	 * A specialized BingingSet that can only hold the start and end values of a Path. Minimizing unneeded memory use,
+	 * and allows specialization in the sets required to answer this part of a query.
+	 */
 	protected static class ValuePair implements MutableBindingSet {
 		private static final long serialVersionUID = 1L;
 
@@ -556,7 +591,7 @@ public void setBinding(Binding binding) {
 		}
 	}
 
-	class VarReplacer extends AbstractQueryModelVisitor<QueryEvaluationException> {
+	private class VarReplacer extends AbstractQueryModelVisitor<QueryEvaluationException> {
 
 		private final Var toBeReplaced;