You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@commonsrdf.apache.org by st...@apache.org on 2016/09/08 14:29:30 UTC
[03/19] incubator-commonsrdf git commit: COMMONSRDF-37: Improve Quad
javadoc
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/jena
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>