You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@commonsrdf.apache.org by an...@apache.org on 2015/03/30 03:09:56 UTC

[02/18] incubator-commonsrdf git commit: Rewrite contracts relating to BlankNode to be based on RDFTermFactory objects

Rewrite contracts relating to BlankNode to be based on RDFTermFactory
objects

Project: http://git-wip-us.apache.org/repos/asf/incubator-commonsrdf/repo
Commit: http://git-wip-us.apache.org/repos/asf/incubator-commonsrdf/commit/243e85c4
Tree: http://git-wip-us.apache.org/repos/asf/incubator-commonsrdf/tree/243e85c4
Diff: http://git-wip-us.apache.org/repos/asf/incubator-commonsrdf/diff/243e85c4

Branch: refs/heads/master
Commit: 243e85c4ce679eb06e6ba00e55e7789e36025fe3
Parents: 9522337
Author: Peter Ansell <p_...@yahoo.com>
Authored: Sat Mar 28 20:22:29 2015 +1100
Committer: Peter Ansell <p_...@yahoo.com>
Committed: Sat Mar 28 20:22:29 2015 +1100

----------------------------------------------------------------------
 .../org/apache/commons/rdf/api/BlankNode.java   | 142 ++++++++-----------
 .../apache/commons/rdf/api/RDFTermFactory.java  |  59 +++++---
 .../apache/commons/rdf/simple/GraphImpl.java    |  30 ++--
 .../rdf/simple/SimpleRDFTermFactory.java        |   7 +-
 4 files changed, 115 insertions(+), 123 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/incubator-commonsrdf/blob/243e85c4/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 ff29d0b..ca6d198 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
@@ -17,39 +17,51 @@
  */
 package org.apache.commons.rdf.api;
 
