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.rdf4j;
19
20 import java.util.ConcurrentModificationException;
21 import java.util.Set;
22 import java.util.stream.Stream;
23
24 import org.apache.commons.rdf.api.BlankNodeOrIRI;
25 import org.apache.commons.rdf.api.Graph;
26 import org.apache.commons.rdf.api.IRI;
27 import org.apache.commons.rdf.api.RDFTerm;
28 import org.apache.commons.rdf.api.Triple;
29 import org.eclipse.rdf4j.model.Model;
30 import org.eclipse.rdf4j.repository.Repository;
31
32 /**
33 * Marker interface for RDF4J implementations of Graph.
34 *
35 * @see RDF4J#createGraph()
36 * @see RDF4J#asGraph(Model)
37 * @see RDF4J#asGraph(Repository, Option...)
38 * @see RDF4J#asGraphUnion(Repository, Option...)
39 * @see RDF4JDataset#getGraph()
40 * @see RDF4JDataset#getGraph(BlankNodeOrIRI)
41 */
42 public interface RDF4JGraph extends Graph, RDF4JGraphLike<Triple> {
43
44 /**
45 * Return a copy of the context mask as a {@link Set} of
46 * {@link RDF4JBlankNodeOrIRI} graph names.
47 * <p>
48 * If the set is not {@link Set#isEmpty()}, the mask determines which
49 * <em>contexts</em> in the corresponding RDF4J {@link Model} or
50 * {@link Repository} that this graph reflect. Modifications to the graph
51 * (e.g. {@link #add(Triple)} will be performed for all the specified
52 * contexts, while retrieval (e.g. {@link #contains(Triple)}) will succeed
53 * if the triple is in at least one of the specified contexts.
54 * <p>
55 * The context mask array may contain <code>null</code>, indicating the
56 * default context (the <em>default graph</em> in RDF datasets).
57 * <p>
58 * If the context mask is {@link Set#isEmpty()}, then this is a <em>union
59 * graph</em> which triples reflect statements in any contexts. Triples
60 * added to the graph will be added in the default context, e.g. equivalent
61 * to <code>new Resource[1]{null}</code>) in RDF4J.
62 * <p>
63 * Note that the context mask itself cannot be <code>null</code>.
64 * <p>
65 * The returned set is an immutable copy; to specify a different mask, use
66 * {@link RDF4J#asGraph(Repository, Set, Option...)}
67 *
68 * @return The context mask as a set of {@link BlankNodeOrIRI} graph names,
69 * which may contain the value <code>null</code>.
70 */
71 Set<RDF4JBlankNodeOrIRI> getContextMask();
72
73 /**
74 * {@inheritDoc}
75 * <p>
76 * Note that for graphs backed by a repository ({@link #asRepository()} is
77 * present), the stream <strong>must be closed</strong> with
78 * {@link Stream#close()}.
79 * <p>
80 * This can generally achieved using a try-with-resources block, e.g.:
81 *
82 * <pre>
83 * int subjects;
84 * try (Stream<RDF4JTriple> s : graph.stream()) {
85 * subjects = s.map(RDF4JTriple::getSubject).distinct().count()
86 * }
87 * </pre>
88 */
89 @Override
90 Stream<RDF4JTriple> stream();
91
92 /**
93 * {@inheritDoc}
94 * <p>
95 * Note that for graphs backed by a repository ({@link #asRepository()} is
96 * present), the stream <strong>must be closed</strong> with
97 * {@link Stream#close()}.
98 * <p>
99 * This can generally achieved using a try-with-resources block, e.g.:
100 *
101 * <pre>
102 * int subjects;
103 * try (Stream<RDF4JTriple> s : graph.stream(s,p,o)) {
104 * subjects = s.map(RDF4JTriple::getSubject).distinct().count()
105 * }
106 * </pre>
107 */
108 @Override
109 Stream<RDF4JTriple> stream(BlankNodeOrIRI subject, IRI predicate, RDFTerm object);
110
111 /**
112 * {@inheritDoc}
113 * <p>
114 * Note that for graphs backed by a repository ({@link #asRepository()} is
115 * present), the iterable <strong>must be closed</strong> with
116 * {@link ClosableIterable#close()}.
117 * <p>
118 * This can generally achieved using a try-with-resources block, e.g.:
119 *
120 * <pre>
121 * try (ClosableIterable<Triple> s : graph.iterate()) {
122 * for (Triple t : triples) {
123 * return t; // OK to terminate for-loop early
124 * }
125 * }
126 * </pre>
127 *
128 * If you don't use a try-with-resources block, the iterator will attempt to
129 * close the ClosableIterable when reaching the end of the iteration.
130 */
131 @Override
132 ClosableIterable<Triple> iterate() throws ConcurrentModificationException, IllegalStateException;
133
134 /**
135 * {@inheritDoc}
136 * <p>
137 * Note that for graphs backed by a repository ({@link #asRepository()} is
138 * present), the iterable <strong>must be closed</strong> with
139 * {@link ClosableIterable#close()}.
140 * <p>
141 * This can generally achieved using a try-with-resources block, e.g.:
142 *
143 * <pre>
144 * try (ClosableIterable<Triple> s : graph.iterate(s,p,o)) {
145 * for (Triple t : triples) {
146 * return t; // OK to terminate for-loop early
147 * }
148 * }
149 * </pre>
150 *
151 * If you don't use a try-with-resources block, the iterator will attempt to
152 * close the ClosableIterable when reaching the end of the iteration.
153 */
154 @Override
155 ClosableIterable<Triple> iterate(BlankNodeOrIRI subject, IRI predicate, RDFTerm object);
156 }