Github user stain commented on a diff in the pull request:
https://github.com/apache/incubator-commonsrdf/pull/10#discussion_r29322000
--- Diff: api/src/main/java/org/apache/commons/rdf/api/BlankNode.java ---
@@ -41,60 +41,51 @@
* on the concrete syntax or implementation. The syntactic restrictions on
blank
* node identifiers, if any, therefore also depend on the concrete RDF
syntax or
* implementation.
- *
+ *
* Implementations that handle blank node identifiers in concrete syntaxes
need
* to be careful not to create the same blank node from multiple
occurrences of
* the same blank node identifier except in situations where this is
supported
* by the syntax. </blockquote>
- *
- * A BlankNode object created through the
- * {@link RDFTermFactory#createBlankNode()} method must be universally
unique,
- * and SHOULD contain a {@link UUID} as part of its
- * {@link #internalIdentifier()}.
- *
- * A BlankNode object created through the
- * {@link RDFTermFactory#createBlankNode(String)} method must be
universally
- * unique, but also produce the same {@link #internalIdentifier()} as any
- * previous or future calls to that method on that factory with the same
- * parameters. In addition, it SHOULD contain a {@link UUID} as part of its
- * {@link #internalIdentifier()}, created using
- * {@link UUID#nameUUIDFromBytes(byte[])} using a constant salt for each
- * instance of {@link RDFTermFactory}, with the given identifier joined to
that
- * salt in a consistent manner.
- *
*
+ * A BlankNode SHOULD contain a {@link UUID} string as part of its
+ * universally unique {@link #uniqueReference()}.
+ *
+ * @see RDFTermFactory#createBlankNode()
+ * @see RDFTermFactory#createBlankNode(String)
* @see <a
href="http://www.w3.org/TR/rdf11-concepts/#dfn-blank-node";>RDF-1.1
* Blank Node</a>
*/
public interface BlankNode extends BlankNodeOrIRI {
/**
- * Return a <a href=
- * "http://www.w3.org/TR/rdf11-concepts/#dfn-blank-node-identifier";
>unique
- * label</a> for the blank node. This label is generated by either
- * {@link RDFTermFactory#createBlankNode()} or
- * {@link RDFTermFactory#createBlankNode(String)} and is unique within
the
- * context of the instance of the factory. In particular, successive
calls
- * to the {@link RDFTermFactory#createBlankNode(String)} method on a
single
- * factory with the same parameters MUST return BlankNode objects with
- * identical internalIdentifiers, but the identifiers SHOULD be mapped
to
- * unique values in the context of the factory instance.
- *
- * IMPORTANT: This is not a serialization/syntax label, and there are
no
- * guarantees that it is a valid identifier in any concrete syntax.
For an
- * N-Triples compatible identifier use {@link #ntriplesString()}. For
all
- * other syntaxes, the result of this method must be sanitized to
produce a
- * valid concrete identifier if one is needed.
+ * Return a reference for uniquely identifying the blank node.
+ * <p>
+ * The reference string MUST be universally unique, e.g. blank nodes
created
+ * separately in different JVMs or from different {@link
RDFTermFactory}
+ * instances MUST NOT have the same reference string.
--- End diff --
I clarified this to:
> The reference string MUST universally and uniquely identify this blank
> node. That is, individual blank nodes created separately in different
> JVMs or from different {@link RDFTermFactory} instances MUST NOT have the
> same reference string.
The SHOULD in the RDFTermFactory means you are allowed to have two
different RDFTermFactory instances that deliberately produces equivalent blank
nodes for the same note. (e.g. because they are Serializable or a parsing
session of a single document is done across a distributed system). SHOULD means
"Don't do it unless you know what you're up to" -- so you can only do it while
also being compliant with the MUST here that those blank nodes are then
equivalent.
---
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.
---
