commonsrdf-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From st...@apache.org
Subject [2/5] incubator-commonsrdf git commit: rdf4j javadoc improvements
Date Mon, 20 Jun 2016 11:29:38 GMT
rdf4j javadoc improvements


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

Branch: refs/heads/rdf4j
Commit: 5709ab23539b3542634a8ecfb2e63f9fe3a71966
Parents: 9209b0c
Author: Stian Soiland-Reyes <stain@apache.org>
Authored: Mon Jun 20 10:46:03 2016 +0100
Committer: Stian Soiland-Reyes <stain@apache.org>
Committed: Mon Jun 20 11:06:31 2016 +0100

----------------------------------------------------------------------
 .../apache/commons/rdf/rdf4j/RDF4JGraph.java    |  28 ++--
 .../org/apache/commons/rdf/rdf4j/RDF4JTerm.java |   5 +-
 .../commons/rdf/rdf4j/RDF4JTermFactory.java     | 144 ++++++++++++++++---
 .../apache/commons/rdf/rdf4j/package-info.java  |  26 ++++
 4 files changed, 175 insertions(+), 28 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/incubator-commonsrdf/blob/5709ab23/rdf4j/src/main/java/org/apache/commons/rdf/rdf4j/RDF4JGraph.java
----------------------------------------------------------------------
diff --git a/rdf4j/src/main/java/org/apache/commons/rdf/rdf4j/RDF4JGraph.java b/rdf4j/src/main/java/org/apache/commons/rdf/rdf4j/RDF4JGraph.java
index f328be1..396a39b 100644
--- a/rdf4j/src/main/java/org/apache/commons/rdf/rdf4j/RDF4JGraph.java
+++ b/rdf4j/src/main/java/org/apache/commons/rdf/rdf4j/RDF4JGraph.java
@@ -23,7 +23,9 @@ import org.apache.commons.rdf.api.Graph;
 import org.apache.commons.rdf.api.Triple;
 import org.apache.commons.rdf.rdf4j.impl.ModelGraphImpl;
 import org.apache.commons.rdf.rdf4j.impl.RepositoryGraphImpl;
+import org.eclipse.rdf4j.model.Model;
 import org.eclipse.rdf4j.model.Resource;
+import org.eclipse.rdf4j.repository.Repository;
 
 
 /**
@@ -37,23 +39,27 @@ public interface RDF4JGraph extends Graph, RDF4JGraphLike<Triple>
{
 	/**
 	 * Return a copy of the context filter, if present.
 	 * <p>
-	 * If {@link Optional#isPresent()}, the filter determines which contexts
-	 * this graph reflect. Modifications to the graph (e.g. {@link #add(Triple)
-	 * will be performed for all the specified contexts, while retrieval (e.g.
-	 * {@link #contains(Triple)}) will succeed if the triple is in at least one
-	 * of the specified contexts.
+	 * If {@link Optional#isPresent()}, the filter determines which
+	 * <em>contexts</em> in the corresponding RDF4J {@link Model} or
+	 * {@link Repository} that this graph reflect. Modifications to the graph
+	 * (e.g. {@link #add(Triple)} will be performed for all the specified
+	 * contexts, while retrieval (e.g. {@link #contains(Triple)}) will succeed
+	 * if the triple is in at least one of the specified contexts.
 	 * <p>
 	 * The context filter array may contain <code>null</code>, indicating the
 	 * default context (the <em>default graph</em> in RDF datasets).
 	 * <p>
-	 * If the context filter is {@link Optional#empty()}, then this is a union
-	 * graph which triples reflecting statements in any contexts. Triples added
-	 * to the graph will be added in the default context <code>null</code>.
+	 * If the context filter is {@link Optional#empty()}, then this is a
+	 * <em>union graph</em> which triples reflecting statements in any contexts.
+	 * Triples added to the graph will be added in the default context
+	 * <code>null</code>.
 	 * <p>
-	 * The returned filter is a copy and thus any modifications are not
-	 * reflected in the RDF4JGraph.
+	 * The filter array is a copy, and thus any modifications are not reflected
+	 * in the RDF4JGraph.
 	 * 
-	 * @return
+	 * @return The context filter as an array of {@link Resource}s, or
+	 *         {@link Optional#empty()} indicating the union graph (any
+	 *         context).
 	 */
 	public Optional<Resource[]> getContextFilter();
 	

