commonsrdf-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From st...@apache.org
Subject [03/19] incubator-commonsrdf git commit: Added Dataset (copy-paste of Graph)
Date Mon, 05 Sep 2016 15:53:47 GMT
Added Dataset (copy-paste of Graph)


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

Branch: refs/heads/master
Commit: 63745d33b66d0ff28ab54e0c8edf65d76dbab931
Parents: 93f9982
Author: Stian Soiland-Reyes <stain@apache.org>
Authored: Fri Apr 8 14:25:49 2016 +0100
Committer: Stian Soiland-Reyes <stain@apache.org>
Committed: Fri Apr 8 14:50:57 2016 +0100

----------------------------------------------------------------------
 .../org/apache/commons/rdf/api/Dataset.java     | 322 +++++++++++++++++++
 1 file changed, 322 insertions(+)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/incubator-commonsrdf/blob/63745d33/api/src/main/java/org/apache/commons/rdf/api/Dataset.java
----------------------------------------------------------------------
diff --git a/api/src/main/java/org/apache/commons/rdf/api/Dataset.java b/api/src/main/java/org/apache/commons/rdf/api/Dataset.java
new file mode 100644
index 0000000..70d5bff
--- /dev/null
+++ b/api/src/main/java/org/apache/commons/rdf/api/Dataset.java
@@ -0,0 +1,322 @@
+/**
+ * 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.
+ */
+package org.apache.commons.rdf.api;
+
+import java.util.ConcurrentModificationException;
+import java.util.Iterator;
+import java.util.Optional;
+import java.util.stream.Stream;
+
+/**
+ * An <a href="http://www.w3.org/TR/rdf11-concepts/#section-rdf-dataset"> RDF
+ * 1.1 dataset</a>, a set of RDF quads, as defined by
+ * <a href="http://www.w3.org/TR/rdf11-concepts/" >RDF-1.1 Concepts and Abstract
+ * Syntax</a>, a W3C Recommendation published on 25 February 2014.
+ */
+public interface Dataset extends AutoCloseable, GraphOrDataset<Quad> {
+
+	/**
+	 * Add a quad to the dataset, possibly mapping any of the components of the
+	 * Quad to those supported by this dataset.
+	 *
+	 * @param quad
+	 *            The quad to add
+	 */
+	void add(Quad quad);
+
+	/**
+	 * Add a triple to the default graph of this dataset, possibly mapping any
+	 * of the components to those supported by this dataset.
+	 * <p>
+	 * This method is equivalent to
+	 * {@link #add(BlankNodeOrIRI, BlankNodeOrIRI, IRI, RDFTerm)} with
+	 * <code>graphName</code> set as <code>null</code>.
+	 *
+	 * @param subject
+	 *            The quad subject
+	 * @param predicate
+	 *            The quad predicate
+	 * @param object
+	 *            The quad object
+	 */
+	void add(BlankNodeOrIRI subject, IRI predicate, RDFTerm object);
+
+	/**
+	 * Add a quad to the dataset, possibly mapping any of the components to
+	 * those supported by this dataset.
+	 *
+	 * @param graphName
+	 *            The graph the quad belongs to, or <code>null</code> for the
+	 *            default graph
+	 * @param subject
+	 *            The quad subject
+	 * @param predicate
+	 *            The quad predicate
+	 * @param object
+	 *            The quad object
+	 */
+	void add(BlankNodeOrIRI graphName, BlankNodeOrIRI subject, IRI predicate, RDFTerm object);
+
+	/**
+	 * Check if dataset contains quad.
+	 *
+	 * @param quad
+	 *            The quad to check.
+	 * @return True if the dataset contains the given Quad.
+	 */
+	boolean contains(Quad quad);
+
+	/**
+	 * Check if the default graph in the dataset contains a triple pattern.
+	 * <p>
+	 * This method is equivalent to
+	 * {@link #contains(Optional, BlankNodeOrIRI, IRI, RDFTerm)} with a
+	 * <code>graphName</code> set to <code>null</code>
+	 *
+	 * @param subject
+	 *            The quad subject (<code>null</code> is a wildcard)
+	 * @param predicate
+	 *            The quad predicate (<code>null</code> is a wildcard)
+	 * @param object
+	 *            The quad object (<code>null</code> is a wildcard)
+	 * @return True if the default graph in the dataset contains any quads that
+	 *         match the given pattern.
+	 */
+	boolean contains(BlankNodeOrIRI subject, IRI predicate, RDFTerm object);
+
+	/**
+	 * Check if dataset contains a pattern of quads.
+	 *
+	 * @param graphName
+	 *            The graph the quad belongs to, wrapped as an {@link Optional}
+	 *            (<code>null</code> is a wildcard, {@link Optional#empty()} is
+	 *            the default graph)
+	 * @param subject
+	 *            The quad subject (<code>null</code> is a wildcard)
+	 * @param predicate
+	 *            The quad predicate (<code>null</code> is a wildcard)
+	 * @param object
+	 *            The quad object (<code>null</code> is a wildcard)
+	 * @return True if the dataset contains any quads that match the given
+	 *         pattern.
+	 */
+	boolean contains(Optional<BlankNodeOrIRI> graphName, BlankNodeOrIRI subject, IRI predicate,
RDFTerm object);
+
+	/**
+	 * Close the dataset, relinquishing any underlying resources.
+	 * <p>
+	 * For example, this would close any open file and network streams and free
+	 * database locks held by the dataset implementation.
+	 * <p>
+	 * The behaviour of the other dataset methods are undefined after closing
+	 * the dataset.
+	 * <p>
+	 * Implementations might not need {@link #close()}, hence the default
+	 * implementation does nothing.
+	 */
+	@Override
+	default void close() throws Exception {
+	}
+
+	/**
+	 * Remove a concrete quad from the dataset.
+	 *
+	 * @param quad
+	 *            quad to remove
+	 */
+	void remove(Quad quad);
+
+	/**
+	 * Remove a concrete pattern of quads from the default graph of the dataset.
+	 *
+	 * @param graphName
+	 *            The graph the quad belongs to
+	 * @param subject
+	 *            The quad subject (<code>null</code> is a wildcard)
+	 * @param predicate
+	 *            The quad predicate (<code>null</code> is a wildcard)
+	 * @param object
+	 *            The quad object (<code>null</code> is a wildcard)
+	 */
+	void remove(BlankNodeOrIRI subject, IRI predicate, RDFTerm object);
+
+	/**
+	 * Remove a concrete pattern of quads from the default graph of the dataset.
+	 *
+	 * @param graphName
+	 *            The graph the quad belongs to, wrapped as an {@link Optional}
+	 *            (<code>null</code> is a wildcard, {@link Optional#empty()} is
+	 *            the default graph)
+	 * @param subject
+	 *            The quad subject (<code>null</code> is a wildcard)
+	 * @param predicate
+	 *            The quad predicate (<code>null</code> is a wildcard)
+	 * @param object
+	 *            The quad object (<code>null</code> is a wildcard)
+	 */
+	void remove(Optional<BlankNodeOrIRI> graphName, BlankNodeOrIRI subject, IRI predicate,
RDFTerm object);
+
+	/**
+	 * Clear the dataset, removing all quads.
+	 */
+	void clear();
+
+	/**
+	 * Number of quads contained by the dataset.
+	 * <p>
+	 * The count of a set does not include duplicates, consistent with the
+	 * {@link Quad#equals(Object)} equals method for each {@link Quad}.
+	 *
+	 * @return The number of quads in the dataset
+	 */
+	long size();
+
+	/**
+	 * Get all quads contained by the dataset.<br>
+	 * <p>
+	 * The iteration does not contain any duplicate quads, as determined by the
+	 * {@link Quad#equals(Object)} method for each {@link Quad}.
+	 * <p>
+	 * The behaviour of the {@link Stream} is not specified if
+	 * {@link #add(Quad)}, {@link #remove(Quad)} or {@link #clear()} are called
+	 * on the {@link Dataset} before it terminates.
+	 * <p>
+	 * Implementations may throw {@link ConcurrentModificationException} from
+	 * Stream methods if they detect a conflict while the Stream is active.
+	 *
+	 * @return A {@link Stream} over all of the quads in the dataset
+	 */
+	Stream<? extends Quad> getQuads();
+
+	/**
+	 * Get all quads contained by the dataset matched with the pattern.
+	 * <p>
+	 * The iteration does not contain any duplicate quads, as determined by the
+	 * {@link Quad#equals(Object)} method for each {@link Quad}.
+	 * <p>
+	 * The behaviour of the {@link Stream} is not specified if
+	 * {@link #add(Quad)}, {@link #remove(Quad)} or {@link #clear()} are called
+	 * on the {@link Dataset} before it terminates.
+	 * <p>
+	 * Implementations may throw {@link ConcurrentModificationException} from
+	 * Stream methods if they detect a conflict while the Stream is active.
+	 *
+	 * @param graphName
+	 *            The graph the quad belongs to, wrapped as an {@link Optional}
+	 *            (<code>null</code> is a wildcard, {@link Optional#empty()} is
+	 *            the default graph)
+	 * @param subject
+	 *            The quad subject (<code>null</code> is a wildcard)
+	 * @param predicate
+	 *            The quad predicate (<code>null</code> is a wildcard)
+	 * @param object
+	 *            The quad object (<code>null</code> is a wildcard)
+	 * @return A {@link Stream} over the matched quads.
+	 */
+	Stream<? extends Quad> getQuads(Optional<BlankNodeOrIRI> graphName, BlankNodeOrIRI
subject, IRI predicate,
+			RDFTerm object);
+
+	/**
+	 * Get an Iterable for iterating over all quads in the dataset.
+	 * <p>
+	 * This method is meant to be used with a Java for-each loop, e.g.:
+	 * 
+	 * <pre>
+	 * for (Quad t : dataset.iterate()) {
+	 * 	System.out.println(t);
+	 * }
+	 * </pre>
+	 * 
+	 * The behaviour of the iterator is not specified if {@link #add(Quad)},
+	 * {@link #remove(Quad)} or {@link #clear()}, are called on the
+	 * {@link Dataset} before it terminates. It is undefined if the returned
+	 * {@link Iterator} supports the {@link Iterator#remove()} method.
+	 * <p>
+	 * Implementations may throw {@link ConcurrentModificationException} from
+	 * Iterator methods if they detect a concurrency conflict while the Iterator
+	 * is active.
+	 * <p>
+	 * The {@link Iterable#iterator()} must only be called once, that is the
+	 * Iterable must only be iterated over once. A {@link IllegalStateException}
+	 * may be thrown on attempt to reuse the Iterable.
+	 *
+	 * @return A {@link Iterable} that returns {@link Iterator} over all of the
+	 *         quads in the dataset
+	 * @throws IllegalStateException
+	 *             if the {@link Iterable} has been reused
+	 * @throws ConcurrentModificationException
+	 *             if a concurrency conflict occurs while the Iterator is
+	 *             active.
+	 */
+	@SuppressWarnings("unchecked")
+	default Iterable<Quad> iterate() throws ConcurrentModificationException, IllegalStateException
{
+		return ((Stream<Quad>) getQuads())::iterator;
+	}
+
+	/**
+	 * Get an Iterable for iterating over the quads in the dataset that match
+	 * the pattern.
+	 * <p>
+	 * This method is meant to be used with a Java for-each loop, e.g.:
+	 * 
+	 * <pre>
+	 * IRI alice = factory.createIRI("http://example.com/alice");
+	 * IRI knows = factory.createIRI("http://xmlns.com/foaf/0.1/");
+	 * for (Quad t : dataset.iterate(null, alice, knows, null)) {
+	 * 	   System.out.println(t.getGraphName()); 
+	 *     System.out.println(t.getObject());
+	 * }
+	 * </pre>
+	 * <p>
+	 * The behaviour of the iterator is not specified if {@link #add(Quad)},
+	 * {@link #remove(Quad)} or {@link #clear()}, are called on the
+	 * {@link Dataset} before it terminates. It is undefined if the returned
+	 * {@link Iterator} supports the {@link Iterator#remove()} method.
+	 * <p>
+	 * Implementations may throw {@link ConcurrentModificationException} from
+	 * Iterator methods if they detect a concurrency conflict while the Iterator
+	 * is active.
+	 * <p>
+	 * The {@link Iterable#iterator()} must only be called once, that is the
+	 * Iterable must only be iterated over once. A {@link IllegalStateException}
+	 * may be thrown on attempt to reuse the Iterable.
+	 *
+	 * @param graphName
+	 *            The graph the quad belongs to, wrapped as an {@link Optional}
+	 *            (<code>null</code> is a wildcard, {@link Optional#empty()} is
+	 *            the default graph)
+	 * @param subject
+	 *            The quad subject (<code>null</code> is a wildcard)
+	 * @param predicate
+	 *            The quad predicate (<code>null</code> is a wildcard)
+	 * @param object
+	 *            The quad object (<code>null</code> is a wildcard)
+	 * @return A {@link Iterable} that returns {@link Iterator} over the
+	 *         matching quads in the dataset
+	 * @throws IllegalStateException
+	 *             if the {@link Iterable} has been reused
+	 * @throws ConcurrentModificationException
+	 *             if a concurrency conflict occurs while the Iterator is
+	 *             active.
+	 */
+	@SuppressWarnings("unchecked")
+	default Iterable<Quad> iterate(Optional<BlankNodeOrIRI> graphName, BlankNodeOrIRI
subject, IRI predicate,
+			RDFTerm object) throws ConcurrentModificationException, IllegalStateException {
+		return ((Stream<Quad>) getQuads(null, subject, predicate, object))::iterator;
+	}
+}


Mime
View raw message