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/10/28 13:26:13 UTC
[3/6] incubator-commonsrdf git commit: COMMONSRDF-7 clarify
immutability and hashcode
COMMONSRDF-7 clarify immutability and hashcode
Project: http://git-wip-us.apache.org/repos/asf/incubator-commonsrdf/repo
Commit: http://git-wip-us.apache.org/repos/asf/incubator-commonsrdf/commit/797a4cd5
Tree: http://git-wip-us.apache.org/repos/asf/incubator-commonsrdf/tree/797a4cd5
Diff: http://git-wip-us.apache.org/repos/asf/incubator-commonsrdf/diff/797a4cd5
Branch: refs/heads/master
Commit: 797a4cd53f62585ecff7f49864f3cd75a55ba0f9
Parents: e0dc34a
Author: Stian Soiland-Reyes <st...@apache.org>
Authored: Fri Oct 28 13:52:49 2016 +0100
Committer: Stian Soiland-Reyes <st...@apache.org>
Committed: Fri Oct 28 14:06:58 2016 +0100
----------------------------------------------------------------------
.../java/org/apache/commons/rdf/api/Quad.java | 55 ++++++++++++--------
.../org/apache/commons/rdf/api/RDFTerm.java | 37 ++++++++-----
.../java/org/apache/commons/rdf/api/Triple.java | 29 +++++++----
3 files changed, 74 insertions(+), 47 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/incubator-commonsrdf/blob/797a4cd5/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 a242ae3..0b19ec1 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
@@ -17,31 +17,40 @@
*/
package org.apache.commons.rdf.api;
-import java.util.List;
-import java.util.Map;
import java.util.Objects;
import java.util.Optional;
-import java.util.Set;
/**
* A Quad is a statement in a
* <a href= "http://www.w3.org/TR/rdf11-concepts/#section-dataset" >RDF-1.1
- * Dataset</a>, as defined by
- * <a href= "https://www.w3.org/TR/2014/NOTE-rdf11-datasets-20140225/#quad-semantics" >RDF-1.1
- * Concepts and Abstract Syntax</a>, a W3C Working Group Note published on 25
- * February 2014.
+ * Dataset</a>, as defined by <a href=
+ * "https://www.w3.org/TR/2014/NOTE-rdf11-datasets-20140225/#quad-semantics"
+ * >RDF-1.1 Concepts and Abstract Syntax</a>, a W3C Working Group Note published
+ * on 25 February 2014.
* <p>
- * A {@link Quad} object in Commons RDF is considered <em>immutable</em>, that
- * is, over its life time it will have consistent behaviour for its
- * {@link #equals(Object)} and {@link #hashCode()}, and the instances returned
- * from {@link #getGraphName()}, {@link #getSubject()}, {@link #getPredicate()}
- * and {@link #getObject()} will have consistent {@link Object#equals(Object)}
- * behaviour.
+ * A <code>Quad</code> object in Commons RDF is considered
+ * <strong>immutable</strong>, that is, over its life time it will have
+ * consistent behaviour for its {@link #equals(Object)}, and the instances
+ * returned from {@link #getGraphName()}, {@link #getSubject()},
+ * {@link #getPredicate()} and {@link #getObject()} will have consistent
+ * {@link Object#equals(Object)} behaviour.
* <p>
- * Thus, a {@link Quad} is thread-safe and can be safely used in collections
- * like {@link List}, {@link Map} or {@link Set}, and a {@link Quad} can be
- * used interchangeably across Commons RDF implementations.
- *
+ * Note that <code>Quad</code> methods are not required to return object
+ * identical (<code>==</code>) instances as long as they are equivalent
+ * according to their {@link RDFTerm#equals(Object)} and/or
+ * {@link Optional#equals(Object)}. Specialisations of <code>Quad</code> may
+ * provide additional methods that are documented to be mutable.
+ * <p>
+ * <code>Quad</code> methods are <strong>thread-safe</strong>, however
+ * specialisations may provide additional methods that are documented to not be
+ * thread-safe.
+ * <p>
+ * <code>Quad</code>s can be safely used in hashing collections like
+ * {@link java.util.HashSet} and {@link java.util.HashMap}.
+ * <p>
+ * Any <code>Quad</code> can be used interchangeably across Commons RDF
+ * implementations.
+ *
* @since 0.3.0-incubating
* @see Dataset
* @see RDF#createQuad(BlankNodeOrIRI,BlankNodeOrIRI,IRI,RDFTerm)
@@ -53,7 +62,7 @@ public interface Quad extends QuadLike<BlankNodeOrIRI> {
/**
* The graph name (graph label) of this quad, if present.
- *
+ *
* If {@link Optional#isPresent()}, then the {@link Optional#get()} is
* either a {@link BlankNode} or an {@link IRI}, indicating the
* <a href="https://www.w3.org/TR/rdf11-concepts/#dfn-named-graph">graph
@@ -65,7 +74,7 @@ public interface Quad extends QuadLike<BlankNodeOrIRI> {
* @return If {@link Optional#isPresent()}, the graph name
* {@link BlankNodeOrIRI} of this quad, otherwise
* {@link Optional#empty()}, indicating the default graph.
- *
+ *
* @see <a href="https://www.w3.org/TR/rdf11-concepts/#dfn-rdf-dataset">RDF-
* 1.1 Dataset</a>
*/
@@ -114,7 +123,7 @@ public interface Quad extends QuadLike<BlankNodeOrIRI> {
* {@link #getGraphName()} value of {@link Optional#empty()}, but MUST
* follow the {@link Triple#equals(Object)} semantics. This means that the
* following MUST be true:
- *
+ *
* <pre>
* Quad q1, q2;
* if (q1.equals(q2)) {
@@ -126,14 +135,14 @@ public interface Quad extends QuadLike<BlankNodeOrIRI> {
* assert (!q1.getGraphName().equals(q2.getGraphName()));
* }
* </pre>
- *
+ *
* The <code>default</code> implementation of this method return a proxy
* {@link Triple} instance that keeps a reference to this {@link Quad} to
* 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 TripleLike}
* properties as this Quad.
*/
@@ -191,7 +200,7 @@ public interface Quad extends QuadLike<BlankNodeOrIRI> {
* this Quad's {@link #getGraphName()} is {@link Optional#empty()}. To test
* triple-like equivalence, callers can use:
* </p>
- *
+ *
* <pre>
* Quad q1;
* Triple t2;
http://git-wip-us.apache.org/repos/asf/incubator-commonsrdf/blob/797a4cd5/api/src/main/java/org/apache/commons/rdf/api/RDFTerm.java
----------------------------------------------------------------------
diff --git a/api/src/main/java/org/apache/commons/rdf/api/RDFTerm.java b/api/src/main/java/org/apache/commons/rdf/api/RDFTerm.java
index 47fd432..dc095b7 100644
--- a/api/src/main/java/org/apache/commons/rdf/api/RDFTerm.java
+++ b/api/src/main/java/org/apache/commons/rdf/api/RDFTerm.java
@@ -17,26 +17,35 @@
*/
package org.apache.commons.rdf.api;
-import java.util.List;
-import java.util.Map;
-import java.util.Set;
-
/**
* An <a href= "http://www.w3.org/TR/rdf11-concepts/#dfn-rdf-term" >RDF-1.1
* Term</a>, as defined by
* <a href= "http://www.w3.org/TR/rdf11-concepts/" >RDF-1.1 Concepts and
* Abstract Syntax</a>, a W3C Recommendation published on 25 February 2014.
* <p>
- * A {@link RDFTerm} object in Commons RDF is considered <em>immutable</em>,
- * that is, over its life time it will have consistent behaviour for its
- * {@link #equals(Object)} and {@link #hashCode()}, and objects returned from
- * its getter methods (e.g. {@link IRI#getIRIString()} and
- * {@link Literal#getLanguageTag()}) will have consistent
+ * A {@link RDFTerm} object in Commons RDF is considered
+ * <strong>immutable</strong>, that is, over its life time it will have
+ * consistent behaviour for its {@link #equals(Object)} and {@link #hashCode()},
+ * and objects returned from its getter methods (e.g. {@link IRI#getIRIString()}
+ * and {@link Literal#getLanguageTag()}) will have consistent
* {@link #equals(Object)} behaviour.
* <p>
- * Thus, an {@link RDFTerm} is thread-safe and can be safely used in collections
- * like {@link List}, {@link Map} or {@link Set}, and a {@link RDFTerm} can be
- * used interchangeably across Commons RDF implementations.
+ * Note that methods in <code>RDFTerm</code> and its Commons RDF specialisations
+ * {@link IRI}, {@link BlankNode} and {@link Literal} are not required to return
+ * object identical (<code>==</code>) instances as long as they are equivalent
+ * according to their {@link Object#equals(Object)}. Further specialisations may
+ * provide additional methods that are documented to be mutable.
+ * <p>
+ * Methods in <code>RDFTerm</code> and its Commons RDF specialisations
+ * {@link IRI}, {@link BlankNode} and {@link Literal} are
+ * <strong>thread-safe</strong>, however further specialisations may add
+ * additional methods that are documented to not be thread-safe.
+ * <p>
+ * <code>RDFTerm</code>s can be safely used in hashing collections like
+ * {@link java.util.HashSet} and {@link java.util.HashMap}.
+ * <p>
+ * Any <code>RDFTerm</code> can be used interchangeably across Commons RDF
+ * implementations.
*
* @see <a href= "http://www.w3.org/TR/rdf11-concepts/#dfn-rdf-term" >RDF-1.1
* Term</a>
@@ -68,7 +77,7 @@ public interface RDFTerm {
* @see IRI#equals(Object)
* @see BlankNode#equals(Object)
* @see Literal#equals(Object)
- *
+ *
* @param other
* Another object
* @return true if other is a RDFTerm and is equal to this
@@ -85,7 +94,7 @@ public interface RDFTerm {
* This method MUST be implemented in conjunction with
* {@link #equals(Object)} so that two equal RDFTerm produce the same hash
* code.
- *
+ *
* @see IRI#hashCode()
* @see Literal#hashCode()
* @see BlankNode#hashCode()
http://git-wip-us.apache.org/repos/asf/incubator-commonsrdf/blob/797a4cd5/api/src/main/java/org/apache/commons/rdf/api/Triple.java
----------------------------------------------------------------------
diff --git a/api/src/main/java/org/apache/commons/rdf/api/Triple.java b/api/src/main/java/org/apache/commons/rdf/api/Triple.java
index 51c4a39..7772851 100644
--- a/api/src/main/java/org/apache/commons/rdf/api/Triple.java
+++ b/api/src/main/java/org/apache/commons/rdf/api/Triple.java
@@ -17,27 +17,36 @@
*/
package org.apache.commons.rdf.api;
-import java.util.List;
-import java.util.Map;
import java.util.Objects;
-import java.util.Set;
/**
* An <a href= "http://www.w3.org/TR/rdf11-concepts/#dfn-rdf-triple" >RDF-1.1
* Triple</a>, as defined by
* <a href= "http://www.w3.org/TR/rdf11-concepts/" >RDF-1.1 Concepts and
- * Abstract Syntax</a>, a W3C Recommendation published on 25 February 2014.<br>
+ * Abstract Syntax</a>, a W3C Recommendation published on 25 February 2014.
* <p>
- * A {@link Triple} object in Commons RDF is considered <em>immutable</em>, that
- * is, over its life time it will have consistent behaviour for its
- * {@link #equals(Object)} and {@link #hashCode()}, and the {@link RDFTerm}
+ * A <code>Triple</code> object in Commons RDF is considered
+ * <strong>immutable</strong>, that is, over its life time it will have
+ * consistent behaviour for its {@link #equals(Object)}, and the {@link RDFTerm}
* instances returned from {@link #getSubject()}, {@link #getPredicate()} and
* {@link #getObject()} will have consistent {@link RDFTerm#equals(Object)}
* behaviour.
* <p>
- * Thus, a {@link Triple} is thread-safe and can be safely used in collections
- * like {@link List}, {@link Map} or {@link Set}, and a {@link Triple} can be
- * used interchangeably across Commons RDF implementations.
+ * Note that <code>Triple</code> methods are not required to return object
+ * identical (<code>==</code>) instances as long as they are equivalent
+ * according to {@link RDFTerm#equals(Object)}. Specialisations of
+ * <code>Triple</code> may provide additional methods that are documented to be
+ * mutable.
+ * <p>
+ * <code>Triple</code> methods are <strong>thread-safe</strong>, however
+ * specialisations may provide additional methods that are documented to not be
+ * thread-safe.
+ * <p>
+ * <code>Triple</code>s can be safely used in hashing collections like
+ * {@link java.util.HashSet} and {@link java.util.HashMap}.
+ * <p>
+ * Any <code>Triple</code> can be used interchangeably across Commons RDF
+ * implementations.
*
* @see Quad
* @see RDF#createTriple(BlankNodeOrIRI,IRI,RDFTerm)