commonsrdf-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From st...@apache.org
Subject [2/4] incubator-commonsrdf git commit: GraphOrDataset superinterface
Date Fri, 08 Apr 2016 13:52:58 GMT
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 <stain@apache.org>
Authored: Fri Apr 8 14:25:09 2016 +0100
Committer: Stian Soiland-Reyes <stain@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;
+    }
+}


Mime
View raw message