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 <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)