Package: Connector

Connector

Coverage

1: /*
2: * JOPA
3: * Copyright (C) 2023 Czech Technical University in Prague
4: *
5: * This library is free software; you can redistribute it and/or
6: * modify it under the terms of the GNU Lesser General Public
7: * License as published by the Free Software Foundation; either
8: * version 3.0 of the License, or (at your option) any later version.
9: *
10: * This library is distributed in the hope that it will be useful,
11: * but WITHOUT ANY WARRANTY; without even the implied warranty of
12: * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
13: * Lesser General Public License for more details.
14: *
15: * You should have received a copy of the GNU Lesser General Public
16: * License along with this library.
17: */
18: package cz.cvut.kbss.ontodriver.rdf4j.connector;
19:
20: import cz.cvut.kbss.ontodriver.Closeable;
21: import cz.cvut.kbss.ontodriver.Wrapper;
22: import cz.cvut.kbss.ontodriver.rdf4j.exception.Rdf4jDriverException;
23: import org.eclipse.rdf4j.model.IRI;
24: import org.eclipse.rdf4j.model.Resource;
25: import org.eclipse.rdf4j.model.Statement;
26: import org.eclipse.rdf4j.model.Value;
27: import org.eclipse.rdf4j.model.ValueFactory;
28:
29: import java.util.Collection;
30: import java.util.List;
31: import java.util.Set;
32:
33: /**
34: * A RDF4J repository connection wrapper.
35: */
36: public interface Connector extends Closeable, StatementExecutor, Wrapper {
37:
38: /**
39: * Explicitly starts a transaction.
40: *
41: * @throws Rdf4jDriverException If unable to start transaction
42: */
43: void begin() throws Rdf4jDriverException;
44:
45: /**
46: * Commits the changes made since transaction beginning.
47: *
48: * @throws Rdf4jDriverException If an error occurs during commit
49: * @see #begin()
50: */
51: void commit() throws Rdf4jDriverException;
52:
53: /**
54: * Rolls back changes made since transaction beginning.
55: *
56: * @throws Rdf4jDriverException If an error occurs when rolling back
57: * @see #begin()
58: */
59: void rollback() throws Rdf4jDriverException;
60:
61: /**
62: * Gets resources representing currently existing contexts in the repository.
63: *
64: * @return List of resources
65: * @throws Rdf4jDriverException If repository access error occurs
66: */
67: List<Resource> getContexts() throws Rdf4jDriverException;
68:
69: /**
70: * Gets Rdf4j value factory.
71: *
72: * @return {@link ValueFactory}
73: */
74: ValueFactory getValueFactory();
75:
76: /**
77: * Finds statements corresponding to the specified criteria.
78: * <p>
79: * Note that some of the parameters are optional.
80: * <p>
81: * This version searches the default context.
82: *
83: * @param subject Statement subject, optional
84: * @param property Statement property, optional
85: * @param value Statement value, optional
86: * @param includeInferred Whether to include inferred statements as well
87: * @return Collection of matching statements
88: * @throws Rdf4jDriverException If a repository access error occurs
89: * @see #findStatements(Resource, IRI, Value, boolean, Set)
90: */
91: Collection<Statement> findStatements(Resource subject, IRI property, Value value, boolean includeInferred)
92: throws Rdf4jDriverException;
93:
94: /**
95: * Finds statements corresponding to the specified criteria.
96: * <p>
97: * Note that some parameters are optional
98: *
99: * @param subject Statement subject, optional
100: * @param property Statement property, optional
101: * @param value Statement value, optional
102: * @param includeInferred Whether to include inferred statements as well
103: * @param contexts Contexts in which the search should be performed. Empty collection indicates the default
104: * context will be searched
105: * @return Collection of matching statements
106: * @throws Rdf4jDriverException If a repository access error occurs
107: */
108: Collection<Statement> findStatements(Resource subject, IRI property, Value value,
109: boolean includeInferred, Set<IRI> contexts)
110: throws Rdf4jDriverException;
111:
112: /**
113: * Checks whether the repository contains any statements matching the specified criteria.
114: *
115: * @param subject Statement subject, optional
116: * @param property Statement property, optional
117: * @param value Statement value, optional
118: * @param includeInferred Whether to include inferred statements as well
119: * @param contexts Optionally specify contexts in which the search should be performed. If empty, the default
120: * one is used
121: * @return Boolean indicating whether the statement exists
122: * @throws Rdf4jDriverException If a repository access error occurs
123: */
124: boolean containsStatement(Resource subject, IRI property, Value value, boolean includeInferred,
125: Set<IRI> contexts)
126: throws Rdf4jDriverException;
127:
128: /**
129: * Checks whether the specified statement is inferred by the repository.
130: * <p>
131: * Note that given the nature of the RDF4J API, this method will return {@code false} even if the statement is both
132: * asserted and inferred, as there is no way to easily ask only for inferred statements but both asserted and
133: * inferred statements are returned.
134: * <p>
135: * Also note that if the repository does not contain the statement at all, {@code false} is returned.
136: *
137: * @param statement Statement whose inference to check
138: * @param contexts Optionally specify contexts in which the search should be performed. If empty, the default one
139: * is used
140: * @return {@code true} iff the specified statement is inferred in any of the specified contexts
141: * @throws Rdf4jDriverException If a repository access error occurs
142: */
143: boolean isInferred(Statement statement, Set<IRI> contexts) throws Rdf4jDriverException;
144:
145: /**
146: * Adds the specified statements to the underlying repository.
147: * <p>
148: * Note that this operation is transactional and the changes are required to be persistent only after successful
149: * {@link #commit()}.
150: *
151: * @param statements The statements to add
152: * @throws IllegalStateException If transaction is not active
153: * @throws Rdf4jDriverException If a repository access error occurs
154: */
155: void addStatements(Collection<Statement> statements) throws Rdf4jDriverException;
156:
157: /**
158: * Removes the specified statements from the underlying repository.
159: * <p>
160: * Note that this operation is transactional and the changes are required to be persistent only after successful
161: * {@link #commit()}.
162: *
163: * @param statements The statements to remove
164: * @throws IllegalStateException If transaction is not active
165: * @throws Rdf4jDriverException If a repository access error occurs
166: */
167: void removeStatements(Collection<Statement> statements) throws Rdf4jDriverException;
168:
169: /**
170: * Removes statements that have the specified subject and predicate pairs.
171: *
172: * @param spc Subject-predicate-contexts tuples
173: * @throws Rdf4jDriverException If a repository access error occurs
174: */
175: void removePropertyValues(Collection<SubjectPredicateContext> spc) throws Rdf4jDriverException;
176: }