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/27 09:57:42 UTC
[2/2] incubator-commonsrdf git commit: COMMONSRDF-7
RDFTerm/Triple/Quad are immutable
COMMONSRDF-7 RDFTerm/Triple/Quad are immutable
also clarify RDFTerm.equals() and RDFTerm.hashCode()
by delegation to its specializations IRI/BlankNode/Literal
Project: http://git-wip-us.apache.org/repos/asf/incubator-commonsrdf/repo
Commit: http://git-wip-us.apache.org/repos/asf/incubator-commonsrdf/commit/cdc76af1
Tree: http://git-wip-us.apache.org/repos/asf/incubator-commonsrdf/tree/cdc76af1
Diff: http://git-wip-us.apache.org/repos/asf/incubator-commonsrdf/diff/cdc76af1
Branch: refs/heads/COMMONSRDF-7
Commit: cdc76af17932dcdd4c27cf1842445e5f5a90ae46
Parents: cb58d56
Author: Stian Soiland-Reyes <st...@apache.org>
Authored: Thu Oct 27 10:56:38 2016 +0100
Committer: Stian Soiland-Reyes <st...@apache.org>
Committed: Thu Oct 27 10:56:38 2016 +0100
----------------------------------------------------------------------
.../java/org/apache/commons/rdf/api/Quad.java | 16 ++++-
.../org/apache/commons/rdf/api/RDFTerm.java | 68 ++++++++++++++++++--
.../java/org/apache/commons/rdf/api/Triple.java | 24 +++++--
3 files changed, 98 insertions(+), 10 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/incubator-commonsrdf/blob/cdc76af1/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 6ce9a95..c1427c6 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,16 +17,30 @@
*/
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/" >RDF-1.1
+ * <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 it's 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.
+ * <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.
*
* @since 0.3.0-incubating
* @see Dataset
http://git-wip-us.apache.org/repos/asf/incubator-commonsrdf/blob/cdc76af1/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 731d7cc..67f849c 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,14 +17,32 @@
*/
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.<br>
+ * 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} represents either an {@link IRI}, a {@link BlankNode} or a
+ * {@link Literal}.
+ * <p>
+ * A {@link RDFTerm} object in Commons RDF is considered <em>immutable</em>,
+ * that is, over it's 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.
*
* @see <a href= "http://www.w3.org/TR/rdf11-concepts/#dfn-rdf-term" >RDF-1.1
- * Term</a>
+ * Term</a>
*/
public interface RDFTerm {
@@ -37,4 +55,46 @@ public interface RDFTerm {
*/
String ntriplesString();
+ /**
+ * Check it this RDFTerm is equal to another RDFTerm.
+ * <p>
+ * If this object is an {@link IRI}, equality is checked using
+ * {@link IRI#equals(Object)}, or if this object is a {@link BlankNode},
+ * equality is checked using {@link BlankNode#equals(Object)}, or if this
+ * object is a {@link Literal}, equality is checked using
+ * {@link Literal#equals(Object)}.
+ * <p>
+ * Implementations MUST also override {@link #hashCode()} so that two equal
+ * Literals produce the same hash code.
+ *
+ * @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
+ */
+ @Override
+ public boolean equals(Object other);
+
+ /**
+ * Calculate a hash code for this RDFTerm.
+ * <p>
+ * As an {@link RDFTerm} is <em>immutable</em>, this method will always
+ * return the same hashCode over the lifetime of this object.
+ * <p>
+ * 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()
+ *
+ * @return a hash code value for this RDFTerm.
+ */
+ @Override
+ public int hashCode();
+
}
http://git-wip-us.apache.org/repos/asf/incubator-commonsrdf/blob/cdc76af1/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 9e7f140..848356d 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,18 +17,32 @@
*/
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>
+ * 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>
+ * <p>
+ * A {@link Triple} object in Commons RDF is considered <em>immutable</em>, that
+ * is, over it's life time it will have consistent behaviour for its
+ * {@link #equals(Object)} and {@link #hashCode()}, 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.
*
- * @see Quad
+ * @see Quad
* @see RDFTermFactory#createTriple(BlankNodeOrIRI,IRI,RDFTerm)
* @see <a href= "http://www.w3.org/TR/rdf11-concepts/#dfn-rdf-triple" >RDF-1.1
- * Triple</a>
+ * Triple</a>
*/
public interface Triple extends TripleLike {