GH-4819 code cleanup and add javadocs

core/common/iterator/src/main/java/org/eclipse/rdf4j/common/iteration/DualUnionIteration.java

@@ -14,6 +14,7 @@
 import java.util.Comparator;
 import java.util.NoSuchElementException;
 
+import org.eclipse.rdf4j.common.annotation.Experimental;
 import org.eclipse.rdf4j.common.order.StatementOrder;
 import org.eclipse.rdf4j.model.Value;
 
@@ -40,6 +41,7 @@ private DualUnionIteration(CloseableIteration<? extends E> iteration1,
 		this.cmp = null;
 	}
 
+	@Experimental
 	public DualUnionIteration(StatementOrder statementOrder, Comparator<Value> cmp,
 			CloseableIteration<? extends E> iteration1, CloseableIteration<? extends E> iteration2) {
 		this.iteration1 = iteration1;
@@ -51,7 +53,7 @@ public DualUnionIteration(StatementOrder statementOrder, Comparator<Value> cmp,
 		throw new UnsupportedOperationException("Not implemented yet");
 	}
 
-	public static <E, X extends Exception> CloseableIteration<? extends E> getWildcardInstance(
+	public static <E> CloseableIteration<? extends E> getWildcardInstance(
 			CloseableIteration<? extends E> leftIteration, CloseableIteration<? extends E> rightIteration) {
 
 		if (rightIteration instanceof EmptyIteration) {
@@ -63,7 +65,8 @@ public static <E, X extends Exception> CloseableIteration<? extends E> getWildca
 		}
 	}
 
-	public static <E, X extends Exception> CloseableIteration<? extends E> getWildcardInstance(StatementOrder order,
+	@Experimental
+	public static <E> CloseableIteration<? extends E> getWildcardInstance(StatementOrder order,
 			Comparator<Value> cmp,
 			CloseableIteration<? extends E> leftIteration, CloseableIteration<? extends E> rightIteration) {
 
@@ -84,7 +87,7 @@ public static <E, X extends Exception> CloseableIteration<? extends E> getWildca
 		}
 	}
 
-	public static <E, X extends Exception> CloseableIteration<E> getInstance(CloseableIteration<E> leftIteration,
+	public static <E> CloseableIteration<E> getInstance(CloseableIteration<E> leftIteration,
 			CloseableIteration<E> rightIteration) {
 
 		if (rightIteration instanceof EmptyIteration) {

core/common/order/src/main/java/org/eclipse/rdf4j/common/order/AvailableStatementOrder.java

@@ -13,11 +13,14 @@
 
 import java.util.Set;
 
+import org.eclipse.rdf4j.common.annotation.Experimental;
 import org.eclipse.rdf4j.model.IRI;
 import org.eclipse.rdf4j.model.Resource;
 import org.eclipse.rdf4j.model.Value;
 
+@Experimental
 public interface AvailableStatementOrder {
 
+	@Experimental
 	Set<StatementOrder> getSupportedOrders(Resource subj, IRI pred, Value obj, Resource... contexts);
 }

core/common/order/src/main/java/org/eclipse/rdf4j/common/order/StatementOrder.java

@@ -13,16 +13,19 @@
 
 import java.util.Comparator;
 
+import org.eclipse.rdf4j.common.annotation.Experimental;
 import org.eclipse.rdf4j.model.Statement;
 import org.eclipse.rdf4j.model.Value;
 
+@Experimental
 public enum StatementOrder {
 
 	S,
 	P,
 	O,
 	C;
 
+	@Experimental
 	public Comparator<Statement> getComparator(Comparator<Value> comparator) {
 		switch (this) {
 		case S:

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

@@ -23,7 +23,7 @@ public interface RDFStarTripleSource extends TripleSource {
 	 * indicate wildcards.
 	 *
 	 * @param subj A Resource specifying the triple's subject, or <var>null</var> for a wildcard.
-	 * @param pred A URI specifying the triple's predicate, or <var>null</var> for a wildcard.
+	 * @param pred A IRI specifying the triple's predicate, or <var>null</var> for a wildcard.
 	 * @param obj  A Value specifying the triple's object, or <var>null</var> for a wildcard.
 	 * @return An iterator over the relevant triples.
 	 * @throws QueryEvaluationException If the rdf star triple source failed to get the statements.

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

@@ -14,6 +14,7 @@
 import java.util.EnumSet;
 import java.util.Set;
 
+import org.eclipse.rdf4j.common.annotation.Experimental;
 import org.eclipse.rdf4j.common.iteration.CloseableIteration;
 import org.eclipse.rdf4j.common.iteration.EmptyIteration;
 import org.eclipse.rdf4j.common.order.AvailableStatementOrder;
@@ -33,15 +34,14 @@
 public interface TripleSource extends AvailableStatementOrder {
 
 	EmptyIteration<? extends Statement> EMPTY_ITERATION = new EmptyIteration<>();
-	EmptyIteration<? extends Triple> EMPTY_TRIPLE_ITERATION = new EmptyIteration<>();
 
 	/**
 	 * Gets all statements that have a specific subject, predicate and/or object. All three parameters may be null to
 	 * indicate wildcards. Optionally a (set of) context(s) may be specified in which case the result will be restricted
 	 * to statements matching one or more of the specified contexts.
 	 *
 	 * @param subj     A Resource specifying the subject, or <var>null</var> for a wildcard.
-	 * @param pred     A URI specifying the predicate, or <var>null</var> for a wildcard.
+	 * @param pred     A IRI specifying the predicate, or <var>null</var> for a wildcard.
 	 * @param obj      A Value specifying the object, or <var>null</var> for a wildcard.
 	 * @param contexts The context(s) to get the statements from. Note that this parameter is a vararg and as such is
 	 *                 optional. If no contexts are supplied the method operates on the entire repository.
@@ -55,34 +55,70 @@ CloseableIteration<? extends Statement> getStatements(Resource subj, IRI pred,
 	 * Gets all statements that have a specific subject, predicate and/or object. All three parameters may be null to
 	 * indicate wildcards. Optionally a (set of) context(s) may be specified in which case the result will be restricted
 	 * to statements matching one or more of the specified contexts.
+	 * <p>
+	 * Statements are returned in the order specified by the <var>statementOrder</var> parameter. Use
+	 * {@link #getSupportedOrders(Resource, IRI, Value, Resource...)} to first retrieve the statement orders supported
+	 * by this store for this statement pattern.
+	 * <p>
+	 * Note that this method is experimental and may be changed or removed without notice.
 	 *
+	 * @param order    The order in which the statements should be returned.
 	 * @param subj     A Resource specifying the subject, or <var>null</var> for a wildcard.
-	 * @param pred     A URI specifying the predicate, or <var>null</var> for a wildcard.
+	 * @param pred     A IRI specifying the predicate, or <var>null</var> for a wildcard.
 	 * @param obj      A Value specifying the object, or <var>null</var> for a wildcard.
 	 * @param contexts The context(s) to get the statements from. Note that this parameter is a vararg and as such is
 	 *                 optional. If no contexts are supplied the method operates on the entire repository.
-	 * @return An iterator over the relevant statements.
+	 * @return An ordered iterator over the relevant statements.
 	 * @throws QueryEvaluationException If the triple source failed to get the statements.
 	 */
+	@Experimental
 	default CloseableIteration<? extends Statement> getStatements(StatementOrder order, Resource subj, IRI pred,
 			Value obj, Resource... contexts) throws QueryEvaluationException {
 		throw new UnsupportedOperationException(
 				"StatementOrder is not supported by this TripleSource: " + this.getClass().getName());
 	}
 
-	default Set<StatementOrder> getSupportedOrders(Resource subj, IRI pred,
-			Value obj, Resource... contexts) throws QueryEvaluationException {
+	/**
+	 * The underlying store may support some, but not all, statement orders based on the statement pattern. This method
+	 * can be used to determine which orders are supported for a given statement pattern. The supported orders can be
+	 * used to retrieve statements in a specific order using
+	 * {@link #getStatements(StatementOrder, Resource, IRI, Value, Resource...)} .
+	 * <p>
+	 * Note that this method is experimental and may be changed or removed without notice.
+	 *
+	 * @param subj     A Resource specifying the subject, or <var>null</var> for a wildcard.
+	 * @param pred     A IRI specifying the predicate, or <var>null</var> for a wildcard.
+	 * @param obj      A Value specifying the object, or <var>null</var> for a wildcard.
+	 * @param contexts The context(s) to get the data from. Note that this parameter is a vararg and as such is
+	 *                 optional. If no contexts are specified the method operates on the entire repository. A
+	 *                 <var>null</var> value can be used to match context-less statements.
+	 * @return a set of supported statement orders
+	 */
+	@Experimental
+	default Set<StatementOrder> getSupportedOrders(Resource subj, IRI pred, Value obj, Resource... contexts) {
 		return Set.of();
 	}
 
 	/**
-	 * Gets a ValueFactory object that can be used to create URI-, blank node- and literal objects.
+	 * Different underlying datastructures may have different ways of ordering statements. On-disk stores typically use
+	 * a long to represent a value and only stores the actual value in a dictionary, in this case the order would be the
+	 * order that values where inserted into the dictionary. Stores that instead store values in SPARQL-order can return
+	 * an instance of {@link org.eclipse.rdf4j.query.algebra.evaluation.util.ValueComparator} which may allow for
+	 * further optimizations.
+	 * <p>
+	 * Note that this method is experimental and may be changed or removed without notice.
 	 *
-	 * @return a ValueFactory object for this TripleSource.
+	 * @return a comparator that matches the order of values in the store
 	 */
-	ValueFactory getValueFactory();
-
+	@Experimental
 	default Comparator<Value> getComparator() {
 		return null;
 	}
+
+	/**
+	 * Gets a ValueFactory object that can be used to create IRI-, blank node- and literal objects.
+	 *
+	 * @return a ValueFactory object for this TripleSource.
+	 */
+	ValueFactory getValueFactory();
 }

core/queryalgebra/evaluation/src/main/java/org/eclipse/rdf4j/query/algebra/evaluation/impl/EvaluationStatistics.java

@@ -129,7 +129,7 @@ public void meet(ArbitraryLengthPath node) {
 		@Override
 		public void meet(Service node) {
 			if (!node.getServiceRef().hasValue()) {
-				// the URI is not available, may be computed in the course of the
+				// the IRI is not available, may be computed in the course of the
 				// query
 				// => use high cost to order the SERVICE node late in the query plan
 				cardinality = UNBOUND_SERVICE_CARDINALITY;

core/queryalgebra/evaluation/src/main/java/org/eclipse/rdf4j/query/algebra/evaluation/util/ValueComparator.java

@@ -63,7 +63,7 @@ public int compare(Value o1, Value o2) {
 		boolean iri1 = o1.isIRI();
 		boolean iri2 = o2.isIRI();
 		if (iri1 && iri2) {
-			return compareURIs((IRI) o1, (IRI) o2);
+			return compareIRIs((IRI) o1, (IRI) o2);
 		}
 		if (iri1) {
 			return -1;
@@ -101,8 +101,8 @@ private int compareBNodes(BNode leftBNode, BNode rightBNode) {
 		return leftBNode.getID().compareTo(rightBNode.getID());
 	}
 
-	private int compareURIs(IRI leftURI, IRI rightURI) {
-		return leftURI.toString().compareTo(rightURI.toString());
+	private int compareIRIs(IRI leftIRI, IRI rightIRI) {
+		return leftIRI.toString().compareTo(rightIRI.toString());
 	}
 
 	private int compareLiterals(Literal leftLit, Literal rightLit) {
@@ -211,7 +211,7 @@ private int compareDatatypes(CoreDatatype.XSD leftDatatype, CoreDatatype.XSD rig
 		}
 
 		// incompatible or unordered datatype
-		return compareURIs(leftDatatypeIRI, rightDatatypeIRI);
+		return compareIRIs(leftDatatypeIRI, rightDatatypeIRI);
 
 	}
 

core/queryalgebra/model/src/main/java/org/eclipse/rdf4j/query/algebra/TupleExpr.java

@@ -12,6 +12,7 @@
 
 import java.util.Set;
 
+import org.eclipse.rdf4j.common.annotation.Experimental;
 import org.eclipse.rdf4j.common.order.AvailableStatementOrder;
 
 /**
@@ -37,9 +38,12 @@ public interface TupleExpr extends QueryModelNode {
 	@Override
 	TupleExpr clone();
 
+	@Experimental
 	Set<Var> getSupportedOrders(AvailableStatementOrder tripleSource);
 
+	@Experimental
 	void setOrder(Var var);
 
+	@Experimental
 	Var getOrder();
 }

core/repository/contextaware/src/main/java/org/eclipse/rdf4j/repository/contextaware/ContextAwareConnection.java

@@ -458,7 +458,7 @@ public void exportStatements(Resource subj, IRI pred, Value obj, boolean include
 	 * optionally restricted to the specified set of named contexts.
 	 *
 	 * @param subj A Resource specifying the subject, or <var>null</var> for a wildcard.
-	 * @param pred A URI specifying the predicate, or <var>null</var> for a wildcard.
+	 * @param pred A IRI specifying the predicate, or <var>null</var> for a wildcard.
 	 * @param obj  A Value specifying the object, or <var>null</var> for a wildcard.
 	 * @return The statements matching the specified pattern. The result object is a {@link RepositoryResult} object, a
 	 *         lazy Iterator-like object containing {@link Statement}s and optionally throwing a
@@ -511,7 +511,7 @@ public boolean hasStatement(Statement st, boolean includeInferred, Resource... c
 	 * the specified contexts.
 	 *
 	 * @param subj A Resource specifying the subject, or <var>null</var> for a wildcard.
-	 * @param pred A URI specifying the predicate, or <var>null</var> for a wildcard.
+	 * @param pred A IRI specifying the predicate, or <var>null</var> for a wildcard.
 	 * @param obj  A Value specifying the object, or <var>null</var> for a wildcard.
 	 * @return true If a matching statement is in the repository in the specified context, false otherwise.
 	 * @see #getReadContexts()

core/sail/api/src/main/java/org/eclipse/rdf4j/sail/SailConnection.java

@@ -125,6 +125,13 @@ CloseableIteration<? extends Statement> getStatements(Resource subj, IRI pred, V
 	 * Gets all statements from the specified contexts that have a specific subject, predicate and/or object. All three
 	 * parameters may be null to indicate wildcards. The <var>includeInferred</var> parameter can be used to control
 	 * which statements are fetched: all statements or only the statements that have been added explicitly.
+	 * <p>
+	 * Statements are returned in the order specified by the <var>statementOrder</var> parameter. Use
+	 * {@link #getSupportedOrders(Resource, IRI, Value, Resource...)} to first retrieve the statement orders supported
+	 * by this store for this statement pattern.
+	 * <p>
+	 * Note that this method is experimental and may be changed or removed without notice.
+	 *
 	 *
 	 * @param statementOrder  The order that the statements should be returned in.
 	 * @param subj            A Resource specifying the subject, or <var>null</var> for a wildcard.
@@ -139,6 +146,7 @@ CloseableIteration<? extends Statement> getStatements(Resource subj, IRI pred, V
 	 * @throws SailException         If the Sail object encountered an error or unexpected situation internally.
 	 * @throws IllegalStateException If the connection has been closed.
 	 */
+	@Experimental
 	default CloseableIteration<? extends Statement> getStatements(StatementOrder statementOrder, Resource subj,
 			IRI pred, Value obj,
 			boolean includeInferred, Resource... contexts) throws SailException {
@@ -468,10 +476,39 @@ default Explanation explain(Explanation.Level level, TupleExpr tupleExpr, Datase
 		throw new UnsupportedOperationException();
 	}
 
+	/**
+	 * The underlying store may support some, but not all, statement orders based on the statement pattern. This method
+	 * can be used to determine which orders are supported for a given statement pattern. The supported orders can be
+	 * used to retrieve statements in a specific order using
+	 * {@link #getStatements(StatementOrder, Resource, IRI, Value, boolean, Resource...)}.
+	 * <p>
+	 * Note that this method is experimental and may be changed or removed without notice.
+	 *
+	 * @param subj     A Resource specifying the subject, or <var>null</var> for a wildcard.
+	 * @param pred     A URI specifying the predicate, or <var>null</var> for a wildcard.
+	 * @param obj      A Value specifying the object, or <var>null</var> for a wildcard.
+	 * @param contexts The context(s) to get the data from. Note that this parameter is a vararg and as such is
+	 *                 optional. If no contexts are specified the method operates on the entire repository. A
+	 *                 <var>null</var> value can be used to match context-less statements.
+	 * @return a set of supported statement orders
+	 */
+	@Experimental
 	default Set<StatementOrder> getSupportedOrders(Resource subj, IRI pred, Value obj, Resource... contexts) {
 		return Set.of();
 	}
 
+	/**
+	 * Different underlying datastructures may have different ways of ordering statements. On-disk stores typically use
+	 * a long to represent a value and only stores the actual value in a dictionary, in this case the order would be the
+	 * order that values where inserted into the dictionary. Stores that instead store values in SPARQL-order can return
+	 * an instance of {@link org.eclipse.rdf4j.query.algebra.evaluation.util.ValueComparator} which may allow for
+	 * further optimizations.
+	 * <p>
+	 * Note that this method is experimental and may be changed or removed without notice.
+	 *
+	 * @return a comparator that matches the order of values in the store
+	 */
+	@Experimental
 	default Comparator<Value> getComparator() {
 		return null;
 	}

core/sail/base/src/main/java/org/eclipse/rdf4j/sail/base/UnionSailDataset.java

@@ -176,7 +176,7 @@ private <T> CloseableIteration<? extends T> union(
 		return DualUnionIteration.getWildcardInstance(iteration1, iteration2);
 	}
 
-	private <T> CloseableIteration<? extends T> union(StatementOrder order, Comparator cmp,
+	private <T> CloseableIteration<? extends T> union(StatementOrder order, Comparator<Value> cmp,
 			CloseableIteration<? extends T> iteration1,
 			CloseableIteration<? extends T> iteration2) {
 		return DualUnionIteration.getWildcardInstance(order, cmp, iteration1, iteration2);