Package: Connector

Connector

Coverage

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