1 /**
2 * Licensed to the Apache Software Foundation (ASF) under one
3 * or more contributor license agreements. See the NOTICE file
4 * distributed with this work for additional information
5 * regarding copyright ownership. The ASF licenses this file
6 * to you under the Apache License, Version 2.0 (the
7 * "License"); you may not use this file except in compliance
8 * with the License. You may obtain a copy of the License at
9 *
10 * http://www.apache.org/licenses/LICENSE-2.0
11 *
12 * Unless required by applicable law or agreed to in writing, software
13 * distributed under the License is distributed on an "AS IS" BASIS,
14 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15 * See the License for the specific language governing permissions and
16 * limitations under the License.
17 */
18 package org.apache.commons.rdf.api;
19
20 import java.util.ConcurrentModificationException;
21 import java.util.Iterator;
22 import java.util.stream.Stream;
23
24 /**
25 * An <a href="http://www.w3.org/TR/rdf11-concepts/#section-rdf-graph"> RDF 1.1
26 * Graph</a>, a set of RDF triples, as defined by
27 * <a href="http://www.w3.org/TR/rdf11-concepts/" >RDF-1.1 Concepts and Abstract
28 * Syntax</a>, a W3C Recommendation published on 25 February 2014.
29 *
30 * @see RDF#createGraph()
31 */
32 public interface Graph extends AutoCloseable, GraphLike<Triple> {
33
34 /**
35 * Adds a triple to the graph, possibly mapping any of the components of the
36 * Triple to those supported by this Graph.
37 *
38 * @param triple
39 * The triple to add
40 */
41 @Override
42 void add(Triple triple);
43
44 /**
45 * Adds a triple to the graph, possibly mapping any of the components to
46 * those supported by this Graph.
47 *
48 * @param subject
49 * The triple subject
50 * @param predicate
51 * The triple predicate
52 * @param object
53 * The triple object
54 */
55 void add(BlankNodeOrIRI subject, IRI predicate, RDFTerm object);
56
57 /**
58 * Checks if graph contains triple.
59 *
60 * @param triple
61 * The triple to check.
62 * @return True if the Graph contains the given Triple.
63 */
64 @Override
65 boolean contains(Triple triple);
66
67 /**
68 * Checks if graph contains a pattern of triples.
69 *
70 * @param subject
71 * The triple subject (null is a wildcard)
72 * @param predicate
73 * The triple predicate (null is a wildcard)
74 * @param object
75 * The triple object (null is a wildcard)
76 * @return True if the Graph contains any Triples that match the given
77 * pattern.
78 */
79 boolean contains(BlankNodeOrIRI subject, IRI predicate, RDFTerm object);
80
81 /**
82 * Closes the graph, relinquishing any underlying resources.
83 * <p>
84 * For example, this would close any open file and network streams and free
85 * database locks held by the Graph implementation.
86 * <p>
87 * The behaviour of the other Graph methods are undefined after closing the
88 * graph.
89 * <p>
90 * Implementations might not need {@link #close()}, hence the default
91 * implementation does nothing.
92 */
93 @Override
94 default void close() throws Exception {
95 }
96
97 /**
98 * Removes a concrete triple from the graph.
99 *
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 }