You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@commonsrdf.apache.org by st...@apache.org on 2015/04/29 12:00:26 UTC
[02/13] incubator-commonsrdf git commit: COMMONSRDF-6 Make
BlankNode.internalIdentifier generic
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 {