COMMONSRDF-6 internalIdentifier() refs moved out of factory .. and clarify uniqueness aspects.
Project: http://git-wip-us.apache.org/repos/asf/incubator-commonsrdf/repo Commit: http://git-wip-us.apache.org/repos/asf/incubator-commonsrdf/commit/0a18effd Tree: http://git-wip-us.apache.org/repos/asf/incubator-commonsrdf/tree/0a18effd Diff: http://git-wip-us.apache.org/repos/asf/incubator-commonsrdf/diff/0a18effd Branch: refs/heads/master Commit: 0a18effd0ea9939e9445dcbada7721b3cea9ad0e Parents: be2e079 Author: Stian Soiland-Reyes <st...@apache.org> Authored: Fri Apr 24 11:43:14 2015 +0100 Committer: Stian Soiland-Reyes <st...@apache.org> Committed: Fri Apr 24 11:43:14 2015 +0100 ---------------------------------------------------------------------- .../org/apache/commons/rdf/api/BlankNode.java | 31 +++++++----- .../apache/commons/rdf/api/RDFTermFactory.java | 52 +++++++------------- 2 files changed, 37 insertions(+), 46 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/incubator-commonsrdf/blob/0a18effd/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 eafef52..52c472d 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 @@ -58,22 +58,27 @@ import java.util.UUID; 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. + * Return a reference for uniquely identifying 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. + * 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. * <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 - * other syntaxes, the result of this method must be sanitized to produce a - * valid concrete identifier if one is needed. + * The {@link #internalIdentifier()} of two <code>BlankNode</code> instances + * MUST be equal if and only if the two blank nodes are equal according to + * {@link #equals(Object)}. + * <p> + * This method does not specify any specific structure of the reference + * string, except that the reference SHOULD be (or contain) a {@link UUID} + * string. + * <p> + * <strong>IMPORTANT:</strong> This is not a <a + * href="http://www.w3.org/TR/rdf11-concepts/#dfn-blank-node-identifier";> + * blank node identifier</a> nor a serialization/syntax label, and there are + * no guarantees that it is a valid identifier in any concrete RDF syntax. + * For an N-Triples compatible identifier, use {@link #ntriplesString()}. * - * @return An internal, system identifier for the {@link BlankNode} that is - * used primarily to check whether two BlankNode's are equivalent. + * @return A universally unique reference to identify this {@link BlankNode} */ String internalIdentifier(); http://git-wip-us.apache.org/repos/asf/incubator-commonsrdf/blob/0a18effd/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 3bbe4de..176a704 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 @@ -18,7 +18,6 @@ package org.apache.commons.rdf.api; import java.util.Locale; -import java.util.UUID; /** * Factory for creating RDFTerm and Graph instances. @@ -42,17 +41,12 @@ 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 - * with both past and future calls both to this method, and calls to - * {@link #createBlankNode(String)} with any inputs. + * The returned blank node MUST NOT be equal to any existing + * {@link BlankNode} instances according to {@link BlankNode#equals(Object)}. * - * @return A new {@link BlankNode} - * @throws UnsupportedOperationException If the operation is not supported. + * @return A new, unique {@link BlankNode} + * @throws UnsupportedOperationException + * If the operation is not supported. */ default BlankNode createBlankNode() throws UnsupportedOperationException { throw new UnsupportedOperationException( @@ -60,37 +54,29 @@ public interface RDFTermFactory { } /** - * Create a blank node based on the given identifier. - * <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. + * Create a blank node based on the given name. * <p> - * BlankNodes created on a different RDFTermFactory instance using this - * method SHOULD NOT be equivalent. + * For a particular instance of <code>RDFTermFactory</code>, all + * {@link BlankNode}s created using this method with the same + * <code>name</code> parameter MUST be equivalent according to + * {@link BlankNode#equals(Object)}, * <p> - * A BlankNode object created through the - * {@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. + * The returned BlankNode MUST NOT be equal to any other + * <code>BlankNode</code> instances returned from this instance. * <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). + * The returned BlankNode SHOULD NOT be equivalent to any BlankNodes created + * on a <em>different</em> <code>RDFTermFactory</code> instance, e.g. + * different instances of <code>RDFTermFactory</code> should produce + * different blank nodes for the same <code>name</code>. * - * @param identifier + * @param name * 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 + * @return A BlankNode for the given name * @throws UnsupportedOperationException * If the operation is not supported. */ - default BlankNode createBlankNode(String identifier) + default BlankNode createBlankNode(String name) throws UnsupportedOperationException { throw new UnsupportedOperationException( "createBlankNode(String) not supported");