+import java.util.UUID;
+
 /**
  * A <a href= "http://www.w3.org/TR/rdf11-concepts/#dfn-blank-node" >RDF-1.1
  * 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>
  * <p>
- * 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>
+ * 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>
  * <p>
- * 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 syntaxes or RDF store implementations. They are always
- * <em>locally scoped</em> to the file or RDF store, and are <em>not</em> persistent 
- * or portable
- * identifiers for blank nodes. Blank node identifiers are <em>not</em> 
- * part of the RDF
- * abstract syntax, but are entirely dependent on the concrete syntax or
+ * 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
+ * syntaxes or RDF store implementations. They are always
+ * <em>locally scoped</em> to the file or RDF store, and are <em>not</em>
+ * persistent or portable identifiers for blank nodes. Blank node identifiers
+ * are <em>not</em> part of the RDF abstract syntax, but are entirely dependent
+ * 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.
- * The syntactic restrictions on blank node identifiers, if any,
- * therefore also depend on the concrete RDF syntax or implementation.
  * <p>
  * 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>
+ * by the syntax. </blockquote>
+ * <p>
+ * 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()}.
+ * <p>
+ * 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.
+ * <p>
  *
  * @see <a href="http://www.w3.org/TR/rdf11-concepts/#dfn-blank-node">RDF-1.1
  *      Blank Node</a>
@@ -58,80 +70,42 @@ public interface BlankNode extends BlankNodeOrIRI {
 
 	/**
 	 * Return a <a href=
-	 * "http://www.w3.org/TR/rdf11-concepts/#dfn-blank-node-identifier"
-	 * >label</a> for the blank node. This is not a serialization/syntax label.
-	 * It should be uniquely identifying within the local scope it is created in
-	 * but has no uniqueness guarantees other than that.
+	 * "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.
 	 * <p>
-	 * In particular, the existence of two objects of type {@link BlankNode}
-	 * with the same value returned from {@link #internalIdentifier()} are not
-	 * equivalent unless they are known to have been created in the same local
-	 * scope (see {@link #equals(Object)})
+	 * 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.
 	 * <p>
-	 * An example of a local scope may be an instance of a Java Virtual Machine
-	 * (JVM). In the context of a JVM instance, an implementor may support
-	 * insertion and removal of {@link Triple} objects containing Blank Nodes
-	 * without modifying the blank node labels.
-	 * <p>
-	 * Another example of a local scope may be a <a
-	 * href="http://www.w3.org/TR/rdf11-concepts/#section-rdf-graph">Graph</a>
-	 * or <a
-	 * href="http://www.w3.org/TR/rdf11-concepts/#section-dataset">Dataset</a>
-	 * created from a single document. In this context, an implementor should
-	 * reasonably guarantee that the label returned by getLabel only maps to
-	 * equivalent blank nodes in the same Graph or Dataset, but they may not
-	 * guarantee that it is unique for the JVM instance. In this case, the
-	 * implementor may support a mechanism to provide a mapping for blank nodes
-	 * between Graph or Dataset instances to guarantee their uniqueness.
-	 * <p>
-	 * If implementors support <a
-	 * href="http://www.w3.org/TR/rdf11-concepts/#section-skolemization"
-	 * >Skolemisation</a>, they may map instances of {@link BlankNode} objects
-	 * to {@link IRI} objects to reduce scoping issues.
-	 * <p>
-	 * It is not a requirement for the internal identifier to be a part of the
-	 * {@link #ntriplesString()}, except that two BlankNode instances with the
-	 * same internalIdentifier() and same local scope should have the same
-	 * {@link #ntriplesString()}.
-	 *
-	 * @return An internal, system identifier for the {@link BlankNode}.
+	 * 
+	 * @return An internal, system identifier for the {@link BlankNode} that is
+	 *         used primarily to check whether two BlankNode's are equivalent.
 	 */
 	String internalIdentifier();
 
 	/**
-	 * Check it this BlankNode is equal to another BlankNode. <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 syntaxes or RDF store implementations. They are always locally scoped
-	 * to the file or RDF store, and are <em>not</em> persistent or portable
-	 * identifiers for blank nodes. Blank node identifiers are <em>not</em> part
-	 * of the RDF abstract syntax, but are entirely dependent 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. 
-	 * <p>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>
-	 * <p>
-	 * Implementations MUST check the local scope, as two BlankNode in different
-	 * Graphs MUST differ. On the other hand, two BlankNodes found in triples of
-	 * the same Graph instance MUST equal if and only if they have the same
-	 * {@link #internalIdentifier()}.
-	 * </p>
+	 * Check it this BlankNode is equal to another BlankNode. Two BlankNodes
+	 * MUST be equal if, and only if, they have the same
+	 * {@link #internalIdentifier()}. </p>
 	 * <p>
 	 * Implementations MUST also override {@link #hashCode()} so that two equal
 	 * Literals produce the same hash code.
 	 * </p>
 	 * 
-	 * @see Object#equals(Object)
-	 * 
 	 * @param other
 	 *            Another object
 	 * @return true if other is a BlankNode, is in the same local scope and is
 	 *         equal to this BlankNode
+	 * @see Object#equals(Object)
 	 */
 	@Override
 	public boolean equals(Object other);
