Package: Connection

Connection

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;
19:
20: import cz.cvut.kbss.ontodriver.descriptor.AxiomDescriptor;
21: import cz.cvut.kbss.ontodriver.descriptor.AxiomValueDescriptor;
22: import cz.cvut.kbss.ontodriver.exception.OntoDriverException;
23: import cz.cvut.kbss.ontodriver.model.Axiom;
24: import cz.cvut.kbss.ontodriver.model.NamedResource;
25:
26: import java.net.URI;
27: import java.util.Collection;
28: import java.util.List;
29: import java.util.Set;
30:
31: public interface Connection extends AutoCloseable, Wrapper {
32:
33: /**
34: * Whether this connection is active.
35: *
36: * @return Active status of this connection
37: */
38: boolean isOpen();
39:
40: /**
41: * Commits this connection.
42: * <p>
43: * This effectively makes persistent any changes made since the last commit/rollback or since this connection was
44: * opened.
45: * <p>
46: * If this connection is in auto-commit mode, calling this method has no effect.
47: *
48: * @throws OntoDriverException If an ontology access error occurs
49: * @throws IllegalStateException If called on a closed connection
50: */
51: void commit() throws OntoDriverException;
52:
53: /**
54: * Rolls back any changes made in the current transaction.
55: * <p>
56: * If this connection is in auto-commit mode, calling this method has no effect.
57: *
58: * @throws OntoDriverException If an ontology access error occurs
59: * @throws IllegalStateException If called on a closed connection
60: */
61: void rollback() throws OntoDriverException;
62:
63: /**
64: * Sets this connection's auto-commit mode to the specified state.
65: *
66: * @param autoCommit The new auto-commit state
67: * @throws IllegalStateException If called on a closed connection
68: */
69: void setAutoCommit(boolean autoCommit);
70:
71: /**
72: * Returns this connection's auto-commit mode.
73: *
74: * @return {@code true} if this connection is in auto-commit mode, {@code false} otherwise
75: * @throws IllegalStateException If called on a closed connection
76: */
77: boolean isAutoCommit();
78:
79: /**
80: * Creates a new SPARQL statement.
81: *
82: * @return a {@code Statement} instance
83: * @throws OntoDriverException If an ontology access error occurs
84: * @throws IllegalStateException If called on a closed connection
85: */
86: Statement createStatement() throws OntoDriverException;
87:
88: /**
89: * Creates and returns a new prepared SPARQL statement.
90: *
91: * @param sparql The query to prepare
92: * @return {@code PreparedStatement}
93: * @throws OntoDriverException If an ontology access error occurs
94: * @throws IllegalStateException If called on a closed connection
95: */
96: PreparedStatement prepareStatement(String sparql) throws OntoDriverException;
97:
98: /**
99: * Verifies consistency of ontology context with the specified URI
100: * <p>
101: * Note that {@code null} argument means checking consistency of the whole repository.
102: *
103: * @param context Context identifier, can be {@code null}
104: * @return Consistency status
105: * @throws OntoDriverException If an ontology access error occurs
106: * @throws IllegalStateException If called on a closed connection
107: */
108: boolean isConsistent(URI context) throws OntoDriverException;
109:
110: /**
111: * Gets a set of currently available contexts in the underlying repository.
112: * <p>
113: * Note that the default context is not included in the result.
114: *
115: * @return List of context URIs
116: * @throws OntoDriverException If an ontology access error occurs
117: * @throws IllegalStateException If called on a closed connection
118: */
119: List<URI> getContexts() throws OntoDriverException;
120:
121: /**
122: * Checks whether the storage contains the specified axiom.
123: * <p>
124: * The contexts optionally specify repository contexts in which to look for the axiom.
125: *
126: * @param axiom The axiom to look for
127: * @param contexts Optional search contexts, an empty set means to look in the default storage context
128: * @return {@code true} if the storage contains matching axiom, {@code false} otherwise
129: * @throws OntoDriverException If an ontology access error occurs
130: * @throws IllegalStateException If called on a closed connection
131: */
132: boolean contains(Axiom<?> axiom, Set<URI> contexts) throws OntoDriverException;
133:
134: /**
135: * Checks whether the specified axiom is inferred in the underlying repository.
136: * <p>
137: * The contexts optionally specify repository contexts in which to look for the axiom. However, note that different
138: * triple stores treat inference differently and inferred statements may be stored in a special context. In this
139: * case, the implementation may choose to ignore the provided set of contexts.
140: * <p>
141: * Also note that since most underlying repository access implementations do not allow retrieving inferred
142: * statements only and instead provide either only asserted or asserted + inferred statements, this method may
143: * return {@code false} in case the repository contains the axiom both inferred and asserted.
144: *
145: * @param axiom Axiom whose inference to check
146: * @param contexts Optional search contexts, an empty set means to look in the default storage context
147: * @return {@code true} if the repository inferred the specified axiom, {@code false} if the axiom is asserted or
148: * not present at all
149: * @throws OntoDriverException If an ontology access error occurs
150: * @throws IllegalStateException If called on a closed connection
151: */
152: boolean isInferred(Axiom<?> axiom, Set<URI> contexts) throws OntoDriverException;
153:
154: /**
155: * Finds axioms with the corresponding subject and properties.
156: *
157: * @param descriptor Loading descriptor specifies subject, properties to load and possible contexts to work with
158: * @return Collection of axioms matching the specified criteria
159: * @throws OntoDriverException If an ontology access error occurs
160: * @throws IllegalStateException If called on a closed connection
161: */
162: Collection<Axiom<?>> find(AxiomDescriptor descriptor) throws OntoDriverException;
163:
164: /**
165: * Persists new individual and its property values specified by the descriptor.
166: *
167: * @param descriptor Descriptor of the persisted values
168: * @throws OntoDriverException If an ontology access error occurs
169: * @throws IllegalStateException If called on a closed connection
170: */
171: void persist(AxiomValueDescriptor descriptor) throws OntoDriverException;
172:
173: /**
174: * Generates a new unique identifier based on the specified type.
175: * <p>
176: * The identifier is required to be unique in the whole repository.
177: *
178: * @param classUri OWL class identifier
179: * @return Unique identifier
180: * @throws OntoDriverException If an ontology access error occurs
181: */
182: URI generateIdentifier(URI classUri) throws OntoDriverException;
183:
184: /**
185: * Persists the values specified by this descriptor, removing existing property values from the ontology.
186: * <p>
187: * This method removes original values of properties specified in the descriptor and persists new values specified
188: * therein.
189: *
190: * @param descriptor Descriptor of the update values
191: * @throws OntoDriverException If an ontology access error occurs
192: * @throws IllegalStateException If called on a closed connection
193: */
194: void update(AxiomValueDescriptor descriptor) throws OntoDriverException;
195:
196: /**
197: * Removes all axioms related to subject specified by the descriptor.
198: * <p>
199: * The descriptor may also specify contexts from which property assertion axioms should be removed.
200: * <p>
201: * Note that this method will cause also removal of axioms in which the {@link NamedResource} specified by the
202: * argument stands as value.
203: *
204: * @param descriptor Descriptor of contexts and the subject of removal
205: * @throws OntoDriverException If an ontology access error occurs
206: * @throws IllegalStateException If called on a closed connection
207: */
208: void remove(AxiomDescriptor descriptor) throws OntoDriverException;
209:
210: /**
211: * Gets ontology lists handler.
212: *
213: * @return Lists handler
214: */
215: Lists lists();
216:
217: /**
218: * Gets types handler.
219: *
220: * @return Types handler
221: */
222: Types types();
223:
224: /**
225: * Gets handler for unmapped properties.
226: *
227: * @return Properties handler
228: */
229: Properties properties();
230: }