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