commonsrdf-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From st...@apache.org
Subject [48/50] [abbrv] incubator-commonsrdf git commit: COMMONSRDF-7 RDFTerm/Triple/Quad are immutable
Date Fri, 28 Oct 2016 13:08:26 GMT
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/2efe1ab3
Tree: http://git-wip-us.apache.org/repos/asf/incubator-commonsrdf/tree/2efe1ab3
Diff: http://git-wip-us.apache.org/repos/asf/incubator-commonsrdf/diff/2efe1ab3

Branch: refs/heads/COMMONSRDF-7
Commit: 2efe1ab37c4995037b8c3a6ee431e9ba58e21cd5
Parents: 413dd09
Author: Stian Soiland-Reyes <stain@apache.org>
Authored: Thu Oct 27 10:56:38 2016 +0100
Committer: Stian Soiland-Reyes <stain@apache.org>
Committed: Fri Oct 28 11:45:44 2016 +0100

----------------------------------------------------------------------
 .../java/org/apache/commons/rdf/api/Quad.java   | 16 ++++-
 .../org/apache/commons/rdf/api/RDFTerm.java     | 62 ++++++++++++++++++--
 .../java/org/apache/commons/rdf/api/Triple.java | 14 +++++
 3 files changed, 87 insertions(+), 5 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/incubator-commonsrdf/blob/2efe1ab3/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 3b286cb..b2e8ed5 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/2efe1ab3/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 2b69b24..a277140 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,15 +17,27 @@
  */
 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>
+ * 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 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>
- * Instances of RDFTerm SHOULD be an {@link IRI}, {@link BlankNode} or
- * {@link Literal}.
- * 
+ * 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>
  */
@@ -41,4 +53,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/2efe1ab3/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 ef9bdaa..57934fa 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,13 +17,27 @@
  */
 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>
+ * <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 RDF#createTriple(BlankNodeOrIRI,IRI,RDFTerm)


Mime
View raw message