COMMONSRDF-6 Make BlankNode.internalIdentifier generic .. e.g. remove implementation-specifics such as salts.
This keeps the "MUST be universally unique" aspect with a recommendation to have a UUID included, so that internalIdentifier() has a more well-defined purpose. Project: http://git-wip-us.apache.org/repos/asf/incubator-commonsrdf/repo Commit: http://git-wip-us.apache.org/repos/asf/incubator-commonsrdf/commit/5ec5230b Tree: http://git-wip-us.apache.org/repos/asf/incubator-commonsrdf/tree/5ec5230b Diff: http://git-wip-us.apache.org/repos/asf/incubator-commonsrdf/diff/5ec5230b Branch: refs/heads/master Commit: 5ec5230bfd021637a94015de5105167a05ade060 Parents: aae1886 Author: Stian Soiland-Reyes <st...@apache.org> Authored: Tue Apr 21 10:51:59 2015 +0100 Committer: Stian Soiland-Reyes <st...@apache.org> Committed: Fri Apr 24 09:44:52 2015 +0100 ---------------------------------------------------------------------- .../org/apache/commons/rdf/api/BlankNode.java | 44 ++++++---------- .../apache/commons/rdf/api/RDFTermFactory.java | 55 +++++++++++--------- 2 files changed, 44 insertions(+), 55 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/incubator-commonsrdf/blob/5ec5230b/api/src/main/java/org/apache/commons/rdf/api/BlankNode.java ---------------------------------------------------------------------- diff --git a/api/src/main/java/org/apache/commons/rdf/api/BlankNode.java b/api/src/main/java/org/apache/commons/rdf/api/BlankNode.java index 0239416..eafef52 100644 --- a/api/src/main/java/org/apache/commons/rdf/api/BlankNode.java +++ b/api/src/main/java/org/apache/commons/rdf/api/BlankNode.java @@ -24,13 +24,13 @@ import java.util.UUID; * Blank Node</a>, as defined by <a href= * "http://www.w3.org/TR/rdf11-concepts/#section-blank-nodes"; >RDF-1.1 Concepts * and Abstract Syntax</a>, a W3C Recommendation published on 25 February 2014.<br> - * + * * Note: <blockquote> <a * href="http://www.w3.org/TR/rdf11-concepts/#dfn-blank-node";>Blank nodes</a> * are disjoint from IRIs and literals. Otherwise, the set of possible blank * nodes is arbitrary. RDF makes no reference to any internal structure of blank * nodes. </blockquote> - * + * * Also note that: <blockquote> <a * href="http://www.w3.org/TR/rdf11-concepts/#dfn-blank-node-identifier";>Blank * node identifiers</a> are local identifiers that are used in some concrete RDF @@ -41,28 +41,17 @@ import java.util.UUID; * 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 #internalIdentifier()}. + * + * @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> */ @@ -71,15 +60,12 @@ 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. - * + * label</a> for the blank node. + * <p> + * The internal identifier string MUST be universally unique, and + * SHOULD contain a UUID string. The UUID, if present, MUST be + * universally unique across JVM runs and {@link RDFTermFactory} instances. + * <p> * 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 @@ -109,7 +95,7 @@ public interface BlankNode extends BlankNodeOrIRI { /** * Calculate a hash code for this BlankNode. - * + * * This method MUST be implemented in conjunction with * {@link #equals(Object)} so that two equal BlankNodes produce the same * hash code. http://git-wip-us.apache.org/repos/asf/incubator-commonsrdf/blob/5ec5230b/api/src/main/java/org/apache/commons/rdf/api/RDFTermFactory.java ---------------------------------------------------------------------- diff --git a/api/src/main/java/org/apache/commons/rdf/api/RDFTermFactory.java b/api/src/main/java/org/apache/commons/rdf/api/RDFTermFactory.java index 5189bee..3bbe4de 100644 --- a/api/src/main/java/org/apache/commons/rdf/api/RDFTermFactory.java +++ b/api/src/main/java/org/apache/commons/rdf/api/RDFTermFactory.java @@ -29,7 +29,7 @@ import java.util.UUID; * additional parameters or can't create graphs), then it MAY throw * UnsupportedOperationException, as provided by the default implementations * here. - * + * * If a factory method does not allow or support a provided parameter, e.g. * because an IRI is considered invalid, then it SHOULD throw * IllegalArgumentException. @@ -41,10 +41,10 @@ public interface RDFTermFactory { /** * Create a new blank node. - * + * <p> * All pairs of {@link BlankNode}s created with this method MUST NOT be * equal. - * + * <p> * If supported, the {@link BlankNode#internalIdentifier()} of the returned * blank node MUST be a universally unique value across both this and any * other {@link RDFTermFactory} objects running in the JVM when compared @@ -61,31 +61,34 @@ public interface RDFTermFactory { /** * Create a blank node based on the given identifier. - * - * All BlankNodes created using this method with the same parameter for a - * single instance of RDFTermFactory MUST be equivalent. Ie, - * {@link BlankNode#equals(Object)} MUST return true. 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 BlankNode#internalIdentifier()}. - * + * <p> + * For a single instance of RDFTermFactory, all BlankNodes created using + * this method with the same <code>identifier</code> parameter MUST be + * equivalent according to {@link BlankNode#equals(Object)}, The returned + * BlankNode MUST NOT be equal to any other BlankNode objects from + * {@link #createBlankNode(String)} with a different <code>identifier</code> + * parameter. + * <p> + * BlankNodes created on a different RDFTermFactory instance using this + * method SHOULD NOT be equivalent. + * <p> * A BlankNode object created through the - * {@link RDFTermFactory#createBlankNode(String)} method must be universally - * unique, but also produce the same {@link BlankNode#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 BlankNode#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. - * - * BlankNodes created using this method with the same parameter, for - * different instances of RDFTermFactory, SHOULD NOT be equivalent. - * - * @param identifier A non-empty, non-null, String that is unique to this blank - * node in the context of this {@link RDFTermFactory}. + * {@link RDFTermFactory#createBlankNode(String)} method MUST produce the + * same {@link BlankNode#internalIdentifier()} as any previous or future + * calls to this method <b>on that factory instance</b> with the same + * <code>identifier</code> parameter. + * <p> + * The returned blank node SHOULD contain a {@link UUID} string as part of + * its {@link BlankNode#internalIdentifier()}, which MUST be universally + * unique across factory instances and JVM runs (e.g. created using + * {@link UUID#randomUUID()} per factory instance). + * + * @param identifier + * A non-empty, non-null, String that is unique to this blank + * node in the context of this {@link RDFTermFactory}. * @return A BlankNode for the given identifier - * @throws UnsupportedOperationException If the operation is not supported. + * @throws UnsupportedOperationException + * If the operation is not supported. */ default BlankNode createBlankNode(String identifier) throws UnsupportedOperationException {
