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/04/08 15:52:58 UTC
[2/4] incubator-commonsrdf git commit: GraphOrDataset superinterface
GraphOrDataset superinterface
Project: http://git-wip-us.apache.org/repos/asf/incubator-commonsrdf/repo
Commit: http://git-wip-us.apache.org/repos/asf/incubator-commonsrdf/commit/93f99826
Tree: http://git-wip-us.apache.org/repos/asf/incubator-commonsrdf/tree/93f99826
Diff: http://git-wip-us.apache.org/repos/asf/incubator-commonsrdf/diff/93f99826
Branch: refs/heads/quad
Commit: 93f99826ac704d7804e78fe3e2dcbd7604614ace
Parents: 7639fd7
Author: Stian Soiland-Reyes <st...@apache.org>
Authored: Fri Apr 8 14:25:09 2016 +0100
Committer: Stian Soiland-Reyes <st...@apache.org>
Committed: Fri Apr 8 14:25:09 2016 +0100
----------------------------------------------------------------------
.../java/org/apache/commons/rdf/api/Graph.java | 2 +-
.../apache/commons/rdf/api/GraphOrDataset.java | 236 +++++++++++++++++++
2 files changed, 237 insertions(+), 1 deletion(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/incubator-commonsrdf/blob/93f99826/api/src/main/java/org/apache/commons/rdf/api/Graph.java
----------------------------------------------------------------------
diff --git a/api/src/main/java/org/apache/commons/rdf/api/Graph.java b/api/src/main/java/org/apache/commons/rdf/api/Graph.java
index c421226..019a713 100644
--- a/api/src/main/java/org/apache/commons/rdf/api/Graph.java
+++ b/api/src/main/java/org/apache/commons/rdf/api/Graph.java
@@ -27,7 +27,7 @@ import java.util.stream.Stream;
* 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 Graph extends AutoCloseable {
+public interface Graph extends AutoCloseable, GraphOrDataset<Triple> {
/**
* Add a triple to the graph, possibly mapping any of the components of the
http://git-wip-us.apache.org/repos/asf/incubator-commonsrdf/blob/93f99826/api/src/main/java/org/apache/commons/rdf/api/GraphOrDataset.java
----------------------------------------------------------------------
diff --git a/api/src/main/java/org/apache/commons/rdf/api/GraphOrDataset.java b/api/src/main/java/org/apache/commons/rdf/api/GraphOrDataset.java
new file mode 100644
index 0000000..35017fb
--- /dev/null
+++ b/api/src/main/java/org/apache/commons/rdf/api/GraphOrDataset.java
@@ -0,0 +1,236 @@
+/**
+ * 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.stream.Stream;
+
+/**
+ * An <a href="http://www.w3.org/TR/rdf11-concepts/#section-rdf-graph"> RDF 1.1
+ * Graph</a>, a set of RDF triples, 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 GraphOrDataset<T extends TripleOrQuad> extends AutoCloseable {
+
+ /**
+ * Add a triple to the graph, possibly mapping any of the components of the
+ * Triple to those supported by this Graph.
+ *
+ * @param triple The triple or quad to add
+ */
+ void add(T triple);
+
+ /**
+ * Add a triple to the graph, possibly mapping any of the components to
+ * those supported by this Graph.
+ *
+ * @param subject The triple subject
+ * @param predicate The triple predicate
+ * @param object The triple object
+ */
+ void add(BlankNodeOrIRI subject, IRI predicate, RDFTerm object);
+
+ /**
+ * Check if graph contains triple.
+ *
+ * @param triple The triple to check.
+ * @return True if the Graph contains the given Triple.
+ */
+ boolean contains(T triple);
+
+ /**
+ * Check if graph contains a pattern of triples.
+ *
+ * @param subject The triple subject (null is a wildcard)
+ * @param predicate The triple predicate (null is a wildcard)
+ * @param object The triple object (null is a wildcard)
+ * @return True if the Graph contains any Triples that match the given
+ * pattern.
+ */
+ boolean contains(BlankNodeOrIRI subject, IRI predicate, RDFTerm object);
+
+ /**
+ * Close the graph, relinquishing any underlying resources.
+ * <p>
+ * For example, this would close any open file and network streams and free
+ * database locks held by the Graph implementation.
+ * <p>
+ * The behaviour of the other Graph methods are undefined after closing the
+ * graph.
+ * <p>
+ * Implementations might not need {@link #close()}, hence the default
+ * implementation does nothing.
+ */
+ @Override
+ default void close() throws Exception {
+ }
+
+ /**
+ * Remove a concrete triple from the graph.
+ *
+ * @param triple triple to remove
+ */
+ void remove(T triple);
+
+ /**
+ * Remove a concrete pattern of triples from the graph.
+ *
+ * @param subject The triple subject (null is a wildcard)
+ * @param predicate The triple predicate (null is a wildcard)
+ * @param object The triple object (null is a wildcard)
+ */
+ void remove(BlankNodeOrIRI subject, IRI predicate, RDFTerm object);
+
+ /**
+ * Clear the graph, removing all triples.
+ */
+ void clear();
+
+ /**
+ * Number of triples contained by the graph.
+ * <p>
+ * The count of a set does not include duplicates, consistent with the
+ * {@link T#equals(Object)} equals method for each {@link T}.
+ *
+ * @return The number of triples in the graph
+ */
+ long size();
+
+ /**
+ * Get all triples contained by the graph.<br>
+ * <p>
+ * The iteration does not contain any duplicate triples, as determined by
+ * the {@link T#equals(Object)} method for each {@link T}.
+ * <p>
+ * The behaviour of the {@link Stream} is not specified if {@link #add(T)},
+ * {@link #remove(T)} or {@link #clear()} are called on the
+ * {@link GraphOrDataset} 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 triples in the graph
+ */
+ Stream<? extends T> getTriples();
+
+ /**
+ * Get all triples contained by the graph matched with the pattern.
+ * <p>
+ * The iteration does not contain any duplicate triples, as determined by
+ * the {@link T#equals(Object)} method for each {@link T}.
+ * <p>
+ * The behaviour of the {@link Stream} is not specified if {@link #add(T)},
+ * {@link #remove(T)} or {@link #clear()} are called on the
+ * {@link GraphOrDataset} before it terminates.
+ * <p>
+ * Implementations may throw {@link ConcurrentModificationException} from Stream
+ * methods if they detect a conflict while the Stream is active.
+ *
+ * @param subject The triple subject (null is a wildcard)
+ * @param predicate The triple predicate (null is a wildcard)
+ * @param object The triple object (null is a wildcard)
+ * @return A {@link Stream} over the matched triples.
+ */
+ Stream<? extends T> getTriples(BlankNodeOrIRI subject, IRI predicate,
+ RDFTerm object);
+
+ /**
+ * Get an Iterable for iterating over all triples in the graph.
+ * <p>
+ * This method is meant to be used with a Java for-each loop, e.g.:
+ * <pre>
+ * for (Triple t : graph.iterate()) {
+ * System.out.println(t);
+ * }
+ * </pre>
+ * The behaviour of the iterator is not specified if {@link #add(T)},
+ * {@link #remove(T)} or {@link #clear()}, are called on the
+ * {@link GraphOrDataset} 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
+ * triples in the graph
+ * @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<T> iterate()
+ throws ConcurrentModificationException, IllegalStateException {
+ return ((Stream<T>)getTriples())::iterator;
+ }
+
+ /**
+ * Get an Iterable for iterating over the triples in the graph 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 (Triple t : graph.iterate(alice, knows, null)) {
+ * System.out.println(t.getObject());
+ * }
+ * </pre>
+ * <p>
+ * The behaviour of the iterator is not specified if
+ * {@link #add(T)}, {@link #remove(T)} or {@link #clear()}, are
+ * called on the {@link GraphOrDataset} 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 subject
+ * The triple subject (null is a wildcard)
+ * @param predicate
+ * The triple predicate (null is a wildcard)
+ * @param object
+ * The triple object (null is a wildcard)
+ * @return A {@link Iterable} that returns {@link Iterator} over the
+ * matching triples in the graph
+ * @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<T> iterate(
+ BlankNodeOrIRI subject, IRI predicate, RDFTerm object)
+ throws ConcurrentModificationException, IllegalStateException {
+ return ((Stream<T>) getTriples(subject, predicate, object))::iterator;
+ }
+}