@@ -139,12 +113,12 @@ public interface BlankNode extends BlankNodeOrIRI {
 	/**
 	 * Calculate a hash code for this BlankNode.
 	 * <p>
-	 * This method MUST be implemented when implementing {@link #equals(Object)}
-	 * so that two equal BlankNodes produce the same hash code.
-	 * 
-	 * @see Object#hashCode()
+	 * This method MUST be implemented in conjunction with
+	 * {@link #equals(Object)} so that two equal BlankNodes produce the same
+	 * hash code.
 	 * 
 	 * @return a hash code value for this BlankNode.
+	 * @see Object#hashCode()
 	 */
 	@Override
 	public int hashCode();

http://git-wip-us.apache.org/repos/asf/incubator-commonsrdf/blob/243e85c4/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 e0a64ff..3cbd430 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,6 +18,7 @@
 package org.apache.commons.rdf.api;
 
 import java.util.Locale;
+import java.util.UUID;
 
 /**
  * Factory for creating RDFTerm and Graph instances.
@@ -33,7 +34,6 @@ import java.util.Locale;
  * because an IRI is considered invalid, then it SHOULD throw
  * IllegalArgumentException.
  * 
- * 
  * @see RDFTerm
  * @see Graph
  * 
@@ -43,12 +43,16 @@ public interface RDFTermFactory {
 	/**
 	 * Create a new blank node.
 	 * <p>
-	 * Two BlankNodes created with this method MUST NOT be equal.
+	 * 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 an auto-generated value.
+	 * 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.
 	 * 
-	 * @return A new BlankNode
+	 * @return A new {@link BlankNode}
 	 * @throws UnsupportedOperationException
 	 *             If the operation is not supported.
 	 */
@@ -58,28 +62,37 @@ public interface RDFTermFactory {
 	}
 
 	/**
-	 * Create a blank node for the given internal identifier.
+	 * Create a blank node based on the given identifier.
 	 * <p>
-	 * Two BlankNodes created with the same identifier using this method MUST be
-	 * equal if they are in the same local scope (e.g. in the same Graph). See
-	 * the equals contract for {@link BlankNode} for more information.
+	 * 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 #internalIdentifier()}.
 	 * <p>
-	 * If supported, the {@link BlankNode#internalIdentifier()} of the returned
-	 * blank node MAY be equal to the provided identifier.
+	 * 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.
+	 * <p>
+	 * BlankNodes created using this method with the same parameter, for
+	 * different instances of RDFTermFactory, SHOULD NOT be equivalent.
 	 * 
 	 * @param identifier
-	 *            A non-empty String that is unique to this blank node in this
-	 *            scope, and which may be used as the internal identifier for
-	 *            the blank node.
+	 *            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 IllegalArgumentException
-	 *             if the identifier is not acceptable, e.g. was empty or
-	 *             contained unsupported characters.
 	 * @throws UnsupportedOperationException
 	 *             If the operation is not supported.
 	 */
 	default BlankNode createBlankNode(String identifier)
-			throws IllegalArgumentException, UnsupportedOperationException {
+			throws UnsupportedOperationException {
 		throw new UnsupportedOperationException(
 				"createBlankNode(String) not supported");
 	}
@@ -89,6 +102,11 @@ public interface RDFTermFactory {
 	 * <p>
 	 * It is undefined if the graph will be persisted by any underlying storage
 	 * mechanism.
+	 * <p>
+	 * {@link BlankNode} objects added to the {@link Graph} returned from this
+	 * method SHOULD be mapped using the {@link #createBlankNode(String)} of
+	 * this factory, called using the {@link BlankNode#internalIdentifier()} as
+	 * the parameter, before they are inserted into the Graph.
 	 * 
 	 * @return A new Graph
 	 * @throws UnsupportedOperationException
@@ -164,8 +182,9 @@ public interface RDFTermFactory {
 	 * <p>
 	 * The returned Literal SHOULD have a {@link Literal#getLexicalForm()} that
 	 * is equal to the provided lexicalForm, MUST NOT have a
-	 * {@link Literal#getLanguageTag()} present, and SHOULD return a
-	 * {@link Literal#getDatatype()} that is equal to the provided dataType IRI.
+	 * {@link Literal#getLanguageTag()} present, and MUST return a
+	 * {@link Literal#getDatatype()} that is equivalent to the provided dataType
+	 * IRI.
 	 * 
 	 * @param lexicalForm
 	 *            The literal value
@@ -204,7 +223,7 @@ public interface RDFTermFactory {
 	 * <code>http://www.w3.org/1999/02/22-rdf-syntax-ns#langString</code>, and
 	 * MUST have a {@link Literal#getLanguageTag()} present which SHOULD be
 	 * equal to the provided language tag (compared as
-	 * {@link String#toLowerCase(Locale)} in {@link Locale#ENGLISH}).
+	 * {@link String#toLowerCase(Locale)} using {@link Locale#ENGLISH}).
 	 * 
 	 * @param lexicalForm
 	 *            The literal value

http://git-wip-us.apache.org/repos/asf/incubator-commonsrdf/blob/243e85c4/simple/src/main/java/org/apache/commons/rdf/simple/GraphImpl.java
----------------------------------------------------------------------
diff --git a/simple/src/main/java/org/apache/commons/rdf/simple/GraphImpl.java b/simple/src/main/java/org/apache/commons/rdf/simple/GraphImpl.java
index 81bbcee..3fd4bca 100644
--- a/simple/src/main/java/org/apache/commons/rdf/simple/GraphImpl.java
+++ b/simple/src/main/java/org/apache/commons/rdf/simple/GraphImpl.java
@@ -44,6 +44,11 @@ final class GraphImpl implements Graph {
 
 	private static final int TO_STRING_MAX = 10;
 	private final Set<Triple> triples = new LinkedHashSet<Triple>();
+	private final SimpleRDFTermFactory factory;
+
+	GraphImpl(SimpleRDFTermFactory simpleRDFTermFactory) {
+		this.factory = simpleRDFTermFactory;
+	}
 
 	@Override
 	public void add(BlankNodeOrIRI subject, IRI predicate, RDFTerm object) {
@@ -60,37 +65,34 @@ final class GraphImpl implements Graph {
 			// this graph will generate a local object that is mapped to an
 			// equivalent object, based on the code in the package private
 			// BlankNodeImpl class
-			return new BlankNodeImpl(this, blankNode.internalIdentifier());
+			return factory.createBlankNode(blankNode.internalIdentifier());
 		} else if (object instanceof IRI && !(object instanceof IRIImpl)) {
 			IRI iri = (IRI) object;
-			return new IRIImpl(iri.getIRIString());
+			return factory.createIRI(iri.getIRIString());
 		} else if (object instanceof Literal
 				&& !(object instanceof LiteralImpl)) {
 			Literal literal = (Literal) object;
 			if (literal.getLanguageTag().isPresent()) {
-				return new LiteralImpl(literal.getLexicalForm(), literal
+				return factory.createLiteral(literal.getLexicalForm(), literal
 						.getLanguageTag().get());
 			} else {
-				return new LiteralImpl(literal.getLexicalForm(),
+				return factory.createLiteral(literal.getLexicalForm(),
 						(IRI) internallyMap(literal.getDatatype()));
 			}
 		} else {
+			// The object is a local implementation, and is not a BlankNode, so
+			// can be returned directly
 			return object;
 		}
 	}
 
 	@Override
 	public void add(Triple triple) {
-		if (!(triple instanceof TripleImpl)) {
-			BlankNodeOrIRI subject = (BlankNodeOrIRI) internallyMap(triple
-					.getSubject());
-			IRI predicate = (IRI) internallyMap(triple.getPredicate());
-			RDFTerm object = internallyMap(triple.getObject());
-			triples.add(new TripleImpl(subject, predicate, object));
-		} else {
-			triples.add(new TripleImpl(triple.getSubject(), triple
-					.getPredicate(), triple.getObject()));
-		}
+		BlankNodeOrIRI subject = (BlankNodeOrIRI) internallyMap(triple
+				.getSubject());
+		IRI predicate = (IRI) internallyMap(triple.getPredicate());
+		RDFTerm object = internallyMap(triple.getObject());
+		triples.add(factory.createTriple(subject, predicate, object));
 	}
 
 	@Override

http://git-wip-us.apache.org/repos/asf/incubator-commonsrdf/blob/243e85c4/simple/src/main/java/org/apache/commons/rdf/simple/SimpleRDFTermFactory.java
----------------------------------------------------------------------
diff --git a/simple/src/main/java/org/apache/commons/rdf/simple/SimpleRDFTermFactory.java b/simple/src/main/java/org/apache/commons/rdf/simple/SimpleRDFTermFactory.java
index d7a1c1f..471af67 100644
--- a/simple/src/main/java/org/apache/commons/rdf/simple/SimpleRDFTermFactory.java
+++ b/simple/src/main/java/org/apache/commons/rdf/simple/SimpleRDFTermFactory.java
@@ -17,8 +17,6 @@
  */
 package org.apache.commons.rdf.simple;
 
-import java.util.Optional;
-
 import org.apache.commons.rdf.api.BlankNode;
 import org.apache.commons.rdf.api.BlankNodeOrIRI;
 import org.apache.commons.rdf.api.Graph;
@@ -34,7 +32,6 @@ import org.apache.commons.rdf.api.Triple;
  * The {@link RDFTerm} and {@link Graph} instances created by this factory are
  * simple in-memory Implementations that are not thread-safe or efficient, but
  * which may be useful for testing and prototyping purposes.
- *
  */
 public class SimpleRDFTermFactory implements RDFTermFactory {
 
@@ -45,12 +42,12 @@ public class SimpleRDFTermFactory implements RDFTermFactory {
 
 	@Override
 	public BlankNode createBlankNode(String identifier) {
-		return new BlankNodeImpl(Optional.empty(), identifier);
+		return new BlankNodeImpl(this, identifier);
 	}
 
 	@Override
 	public Graph createGraph() {
-		return new GraphImpl();
+		return new GraphImpl(this);
 	}
 
 	@Override