commonsrdf-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From st...@apache.org
Subject [02/13] incubator-commonsrdf git commit: COMMONSRDF-6 Make BlankNode.internalIdentifier generic
Date Wed, 29 Apr 2015 10:00:26 GMT
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 <stain@apache.org>
Authored: Tue Apr 21 10:51:59 2015 +0100
Committer: Stian Soiland-Reyes <stain@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 {


Mime
View raw message