commonsrdf-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From st...@apache.org
Subject [50/50] [abbrv] incubator-commonsrdf git commit: COMMONSRDF-7 clarify immutability and hashcode
Date Fri, 28 Oct 2016 13:08:28 GMT
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/COMMONSRDF-7
Commit: 797a4cd53f62585ecff7f49864f3cd75a55ba0f9
Parents: e0dc34a
Author: Stian Soiland-Reyes <stain@apache.org>
Authored: Fri Oct 28 13:52:49 2016 +0100
Committer: Stian Soiland-Reyes <stain@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)


Mime
View raw message