COMMONSRDF-37: Improve Quad javadoc
Project: http://git-wip-us.apache.org/repos/asf/incubator-commonsrdf/repo Commit: http://git-wip-us.apache.org/repos/asf/incubator-commonsrdf/commit/a1d65546 Tree: http://git-wip-us.apache.org/repos/asf/incubator-commonsrdf/tree/a1d65546 Diff: http://git-wip-us.apache.org/repos/asf/incubator-commonsrdf/diff/a1d65546 Branch: refs/heads/jsonld-java Commit: a1d65546388f3d9acf56456d08d923aae3beaa41 Parents: 53ef228 Author: Stian Soiland-Reyes <st...@apache.org> Authored: Thu Jul 7 10:47:06 2016 +0100 Committer: Stian Soiland-Reyes <st...@apache.org> Committed: Thu Jul 7 10:47:06 2016 +0100 ---------------------------------------------------------------------- .../org/apache/commons/rdf/api/GraphLike.java | 21 +++++++++++++++--- .../java/org/apache/commons/rdf/api/Quad.java | 23 +++++++++++--------- .../org/apache/commons/rdf/api/QuadLike.java | 18 +++++++++++---- .../org/apache/commons/rdf/api/TripleLike.java | 14 +++++++++--- .../commons/rdf/simple/DatasetGraphView.java | 2 +- 5 files changed, 57 insertions(+), 21 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/incubator-commonsrdf/blob/a1d65546/api/src/main/java/org/apache/commons/rdf/api/GraphLike.java ---------------------------------------------------------------------- diff --git a/api/src/main/java/org/apache/commons/rdf/api/GraphLike.java b/api/src/main/java/org/apache/commons/rdf/api/GraphLike.java index c68278e..bd37510 100644 --- a/api/src/main/java/org/apache/commons/rdf/api/GraphLike.java +++ b/api/src/main/java/org/apache/commons/rdf/api/GraphLike.java @@ -30,7 +30,23 @@ import java.util.stream.Stream; * generalised {@link TripleLike} or {@link QuadLike} statements, and does not * include semantics like {@link #size()} or the requirement of mapping * {@link RDFTerm} instances from different implementations. + * <p> + * As {@link TripleLike} do not have a specific {@link Object#equals(Object)} + * semantics, the behaviour of methods like {@link #contains(TripleLike)} and + * {@link #remove(TripleLike)} is undefined for arguments that are not object + * identical to previously added or returned {@link TripleLike} statements. * + * @param <T> + * A {@link TripleLike} type used by the graph methods, typically + * {@link Triple} or {@link Quad} + * @param <S> + * The type of subjects in the statements, typically + * {@link BlankNodeOrIRI} + * @param <P> + * The type of predicates in the statements, typically {@link IRI} + * @param <O> + * The type of objects in the statements, typically {@link RDFTerm} + * * @since 0.3.0-incubating * @see Graph * @see Dataset @@ -50,7 +66,7 @@ public interface GraphLike<T extends TripleLike<S, P, O>, S extends RDFTerm, P e * Check if statement is contained. * * @param statement - * The {@link TripleLike} statement to chec + * The {@link TripleLike} statement to check * @return True if the statement is contained */ boolean contains(T statement); @@ -71,7 +87,7 @@ public interface GraphLike<T extends TripleLike<S, P, O>, S extends RDFTerm, P e /** * Number of statements. * - * @return + * @return Number of statements */ long size(); @@ -86,7 +102,6 @@ public interface GraphLike<T extends TripleLike<S, P, O>, S extends RDFTerm, P e * Iterate over contained statements. * * @return An {@link Iterable} of {@link TripleLike} statements. - * * @throws IllegalStateException * if the {@link Iterable} has been reused * @throws ConcurrentModificationException http://git-wip-us.apache.org/repos/asf/incubator-commonsrdf/blob/a1d65546/api/src/main/java/org/apache/commons/rdf/api/Quad.java ---------------------------------------------------------------------- diff --git a/api/src/main/java/org/apache/commons/rdf/api/Quad.java b/api/src/main/java/org/apache/commons/rdf/api/Quad.java index 5a67571..679000b 100644 --- a/api/src/main/java/org/apache/commons/rdf/api/Quad.java +++ b/api/src/main/java/org/apache/commons/rdf/api/Quad.java @@ -67,31 +67,31 @@ public interface Quad extends QuadLike<BlankNodeOrIRI,IRI,RDFTerm,BlankNodeOrIRI BlankNodeOrIRI getSubject(); /** - * The predicate {@link IRI} of this triple. + * The predicate {@link IRI} of this quad. * - * @return The predicate {@link IRI} of this triple. + * @return The predicate {@link IRI} of this quad. * @see <a href="http://www.w3.org/TR/rdf11-concepts/#dfn-predicate";>RDF-1.1 * Triple predicate</a> */ IRI getPredicate(); /** - * The object of this triple, which may be either a {@link BlankNode}, an + * The object of this quad, which may be either a {@link BlankNode}, an * {@link IRI}, or a {@link Literal}, which are represented in Commons RDF * by the interface {@link RDFTerm}. * - * @return The object {@link RDFTerm} of this triple. + * @return The object {@link RDFTerm} of this quad. * @see <a href="http://www.w3.org/TR/rdf11-concepts/#dfn-object";>RDF-1.1 * Triple object</a> */ RDFTerm getObject(); /** - * Convert this Quad to a Triple. + * Adapt this Quad to a Triple. * <p> * The returned {@link Triple} will have equivalent values returned from the - * methods {@link TripleOrQuad#getSubject()}, - * {@link TripleOrQuad#getPredicate()} and {@link TripleOrQuad#getObject()}. + * methods {@link TripleLike#getSubject()}, + * {@link TripleLike#getPredicate()} and {@link TripleLike#getObject()}. * <p> * The returned {@link Triple} MUST NOT be {@link #equals(Object)} to this * {@link Quad}, even if this quad has a default graph @@ -113,12 +113,12 @@ public interface Quad extends QuadLike<BlankNodeOrIRI,IRI,RDFTerm,BlankNodeOrIRI * * The <code>default</code> implementation of this method return a proxy * {@link Triple} instance that keeps a reference to this {@link Quad} to - * calls the underlying {@link TripleOrQuad} methods, but supplies a + * call the underlying {@link TripleLike} methods, but supplies a * {@link Triple} compatible implementation of {@link Triple#equals(Object)} * and {@link Triple#hashCode()}. Implementations may override this method, * e.g. for a more efficient solution. * - * @return A {@link Triple} that contains the same {@link TripleOrQuad} + * @return A {@link Triple} that contains the same {@link TripleLike} * properties as this Quad. */ default Triple asTriple() { @@ -140,6 +140,9 @@ public interface Quad extends QuadLike<BlankNodeOrIRI,IRI,RDFTerm,BlankNodeOrIRI @Override public boolean equals(Object obj) { + if (obj == this) { + return true; + } if (!(obj instanceof Triple)) { return false; } @@ -159,7 +162,7 @@ public interface Quad extends QuadLike<BlankNodeOrIRI,IRI,RDFTerm,BlankNodeOrIRI /** * Check it this Quad is equal to another Quad. * <p> - * Two Triples are equal if and only if their {@link #getGraphName()}, + * Two Quads are equal if and only if their {@link #getGraphName()}, * {@link #getSubject()}, {@link #getPredicate()} and * {@link #getObject()} are equal. * </p> http://git-wip-us.apache.org/repos/asf/incubator-commonsrdf/blob/a1d65546/api/src/main/java/org/apache/commons/rdf/api/QuadLike.java ---------------------------------------------------------------------- diff --git a/api/src/main/java/org/apache/commons/rdf/api/QuadLike.java b/api/src/main/java/org/apache/commons/rdf/api/QuadLike.java index 9c42465..3f85862 100644 --- a/api/src/main/java/org/apache/commons/rdf/api/QuadLike.java +++ b/api/src/main/java/org/apache/commons/rdf/api/QuadLike.java @@ -28,10 +28,20 @@ import java.util.Optional; * {@link Quad#equals(Object)} semantics, and can allow generalised quads (e.g. * a {@link BlankNode} as predicate). * <p> - * Implementations should specialise which {@link RDFTerm} subclasses they - * return for subject {@link S}, predicate {@link P}, object {@link O} and graph - * name {@link G}. - * <p> + * Implementations should specialise which specific {@link RDFTerm} types they + * return for {@link #getSubject()}, {@link #getPredicate()}, + * {@link #getObject()} and {@link #getGraphName()}. + * + * @param <S> + * The type of subjects in the statements, typically + * {@link BlankNodeOrIRI} + * @param <P> + * The type of predicates in the statements, typically {@link IRI} + * @param <O> + * The type of objects in the statements, typically {@link RDFTerm} + * @param <G> + * The type of graph names in the statements, typically + * {@link BlankNodeOrIRI} * * @since 0.3.0-incubating * @see Quad http://git-wip-us.apache.org/repos/asf/incubator-commonsrdf/blob/a1d65546/api/src/main/java/org/apache/commons/rdf/api/TripleLike.java ---------------------------------------------------------------------- diff --git a/api/src/main/java/org/apache/commons/rdf/api/TripleLike.java b/api/src/main/java/org/apache/commons/rdf/api/TripleLike.java index 2fbeb11..9bead97 100644 --- a/api/src/main/java/org/apache/commons/rdf/api/TripleLike.java +++ b/api/src/main/java/org/apache/commons/rdf/api/TripleLike.java @@ -26,14 +26,22 @@ package org.apache.commons.rdf.api; * does not have a formalised {@link Triple#equals(Object)} semantics, and can * allow generalised triples (e.g. a {@link BlankNode} as predicate). * <p> - * Implementations should specialise which {@link RDFTerm} subclasses they - * return for subject {@link S}, predicate {@link P} and object {@link O}. + * Implementations should specialise which specific {@link RDFTerm} types they + * return for {@link #getSubject()}, {@link #getPredicate()} and + * {@link #getObject()}. + * + * @param <S> + * The type of subjects in the statements, typically + * {@link BlankNodeOrIRI} + * @param <P> + * The type of predicates in the statements, typically {@link IRI} + * @param <O> + * The type of objects in the statements, typically {@link RDFTerm} * * @since 0.3.0-incubating * @see Triple * @see Quad * @see QuadLike - * */ public interface TripleLike<S extends RDFTerm, P extends RDFTerm, O extends RDFTerm> { http://git-wip-us.apache.org/repos/asf/incubator-commonsrdf/blob/a1d65546/simple/src/main/java/org/apache/commons/rdf/simple/DatasetGraphView.java ---------------------------------------------------------------------- diff --git a/simple/src/main/java/org/apache/commons/rdf/simple/DatasetGraphView.java b/simple/src/main/java/org/apache/commons/rdf/simple/DatasetGraphView.java index a347c3e..d578a40 100644 --- a/simple/src/main/java/org/apache/commons/rdf/simple/DatasetGraphView.java +++ b/simple/src/main/java/org/apache/commons/rdf/simple/DatasetGraphView.java @@ -41,7 +41,7 @@ import org.apache.commons.rdf.api.Triple; * triples will add them to the <em>default graph</em>, while removing triples * will remove from all graphs.</dd> * - * <dt>{@link #DatasetGraphView(Dataset, IRI)}</dt> + * <dt>{@link #DatasetGraphView(Dataset, BlankNodeOrIRI)}</dt> * <dd>Expose a particular graph of the Dataset, either named by an {@link IRI}, a * {@link BlankNode}, or <code>null</code> for the <em>default graph</em>.</dd> * </dl>
