You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@commonsrdf.apache.org by st...@apache.org on 2016/09/05 15:53:47 UTC
[03/19] incubator-commonsrdf git commit: Added Dataset (copy-paste of
Graph)
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 <st...@apache.org>
Authored: Fri Apr 8 14:25:49 2016 +0100
Committer: Stian Soiland-Reyes <st...@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;
+ }
+}