commonsrdf-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From st...@apache.org
Subject [18/19] incubator-commonsrdf git commit: COMMONSRDF-37: Improve Quad javadoc
Date Mon, 05 Sep 2016 15:54:02 GMT
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/master
Commit: a1d65546388f3d9acf56456d08d923aae3beaa41
Parents: 53ef228
Author: Stian Soiland-Reyes <stain@apache.org>
Authored: Thu Jul 7 10:47:06 2016 +0100
Committer: Stian Soiland-Reyes <stain@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>


Mime
View raw message