http://git-wip-us.apache.org/repos/asf/incubator-commonsrdf/blob/5709ab23/rdf4j/src/main/java/org/apache/commons/rdf/rdf4j/RDF4JTerm.java
----------------------------------------------------------------------
diff --git a/rdf4j/src/main/java/org/apache/commons/rdf/rdf4j/RDF4JTerm.java b/rdf4j/src/main/java/org/apache/commons/rdf/rdf4j/RDF4JTerm.java
index 3117eee..7128b48 100644
--- a/rdf4j/src/main/java/org/apache/commons/rdf/rdf4j/RDF4JTerm.java
+++ b/rdf4j/src/main/java/org/apache/commons/rdf/rdf4j/RDF4JTerm.java
@@ -18,6 +18,9 @@
 package org.apache.commons.rdf.rdf4j;
 
 import org.apache.commons.rdf.api.RDFTerm;
+import org.eclipse.rdf4j.model.BNode;
+import org.eclipse.rdf4j.model.IRI;
+import org.eclipse.rdf4j.model.Literal;
 import org.eclipse.rdf4j.model.Value;
 
 /**
@@ -29,7 +32,7 @@ public interface RDF4JTerm<T extends Value> extends RDFTerm {
 	/**
 	 * Return the RDF4J {@link Value} that this RDFTerm represents.
 	 * 
-	 * @return
+	 * @return The wrapped {@link Value} (e.g. a {@link Literal}, {@link IRI} or {@link BNode}.
 	 */
 	public T asValue();
 }

