Return-Path: X-Original-To: apmail-commonsrdf-commits-archive@minotaur.apache.org Delivered-To: apmail-commonsrdf-commits-archive@minotaur.apache.org Received: from mail.apache.org (hermes.apache.org [140.211.11.3]) by minotaur.apache.org (Postfix) with SMTP id 206FF18314 for ; Wed, 29 Apr 2015 10:26:24 +0000 (UTC) Received: (qmail 46552 invoked by uid 500); 29 Apr 2015 10:26:24 -0000 Delivered-To: apmail-commonsrdf-commits-archive@commonsrdf.apache.org Received: (qmail 46524 invoked by uid 500); 29 Apr 2015 10:26:24 -0000 Mailing-List: contact commits-help@commonsrdf.incubator.apache.org; run by ezmlm Precedence: bulk List-Help: List-Unsubscribe: List-Post: List-Id: Reply-To: dev@commonsrdf.incubator.apache.org Delivered-To: mailing list commits@commonsrdf.incubator.apache.org Received: (qmail 46515 invoked by uid 99); 29 Apr 2015 10:26:24 -0000 Received: from athena.apache.org (HELO athena.apache.org) (140.211.11.136) by apache.org (qpsmtpd/0.29) with ESMTP; Wed, 29 Apr 2015 10:26:24 +0000 X-ASF-Spam-Status: No, hits=-0.0 required=5.0 tests=SPF_PASS X-Spam-Check-By: apache.org Received-SPF: pass (athena.apache.org: local policy) Received: from [54.191.145.13] (HELO mx1-us-west.apache.org) (54.191.145.13) by apache.org (qpsmtpd/0.29) with ESMTP; Wed, 29 Apr 2015 10:26:18 +0000 Received: from mail.apache.org (hermes.apache.org [140.211.11.3]) by mx1-us-west.apache.org (ASF Mail Server at mx1-us-west.apache.org) with SMTP id 8D6DA284BF for ; Wed, 29 Apr 2015 10:22:19 +0000 (UTC) Received: (qmail 74011 invoked by uid 99); 29 Apr 2015 10:00:25 -0000 Received: from git1-us-west.apache.org (HELO git1-us-west.apache.org) (140.211.11.23) by apache.org (qpsmtpd/0.29) with ESMTP; Wed, 29 Apr 2015 10:00:25 +0000 Received: by git1-us-west.apache.org (ASF Mail Server at git1-us-west.apache.org, from userid 33) id 2D507E0215; Wed, 29 Apr 2015 10:00:25 +0000 (UTC) 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:26 -0000 Message-Id: <79f839e0684543b09834a5125723f245@git.apache.org> In-Reply-To: <0313764916064705b1cb61d8a2e9f8e4@git.apache.org> References: <0313764916064705b1cb61d8a2e9f8e4@git.apache.org> X-Mailer: ASF-Git Admin Mailer Subject: [02/13] incubator-commonsrdf git commit: COMMONSRDF-6 Make BlankNode.internalIdentifier generic X-Virus-Checked: Checked by ClamAV on apache.org 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 Authored: Tue Apr 21 10:51:59 2015 +0100 Committer: Stian Soiland-Reyes 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, as defined by RDF-1.1 Concepts * and Abstract Syntax, a W3C Recommendation published on 25 February 2014.
- * + * * Note:
Blank nodes * 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.
- * + * * Also note that:
Blank * node identifiers 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.
- * - * 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 RDF-1.1 * Blank Node */ @@ -71,15 +60,12 @@ public interface BlankNode extends BlankNodeOrIRI { /** * Return a unique - * label 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 for the blank node. + *

+ * 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. + *

* 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. - * + *

* All pairs of {@link BlankNode}s created with this method MUST NOT be * equal. - * + *

* 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()}. - * + *

+ * For a single instance of RDFTermFactory, all BlankNodes created using + * this method with the same identifier 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 identifier + * parameter. + *

+ * BlankNodes created on a different RDFTermFactory instance using this + * method SHOULD NOT be equivalent. + *

* 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 on that factory instance with the same + * identifier parameter. + *

+ * 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 {