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:11 UTC
[1/6] incubator-commonsrdf git commit: COMMONSRDF-7
RDFTerm/Triple/Quad are immutable
Repository: incubator-commonsrdf
Updated Branches:
refs/heads/master 413dd09a6 -> 34c9b42bd
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/master
Commit: 2efe1ab37c4995037b8c3a6ee431e9ba58e21cd5
Parents: 413dd09
Author: Stian Soiland-Reyes <st...@apache.org>
Authored: Thu Oct 27 10:56:38 2016 +0100
Committer: Stian Soiland-Reyes <st...@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)
[6/6] incubator-commonsrdf git commit: COMMONSRDF-7
Triple/Quad/RDFTerm are immutable
Posted by st...@apache.org.
COMMONSRDF-7 Triple/Quad/RDFTerm are immutable
Project: http://git-wip-us.apache.org/repos/asf/incubator-commonsrdf/repo
Commit: http://git-wip-us.apache.org/repos/asf/incubator-commonsrdf/commit/34c9b42b
Tree: http://git-wip-us.apache.org/repos/asf/incubator-commonsrdf/tree/34c9b42b
Diff: http://git-wip-us.apache.org/repos/asf/incubator-commonsrdf/diff/34c9b42b
Branch: refs/heads/master
Commit: 34c9b42bd7113e49110c02988bb159fb7ebe0aee
Parents: 413dd09 4125eff
Author: Stian Soiland-Reyes <st...@apache.org>
Authored: Fri Oct 28 14:25:43 2016 +0100
Committer: Stian Soiland-Reyes <st...@apache.org>
Committed: Fri Oct 28 14:25:43 2016 +0100
----------------------------------------------------------------------
.../java/org/apache/commons/rdf/api/Quad.java | 45 ++++++++++---
.../org/apache/commons/rdf/api/QuadLike.java | 7 +-
.../org/apache/commons/rdf/api/RDFTerm.java | 71 ++++++++++++++++++--
.../java/org/apache/commons/rdf/api/Triple.java | 25 ++++++-
.../org/apache/commons/rdf/api/TripleLike.java | 5 +-
5 files changed, 132 insertions(+), 21 deletions(-)
----------------------------------------------------------------------
[4/6] incubator-commonsrdf git commit: TripleLike/QuadLike NOT
required to thread-safe or immutable
Posted by st...@apache.org.
TripleLike/QuadLike NOT required to thread-safe or immutable
Project: http://git-wip-us.apache.org/repos/asf/incubator-commonsrdf/repo
Commit: http://git-wip-us.apache.org/repos/asf/incubator-commonsrdf/commit/47734d7e
Tree: http://git-wip-us.apache.org/repos/asf/incubator-commonsrdf/tree/47734d7e
Diff: http://git-wip-us.apache.org/repos/asf/incubator-commonsrdf/diff/47734d7e
Branch: refs/heads/master
Commit: 47734d7eb054418e6da8be0702fa87f01baae75f
Parents: 797a4cd
Author: Stian Soiland-Reyes <st...@apache.org>
Authored: Fri Oct 28 14:13:01 2016 +0100
Committer: Stian Soiland-Reyes <st...@apache.org>
Committed: Fri Oct 28 14:13:01 2016 +0100
----------------------------------------------------------------------
api/src/main/java/org/apache/commons/rdf/api/QuadLike.java | 7 ++++---
api/src/main/java/org/apache/commons/rdf/api/TripleLike.java | 5 +++--
2 files changed, 7 insertions(+), 5 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/incubator-commonsrdf/blob/47734d7e/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 cfe1733..eab92ec 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
@@ -25,9 +25,10 @@ import java.util.Optional;
* A QuadLike statement has at least a {@link #getSubject()},
* {@link #getPredicate()}, {@link #getObject()} and {@link #getGraphName()},
* but unlike a {@link Quad} does not have a formalised
- * {@link Quad#equals(Object)} or {@link Quad#hashCode()} semantics. This
- * interface can also be used for <em>generalised quads</em> (e.g. a
- * {@link BlankNode} as predicate).
+ * {@link Quad#equals(Object)} or {@link Quad#hashCode()} semantics and is not
+ * required to be <em>immutable</em> or <em>thread-safe</em>. This interface can
+ * also be used for <em>generalised quads</em> (e.g. a {@link BlankNode} as
+ * predicate).
* <p>
* Implementations should specialise which specific {@link RDFTerm} types they
* return by overriding {@link #getSubject()}, {@link #getPredicate()},
http://git-wip-us.apache.org/repos/asf/incubator-commonsrdf/blob/47734d7e/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 b469aa4..1427f17 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
@@ -24,8 +24,9 @@ package org.apache.commons.rdf.api;
* A TripleLike statement has at least a {@link #getSubject()},
* {@link #getPredicate()} and {@link #getObject()}, but unlike a {@link Triple}
* does not have a formalised {@link Triple#equals(Object)} or
- * {@link Triple#hashCode()} semantics. This interfaced can also be used for
- * <em>generalised triples</em> (e.g. a {@link BlankNode} as predicate).
+ * {@link Triple#hashCode()} semantics and is not required to be
+ * <em>immutable</em> or <em>thread-safe</em>. This interfaced can also be used
+ * for <em>generalised triples</em> (e.g. a {@link BlankNode} as predicate).
* <p>
* Implementations should specialise which specific {@link RDFTerm} types they
* return by overriding {@link #getSubject()}, {@link #getPredicate()} and
[5/6] incubator-commonsrdf git commit: Quad.asTriple also is
equivalence-immutable
Posted by st...@apache.org.
Quad.asTriple also is equivalence-immutable
Project: http://git-wip-us.apache.org/repos/asf/incubator-commonsrdf/repo
Commit: http://git-wip-us.apache.org/repos/asf/incubator-commonsrdf/commit/4125eff1
Tree: http://git-wip-us.apache.org/repos/asf/incubator-commonsrdf/tree/4125eff1
Diff: http://git-wip-us.apache.org/repos/asf/incubator-commonsrdf/diff/4125eff1
Branch: refs/heads/master
Commit: 4125eff1a6d8bcf278eed181097a7257ac2fe82b
Parents: 47734d7
Author: Stian Soiland-Reyes <st...@apache.org>
Authored: Fri Oct 28 14:13:42 2016 +0100
Committer: Stian Soiland-Reyes <st...@apache.org>
Committed: Fri Oct 28 14:13:42 2016 +0100
----------------------------------------------------------------------
api/src/main/java/org/apache/commons/rdf/api/Quad.java | 10 +++++-----
1 file changed, 5 insertions(+), 5 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/incubator-commonsrdf/blob/4125eff1/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 0b19ec1..7fab357 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
@@ -32,14 +32,14 @@ import java.util.Optional;
* <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.
+ * {@link #getPredicate()}, {@link #getObject()} and {@link #asTriple()} will
+ * have consistent {@link Object#equals(Object)} behaviour.
* <p>
* 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.
+ * according to {@link Object#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
[2/6] incubator-commonsrdf git commit: typo it's -> its
Posted by st...@apache.org.
typo it's -> its
Project: http://git-wip-us.apache.org/repos/asf/incubator-commonsrdf/repo
Commit: http://git-wip-us.apache.org/repos/asf/incubator-commonsrdf/commit/e0dc34ad
Tree: http://git-wip-us.apache.org/repos/asf/incubator-commonsrdf/tree/e0dc34ad
Diff: http://git-wip-us.apache.org/repos/asf/incubator-commonsrdf/diff/e0dc34ad
Branch: refs/heads/master
Commit: e0dc34ade393f6ccb5f3de384cdbb3889f2e7cbb
Parents: 2efe1ab
Author: Stian Soiland-Reyes <st...@apache.org>
Authored: Fri Oct 28 11:46:20 2016 +0100
Committer: Stian Soiland-Reyes <st...@apache.org>
Committed: Fri Oct 28 11:46:20 2016 +0100
----------------------------------------------------------------------
api/src/main/java/org/apache/commons/rdf/api/Quad.java | 2 +-
api/src/main/java/org/apache/commons/rdf/api/RDFTerm.java | 2 +-
api/src/main/java/org/apache/commons/rdf/api/Triple.java | 2 +-
3 files changed, 3 insertions(+), 3 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/incubator-commonsrdf/blob/e0dc34ad/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 b2e8ed5..a242ae3 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
@@ -32,7 +32,7 @@ import java.util.Set;
* 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
+ * 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)}
http://git-wip-us.apache.org/repos/asf/incubator-commonsrdf/blob/e0dc34ad/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 a277140..47fd432 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
@@ -28,7 +28,7 @@ import java.util.Set;
* 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
+ * 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
http://git-wip-us.apache.org/repos/asf/incubator-commonsrdf/blob/e0dc34ad/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 57934fa..51c4a39 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
@@ -29,7 +29,7 @@ import java.util.Set;
* 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
+ * is, over its 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)}
[3/6] incubator-commonsrdf git commit: COMMONSRDF-7 clarify
immutability and hashcode
Posted by st...@apache.org.
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)