001/**
002 * Licensed to the Apache Software Foundation (ASF) under one
003 * or more contributor license agreements. See the NOTICE file
004 * distributed with this work for additional information
005 * regarding copyright ownership. The ASF licenses this file
006 * to you under the Apache License, Version 2.0 (the
007 * "License"); you may not use this file except in compliance
008 * with the License.  You may obtain a copy of the License at
009 *
010 *     http://www.apache.org/licenses/LICENSE-2.0
011 *
012 * Unless required by applicable law or agreed to in writing, software
013 * distributed under the License is distributed on an "AS IS" BASIS,
014 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
015 * See the License for the specific language governing permissions and
016 * limitations under the License.
017 */
018package org.apache.commons.rdf.api;
019
020import java.util.ConcurrentModificationException;
021import java.util.Iterator;
022import java.util.stream.Stream;
023
024/**
025 * An <a href="http://www.w3.org/TR/rdf11-concepts/#section-rdf-graph"> RDF 1.1
026 * Graph</a>, a set of RDF triples, as defined by
027 * <a href="http://www.w3.org/TR/rdf11-concepts/" >RDF-1.1 Concepts and Abstract
028 * Syntax</a>, a W3C Recommendation published on 25 February 2014.
029 *
030 * @see RDF#createGraph()
031 */
032public interface Graph extends AutoCloseable, GraphLike<Triple> {
033
034    /**
035     * Adds a triple to the graph, possibly mapping any of the components of the
036     * Triple to those supported by this Graph.
037     *
038     * @param triple
039     *            The triple to add
040     */
041    @Override
042    void add(Triple triple);
043
044    /**
045     * Adds a triple to the graph, possibly mapping any of the components to
046     * those supported by this Graph.
047     *
048     * @param subject
049     *            The triple subject
050     * @param predicate
051     *            The triple predicate
052     * @param object
053     *            The triple object
054     */
055    void add(BlankNodeOrIRI subject, IRI predicate, RDFTerm object);
056
057    /**
058     * Checks if graph contains triple.
059     *
060     * @param triple
061     *            The triple to check.
062     * @return True if the Graph contains the given Triple.
063     */
064    @Override
065    boolean contains(Triple triple);
066
067    /**
068     * Checks if graph contains a pattern of triples.
069     *
070     * @param subject
071     *            The triple subject (null is a wildcard)
072     * @param predicate
073     *            The triple predicate (null is a wildcard)
074     * @param object
075     *            The triple object (null is a wildcard)
076     * @return True if the Graph contains any Triples that match the given
077     *         pattern.
078     */
079    boolean contains(BlankNodeOrIRI subject, IRI predicate, RDFTerm object);
080
081    /**
082     * Closes the graph, relinquishing any underlying resources.
083     * <p>
084     * For example, this would close any open file and network streams and free
085     * database locks held by the Graph implementation.
086     * <p>
087     * The behaviour of the other Graph methods are undefined after closing the
088     * graph.
089     * <p>
090     * Implementations might not need {@link #close()}, hence the default
091     * implementation does nothing.
092     */
093    @Override
094    default void close() throws Exception {
095    }
096
097    /**
098     * Removes a concrete triple from the graph.
099     *
100     * @param triple
101     *            triple to remove
102     */
103    @Override
104    void remove(Triple triple);
105
106    /**
107     * Removes a concrete pattern of triples from the graph.
108     *
109     * @param subject
110     *            The triple subject (null is a wildcard)
111     * @param predicate
112     *            The triple predicate (null is a wildcard)
113     * @param object
114     *            The triple object (null is a wildcard)
115     */
116    void remove(BlankNodeOrIRI subject, IRI predicate, RDFTerm object);
117
118    /**
119     * Clears the graph, removing all triples.
120     */
121    @Override
122    void clear();
123
124    /**
125     * Number of triples contained by the graph.
126     * <p>
127     * The count of a set does not include duplicates, consistent with the
128     * {@link Triple#equals(Object)} equals method for each {@link Triple}.
129     *
130     * @return The number of triples in the graph
131     */
132    @Override
133    long size();
134
135    /**
136     * Gets all triples contained by the graph.<br>
137     * <p>
138     * The iteration does not contain any duplicate triples, as determined by
139     * the {@link Triple#equals(Object)} method for each {@link Triple}.
140     * <p>
141     * The behaviour of the {@link Stream} is not specified if
142     * {@link #add(Triple)}, {@link #remove(Triple)} or {@link #clear()} are
143     * called on the {@link Graph} before it terminates.
144     * <p>
145     * Implementations may throw {@link ConcurrentModificationException} from
146     * Stream methods if they detect a conflict while the Stream is active.
147     *
148     * @since 0.3.0-incubating
149     * @return A {@link Stream} over all of the triples in the graph
150     */
151    @Override
152    Stream<? extends Triple> stream();
153
154    /**
155     * Gets all triples contained by the graph matched with the pattern.
156     * <p>
157     * The iteration does not contain any duplicate triples, as determined by
158     * the {@link Triple#equals(Object)} method for each {@link Triple}.
159     * <p>
160     * The behaviour of the {@link Stream} is not specified if
161     * {@link #add(Triple)}, {@link #remove(Triple)} or {@link #clear()} are
162     * called on the {@link Graph} before it terminates.
163     * <p>
164     * Implementations may throw {@link ConcurrentModificationException} from
165     * Stream methods if they detect a conflict while the Stream is active.
166     * <p>
167     *
168     * @since 0.3.0-incubating
169     * @param subject
170     *            The triple subject (null is a wildcard)
171     * @param predicate
172     *            The triple predicate (null is a wildcard)
173     * @param object
174     *            The triple object (null is a wildcard)
175     * @return A {@link Stream} over the matched triples.
176     */
177    Stream<? extends Triple> stream(BlankNodeOrIRI subject, IRI predicate, RDFTerm object);
178
179    /**
180     * This method is deprecated, use the equivalent method {@link #stream()}
181     * instead.
182     *
183     * @return A {@link Stream} over all triples.
184     */
185    @Deprecated
186    default Stream<? extends Triple> getTriples() {
187        return stream();
188    }
189
190    /**
191     * This method is deprecated, use the equivalent method
192     * {@link #stream(BlankNodeOrIRI, IRI, RDFTerm)} instead.
193     *
194     * @param subject
195     *            The triple subject (null is a wildcard)
196     * @param predicate
197     *            The triple predicate (null is a wildcard)
198     * @param object
199     *            The triple object (null is a wildcard)
200     * @return A {@link Stream} over the matched triples.
201     */
202    @Deprecated
203    default Stream<? extends Triple> getTriples(final BlankNodeOrIRI subject, final IRI predicate, final RDFTerm object) {
204        return stream(subject, predicate, object);
205    }
206
207    /**
208     * Gets an Iterable for iterating over all triples in the graph.
209     * <p>
210     * This method is meant to be used with a Java for-each loop, e.g.:
211     *
212     * <pre>
213     * for (Triple t : graph.iterate()) {
214     *     System.out.println(t);
215     * }
216     * </pre>
217     *
218     * The behaviour of the iterator is not specified if {@link #add(Triple)},
219     * {@link #remove(Triple)} or {@link #clear()}, are called on the
220     * {@link Graph} before it terminates. It is undefined if the returned
221     * {@link Iterator} supports the {@link Iterator#remove()} method.
222     * <p>
223     * Implementations may throw {@link ConcurrentModificationException} from
224     * Iterator methods if they detect a concurrency conflict while the Iterator
225     * is active.
226     * <p>
227     * The {@link Iterable#iterator()} must only be called once, that is the
228     * Iterable must only be iterated over once. A {@link IllegalStateException}
229     * may be thrown on attempt to reuse the Iterable.
230     * <p>
231     * The default implementation of this method will call {@link #stream()} to return
232     * its {@link Stream#iterator()}.
233     *
234     * @return A {@link Iterable} that returns {@link Iterator} over all of the
235     *         triples in the graph
236     * @throws IllegalStateException
237     *             if the {@link Iterable} has been reused
238     * @throws ConcurrentModificationException
239     *             if a concurrency conflict occurs while the Iterator is
240     *             active.
241     */
242    @Override
243    @SuppressWarnings("unchecked")
244    default Iterable<Triple> iterate() throws ConcurrentModificationException, IllegalStateException {
245        return ((Stream<Triple>) stream())::iterator;
246    }
247
248    /**
249     * Gets an Iterable for iterating over the triples in the graph that match
250     * the pattern.
251     * <p>
252     * This method is meant to be used with a Java for-each loop, e.g.:
253     *
254     * <pre>
255     * IRI alice = factory.createIRI("http://example.com/alice");
256     * IRI knows = factory.createIRI("http://xmlns.com/foaf/0.1/");
257     * for (Triple t : graph.iterate(alice, knows, null)) {
258     *     System.out.println(t.getObject());
259     * }
260     * </pre>
261     * <p>
262     * The behaviour of the iterator is not specified if {@link #add(Triple)},
263     * {@link #remove(Triple)} or {@link #clear()}, are called on the
264     * {@link Graph} before it terminates. It is undefined if the returned
265     * {@link Iterator} supports the {@link Iterator#remove()} method.
266     * <p>
267     * Implementations may throw {@link ConcurrentModificationException} from
268     * Iterator methods if they detect a concurrency conflict while the Iterator
269     * is active.
270     * <p>
271     * The {@link Iterable#iterator()} must only be called once, that is the
272     * Iterable must only be iterated over once. A {@link IllegalStateException}
273     * may be thrown on attempt to reuse the Iterable.
274     * <p>
275     * The default implementation of this method will call
276     * {@link #stream(BlankNodeOrIRI, IRI, RDFTerm)} to return its
277     * {@link Stream#iterator()}.
278     *
279     * @param subject
280     *            The triple subject (null is a wildcard)
281     * @param predicate
282     *            The triple predicate (null is a wildcard)
283     * @param object
284     *            The triple object (null is a wildcard)
285     * @return A {@link Iterable} that returns {@link Iterator} over the
286     *         matching triples in the graph
287     * @throws IllegalStateException
288     *             if the {@link Iterable} has been reused
289     * @throws ConcurrentModificationException
290     *             if a concurrency conflict occurs while the Iterator is
291     *             active.
292     */
293    @SuppressWarnings("unchecked")
294    default Iterable<Triple> iterate(final BlankNodeOrIRI subject, final IRI predicate, final RDFTerm object)
295            throws ConcurrentModificationException, IllegalStateException {
296        return ((Stream<Triple>) stream(subject, predicate, object))::iterator;
297    }
298}