http://git-wip-us.apache.org/repos/asf/incubator-commonsrdf/blob/5709ab23/rdf4j/src/main/java/org/apache/commons/rdf/rdf4j/RDF4JTermFactory.java
----------------------------------------------------------------------
diff --git a/rdf4j/src/main/java/org/apache/commons/rdf/rdf4j/RDF4JTermFactory.java b/rdf4j/src/main/java/org/apache/commons/rdf/rdf4j/RDF4JTermFactory.java
index 2cd64e7..55a8046 100644
--- a/rdf4j/src/main/java/org/apache/commons/rdf/rdf4j/RDF4JTermFactory.java
+++ b/rdf4j/src/main/java/org/apache/commons/rdf/rdf4j/RDF4JTermFactory.java
@@ -54,7 +54,7 @@ import org.eclipse.rdf4j.repository.Repository;
  * <p>
  * The {@link #RDF4JTermFactory()} constructor uses a {@link SimpleValueFactory}
  * to create corresponding RDF4J {@link Value} instances. Alternatively, this
- * factory can be constructed with a {@link ValueFactory} using
+ * factory can be constructed with a different {@link ValueFactory} using
  * {@link #RDF4JTermFactory(ValueFactory)}.
  * <p>
  * {@link #asRDFTerm(Value)} can be used to convert any RDF4J {@link Value} to
@@ -65,13 +65,37 @@ import org.eclipse.rdf4j.repository.Repository;
  * {@link #createGraph()} creates a new Graph backed by {@link LinkedHashModel}.
  * To use other models, see {@link #asRDFTermGraph(Model)}.
  * <p>
+ * To adapt a RDF4J {@link Repository} as a {@link Dataset} or {@link Graph},
+ * use {@link #asRDFTermDataset(Repository)} or
+ * {@link #asRDFTermGraph(Repository)}.
+ * <p>
  * {@link #asTriple(Statement)} can be used to convert a RDF4J {@link Statement}
- * to a Commons RDF {@link Triple}.
+ * to a Commons RDF {@link Triple}, and equivalent {@link #asQuad(Statement)} to
+ * convert a {@link Quad}.
+ * <p>
+ * To convert any {@link Triple} or {@link Quad} to to RDF4J {@link Statement},
+ * use {@link #asStatement(TripleLike)}. This recognises previously converted
+ * {@link RDF4JTriple}s and {@link RDF4JQuad}s without re-converting their
+ * {@link RDF4JTripleLike#asStatement()}.
+ * <p>
+ * Likewise, {@link #asValue(RDFTerm)} can be used to convert any Commons RDF
+ * {@link RDFTerm} to a corresponding RDF4J {@link Value}. This recognises
+ * previously converted {@link RDF4JTerm}s without re-converting their
+ * {@link RDF4JTerm#asValue()}.
  * <p>
- * {@link #asStatement(Triple)} can be used to convert any Commons RDF
- * {@link Triple} to a RDF4J {@link Statement}. <p {@link #asValue(RDFTerm)} can
- * be used to convert any Commons RDF {@link RDFTerm} to a corresponding RDF4J
- * {@link Value}.
+ * For the purpose of {@link BlankNode} equivalence, this factory contains an
+ * internal {@link UUID} salt that is used by adapter methods like
+ * {@link #asQuad(Statement)}, {@link #asTriple(Statement)},
+ * {@link #asRDFTerm(Value)} as well as {@link #createBlankNode(String)}. As
+ * RDF4J {@link BNode} instances from multiple repositories or models may have
+ * the same {@link BNode#getID()}, converting them with the above methods might
+ * cause accidental {@link BlankNode} equivalence. Note that the {@link Graph}
+ * and {@link Dataset} adapter methods like
+ * {@link #asRDFTermDataset(Repository)} and {@link #asRDFTermGraph(Model)}
+ * therefore uses a unique {@link RDF4JTermFactory} internally. An alternative
+ * is to use the static methods {@link #asRDFTerm(Value, UUID)},
+ * {@link #asQuad(Statement, UUID)} or {@link #asTriple(Statement, UUID)} with
+ * a provided {@link UUID} salt.
  * 
  */
 public class RDF4JTermFactory implements RDFTermFactory {
@@ -89,18 +113,26 @@ public class RDF4JTermFactory implements RDFTermFactory {
 	 * {@link org.eclipse.rdf4j.model.Literal}. is converted to a
 	 * {@link org.apache.commons.rdf.api.Literal}
 	 * 
-	 * @param value
-	 * @return
+	 * @param value The RDF4J {@link Value} to convert.
+	 * @param salt
+	 *            A {@link UUID} salt to use for uniquely mapping any
+	 *            {@link BNode}s. The salt should typically be the same for
+	 *            multiple statements in the same {@link Repository} or
+	 *            {@link Model} to ensure {@link BlankNode#equals(Object)} and
+	 *            {@link BlankNode#uniqueReference()} works as intended.
+	 * @return A {@link RDFTerm} that corresponds to the RDF4J value
+	 * @throws IllegalArgumentException if the value is not a BNode, Literal or IRI 
 	 */
-	public static RDF4JTerm<?> asRDFTerm(final org.eclipse.rdf4j.model.Value value, UUID
salt) {
+	@SuppressWarnings("unchecked")
+	public static <T extends Value> RDF4JTerm<T> asRDFTerm(final T value, UUID salt)
{
 		if (value instanceof BNode) {
-			return new BlankNodeImpl((BNode) value, salt);
+			return (RDF4JTerm<T>) new BlankNodeImpl((BNode) value, salt);
 		}
 		if (value instanceof org.eclipse.rdf4j.model.Literal) {
-			return new LiteralImpl((org.eclipse.rdf4j.model.Literal) value);
+			return (RDF4JTerm<T>) new LiteralImpl((org.eclipse.rdf4j.model.Literal) value);
 		}
 		if (value instanceof org.eclipse.rdf4j.model.IRI) {
-			return new IRIImpl((org.eclipse.rdf4j.model.IRI) value);
+			return (RDF4JTerm<T>) new IRIImpl((org.eclipse.rdf4j.model.IRI) value);
 		}
 		throw new IllegalArgumentException("Value is not a BNode, Literal or IRI: " + value.getClass());
 	}
@@ -109,7 +141,14 @@ public class RDF4JTermFactory implements RDFTermFactory {
 	 * Adapt a RDF4J {@link Statement} as a Commons RDF {@link Triple}.
 	 * 
 	 * @param statement
-	 * @return
+	 *            The statement to convert
+	 * @param salt
+	 *            A {@link UUID} salt to use for uniquely mapping any
+	 *            {@link BNode}s. The salt should typically be the same for
+	 *            multiple statements in the same {@link Repository} or
+	 *            {@link Model} to ensure {@link BlankNode#equals(Object)} and
+	 *            {@link BlankNode#uniqueReference()} works as intended.
+	 * @return A {@link Triple} that corresponds to the RDF4J statement
 	 */
 	public static RDF4JTriple asTriple(final Statement statement, UUID salt) {
 		return new TripleImpl(statement, salt);
@@ -129,8 +168,22 @@ public class RDF4JTermFactory implements RDFTermFactory {
 
 	/**
 	 * Adapt a RDF4J {@link Statement} as a Commons RDF {@link Quad}.
+	 * <p>
+	 * For the purpose of {@link BlankNode} equivalence, this 
+	 * method will use an internal salt UUID that is unique per instance of 
+	 * {@link RDF4JTermFactory}. 
+	 * <p>
+	 * <strong>NOTE:</strong> If combining RDF4J {@link Statement}s
+	 * multiple repositories or models, then their {@link BNode}s 
+	 * may have the same {@link BNode#getID()}, which with this method 
+	 * would become equivalent according to {@link BlankNode#equals(Object)} and
+	 * {@link BlankNode#uniqueReference()}, 
+	 * unless a separate {@link RDF4JTermFactory}
+	 * instance is used per RDF4J repository/model.  
 	 * 
+	 * @see #asQuad(Statement, UUID)
 	 * @param statement
+	 *            The statement to convert
 	 * @return A {@link RDF4JQuad} that is equivalent to the statement
 	 */
 	public RDF4JQuad asQuad(final Statement statement) {
@@ -138,6 +191,25 @@ public class RDF4JTermFactory implements RDFTermFactory {
 	}
 
 	/**
+	 * Adapt a RDF4J {@link Statement} as a Commons RDF {@link Quad}.
+	 *
+	 * @see #asQuad(Statement)
+	 * @param statement
+	 *            The statement to convert
+	 * @param salt
+	 *            A {@link UUID} salt to use for uniquely mapping any
+	 *            {@link BNode}s. The salt should typically be the same for
+	 *            multiple statements in the same {@link Repository} or
+	 *            {@link Model} to ensure {@link BlankNode#equals(Object)} and
+	 *            {@link BlankNode#uniqueReference()} works as intended.
+	 * @return A {@link RDF4JQuad} that is equivalent to the statement
+	 */
+	public static RDF4JQuad asQuad(final Statement statement, UUID salt) {
+		return new QuadImpl(statement, salt);
+	}
+
+	
+	/**
 	 * 
 	 * Adapt a RDF4J {@link Value} as a Commons RDF {@link RDFTerm}.
 	 * <p>
@@ -149,11 +221,24 @@ public class RDF4JTermFactory implements RDFTermFactory {
 	 * {@link org.apache.commons.rdf.api.IRI} and a
 	 * {@link org.eclipse.rdf4j.model.Literal}. is converted to a
 	 * {@link org.apache.commons.rdf.api.Literal}
+	 * <p>
+	 * For the purpose of {@link BlankNode} equivalence, this 
+	 * method will use an internal salt UUID that is unique per instance of 
+	 * {@link RDF4JTermFactory}. 
+	 * <p>
+	 * <strong>NOTE:</strong> If combining RDF4J values from
+	 * multiple repositories or models, then their {@link BNode}s 
+	 * may have the same {@link BNode#getID()}, which with this method 
+	 * would become equivalent according to {@link BlankNode#equals(Object)} and
+	 * {@link BlankNode#uniqueReference()}, 
+	 * unless a separate {@link RDF4JTermFactory}
+	 * instance is used per RDF4J repository/model.  
 	 * 
-	 * @param value
-	 * @return
+	 * @param value The RDF4J {@link Value} to convert.
+	 * @return A {@link RDFTerm} that corresponds to the RDF4J value
+	 * @throws IllegalArgumentException if the value is not a BNode, Literal or IRI 
 	 */
-	public RDF4JTerm<?> asRDFTerm(final org.eclipse.rdf4j.model.Value value) {
+	public <T extends Value> RDF4JTerm<T> asRDFTerm(T value) {
 		return asRDFTerm(value, salt);
 	}
 
@@ -234,6 +319,21 @@ public class RDF4JTermFactory implements RDFTermFactory {
 		return new RepositoryGraphImpl(repository, includeInferred, unionGraph);
 	}
 
+	/**
+	 * Adapt a Commons RDF {@link Triple} or {@link Quad} as a RDF4J
+	 * {@link Statement}.
+	 * <p>
+	 * If the <code>tripleLike</code> argument is an {@link RDF4JTriple} or
+	 * a {@link RDF4JQuad}, then its {@link RDF4JTripleLike#asStatement()} is
+	 * returned as-is. Note that this means that a {@link RDF4JTriple} would
+	 * preserve its {@link Statement#getContext()}, and that any 
+	 * {@link BlankNode}s would be deemed equivalent in RDF4J
+	 * if they have the same {@link BNode#getID()}.
+	 * 
+	 * @param tripleLike
+	 *            A {@link Triple} or {@link Quad} to adapt
+	 * @return A corresponding {@link Statement}
+	 */
 	public Statement asStatement(TripleLike<BlankNodeOrIRI, org.apache.commons.rdf.api.IRI,
RDFTerm> tripleLike) {
 		if (tripleLike instanceof RDF4JTripleLike) {
 			// Return original statement - this covers both RDF4JQuad and
@@ -257,6 +357,18 @@ public class RDF4JTermFactory implements RDFTermFactory {
 
 	/**
 	 * Adapt a RDF4J {@link Statement} as a Commons RDF {@link Triple}.
+	 * <p>
+	 * For the purpose of {@link BlankNode} equivalence, this 
+	 * method will use an internal salt UUID that is unique per instance of 
+	 * {@link RDF4JTermFactory}. 
+	 * <p>
+	 * <strong>NOTE:</strong> If combining RDF4J statements from
+	 * multiple repositories or models, then their {@link BNode}s 
+	 * may have the same {@link BNode#getID()}, which with this method 
+	 * would become equivalent according to {@link BlankNode#equals(Object)} and
+	 * {@link BlankNode#uniqueReference()}, 
+	 * unless a separate {@link RDF4JTermFactory}
+	 * instance is used per RDF4J repository/model.
 	 * 
 	 * @param statement
 	 * @return A {@link RDF4JTriple} that is equivalent to the statement

http://git-wip-us.apache.org/repos/asf/incubator-commonsrdf/blob/5709ab23/rdf4j/src/main/java/org/apache/commons/rdf/rdf4j/package-info.java
----------------------------------------------------------------------
diff --git a/rdf4j/src/main/java/org/apache/commons/rdf/rdf4j/package-info.java b/rdf4j/src/main/java/org/apache/commons/rdf/rdf4j/package-info.java
new file mode 100644
index 0000000..b8ad947
--- /dev/null
+++ b/rdf4j/src/main/java/org/apache/commons/rdf/rdf4j/package-info.java
@@ -0,0 +1,26 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/**
+ * Commons RDF integration with <a href="http://rdf4j.org/">RDF4J</a>.
+ * <p>
+ * 
+ *
+ */
+package org.apache.commons.rdf.rdf4j;
+
+


Mime
View raw message