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.stream.Stream;
22
23 /**
24 * A "graph-like" interface that contains {@link TripleLike} statements.
25 * <p>
26 * Extended by {@link Graph} (for {@link Triple}) and {@link Dataset} (for
27 * {@link Quad}).
28 * <p>
29 * Unlike {@link Graph} and {@link Dataset}, this interface can support
30 * generalised {@link TripleLike} or {@link QuadLike} statements, but does not
31 * imply semantics like {@link #size()} or the requirement of mapping
32 * {@link RDFTerm} instances from different implementations.
33 * <p>
34 * As {@link TripleLike} do not have a specific {@link Object#equals(Object)}
35 * semantics, the behaviour of methods like {@link #contains(TripleLike)} and
36 * {@link #remove(TripleLike)} is undefined for arguments that are not object
37 * identical to previously added or returned {@link TripleLike} statements.
38 *
39 * @param <T>
40 * A {@link TripleLike} type used by the graph methods, typically
41 * {@link Triple} or {@link Quad}
42 *
43 * @since 0.3.0-incubating
44 * @see Graph
45 * @see Dataset
46 * @see TripleLike
47 */
48 public interface GraphLike<T extends TripleLike> {
49
50 /**
51 * Add a statement.
52 *
53 * @param statement
54 * The TripleLike statement to add
55 */
56 void add(T statement);
57
58 /**
59 * Check if statement is contained.
60 *
61 * @param statement
62 * The {@link TripleLike} statement to check
63 * @return True if the statement is contained
64 */
65 boolean contains(T statement);
66
67 /**
68 * Add a statement.
69 *
70 * @param statement
71 * The TripleLike statement to add
72 */
73 void remove(T statement);
74
75 /**
76 * Remove all statements.
77 */
78 void clear();
79
80 /**
81 * Number of statements.
82 *
83 * @return Number of statements
84 */
85 long size();
86
87 /**
88 * Return a Stream of contained statements.
89 *
90 * @return A {@link Stream} of {@link TripleLike} statements.
91 */
92 Stream<? extends T> stream();
93
94 /**
95 * Iterate over contained statements.
96 *
97 * @return An {@link Iterable} of {@link TripleLike} statements.
98 * @throws IllegalStateException
99 * if the {@link Iterable} has been reused
100 * @throws ConcurrentModificationException
101 * if a concurrency conflict occurs while the Iterator is
102 * active.
103 */
104 Iterable<T> iterate() throws ConcurrentModificationException, IllegalStateException;
105
106 }