Mailing-List: contact commits-help@commonsrdf.incubator.apache.org;
 run by ezmlm
Precedence: bulk
Reply-To: dev@commonsrdf.incubator.apache.org
Received-SPF: pass (nike.apache.org: domain of root@apache.org designates
 54.76.25.247 as permitted sender)
Content-Type: text/plain; charset="us-ascii"
MIME-Version: 1.0
Content-Transfer-Encoding: 7bit
From: stain@apache.org
To: commits@commonsrdf.incubator.apache.org
Date: Wed, 29 Apr 2015 10:00:27 -0000
Message-Id: <8d34cfe67047432485b633c0db1b5791@git.apache.org>
In-Reply-To: <0313764916064705b1cb61d8a2e9f8e4@git.apache.org>
References: <0313764916064705b1cb61d8a2e9f8e4@git.apache.org>
Subject: [03/13] incubator-commonsrdf git commit: COMMONSRDF-6
 internalIdentifier() refs moved out of factory

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 <stain@apache.org>
Authored: Fri Apr 24 11:43:14 2015 +0100
Committer: Stian Soiland-Reyes <stain@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");