Github user stain commented on a diff in the pull request:
https://github.com/apache/incubator-commonsrdf/pull/26#discussion_r85522921
--- Diff: 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
--- End diff --
It's not - they are both due to immutability. I split this into multiple
paragraphs.
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at [email protected] or file a JIRA ticket
with INFRA.
---
