1 package ubic.basecode.ontology.providers;
2
3 import ubic.basecode.ontology.model.OntologyIndividual;
4 import ubic.basecode.ontology.model.OntologyResource;
5 import ubic.basecode.ontology.model.OntologyTerm;
6 import ubic.basecode.ontology.search.OntologySearchException;
7 import ubic.basecode.ontology.search.OntologySearchResult;
8
9 import org.jspecify.annotations.Nullable;
10 import java.io.InputStream;
11 import java.util.Collection;
12 import java.util.Set;
13
14 public interface OntologyService extends AutoCloseable {
15
16 /**
17 * Obtain the name of this ontology if available.
18 */
19 @Nullable
20 String getName();
21
22 /**
23 * Obtain a description of this ontology if available.
24 */
25 @Nullable
26 String getDescription();
27
28 /**
29 * Check if this ontology will process imports.
30 * <p>
31 * If disabled, ontologies imported by this ontology will not be loaded.
32 */
33 boolean getProcessImports();
34
35 /**
36 * Allow of forbid this ontology to process imports.
37 * <p>
38 * Changes are applicable only if the service is re-initialized.
39 */
40 void setProcessImports( boolean processImports );
41
42 enum LanguageLevel {
43 /**
44 * The full OWL language.
45 */
46 FULL,
47 /**
48 * OWL-DL
49 */
50 DL,
51 /**
52 * OWL/Lite
53 */
54 LITE
55 }
56
57
58 /**
59 * Obtain the OWL language level supported by this ontology.
60 * <p>
61 * The default is to use {@link LanguageLevel#FULL}.
62 */
63 LanguageLevel getLanguageLevel();
64
65 /**
66 * Set the OWL language level supported by this ontology.
67 * <p>
68 * Changes are applicable only if the service is re-initialized.
69 */
70 void setLanguageLevel( LanguageLevel languageLevel );
71
72 enum InferenceMode {
73 /**
74 * No inference is supported, only the axioms defined in the ontology are considered.
75 */
76 NONE,
77 /**
78 * Only basic inference is supported for {@code rdfs:subClassOf} and {@code rdfs:subPropertyOf}.
79 * <p>
80 * This is the fastest inference mode.
81 */
82 TRANSITIVE,
83 /**
84 * Very limited inference.
85 */
86 MICRO,
87 /**
88 * Limited inference.
89 */
90 MINI,
91 /**
92 * Complete inference.
93 * <p>
94 * This is the slowest inference mode.
95 */
96 FULL
97 }
98
99 /**
100 * Obtain the inference mode used for this ontology.
101 * <p>
102 * The default is {@link InferenceMode#TRANSITIVE}.
103 */
104 InferenceMode getInferenceMode();
105
106 /**
107 * Set the inference mode used for this ontology.
108 * <p>
109 * Changes are applicable only if the service is re-initialized.
110 */
111 void setInferenceMode( InferenceMode inferenceMode );
112
113 /**
114 * Check if this ontology has full-text search enabled.
115 * <p>
116 * This is necessary for finding term using full-text queries. If enabled, an index will be generated in during
117 * initialization by {@link #initialize(boolean, boolean)}.
118 * <p>
119 * Search is enabled by default.
120 *
121 * @see #findTerm(String, int, boolean)
122 * @see #findIndividuals(String, int, boolean)
123 * @see #findResources(String, int, boolean)
124 */
125 boolean isSearchEnabled();
126
127 /**
128 * Enable or disable search for this ontology.
129 * <p>
130 * Changes are only applicable if the service is re-initialized.
131 */
132 void setSearchEnabled( boolean searchEnabled );
133
134 /**
135 * Obtain the words that should be excluded from stemming.
136 * <p>
137 * By default, all words are subject to stemming. The exact implementation of stemming depends on the actual search
138 * implementation.
139 */
140 Set<String> getExcludedWordsFromStemming();
141
142 /**
143 * Set words that should be excluded from stemming when searching.
144 */
145 void setExcludedWordsFromStemming( Set<String> excludedWordsFromStemming );
146
147 /**
148 * Obtain the URIs used as additional properties when inferring parents and children.
149 * <p>
150 * The default is to use <a href="http://purl.obolibrary.org/obo/BFO_0000050">part of</a>, <a href="http://www.obofoundry.org/ro/ro.owl#proper_part_of">proper part of</a>
151 * and all of their sub-properties if inference is enabled.
152 *
153 * @see #getParents(Collection, boolean, boolean, boolean)
154 * @see #getChildren(Collection, boolean, boolean, boolean)
155 */
156 Set<String> getAdditionalPropertyUris();
157
158 /**
159 * Set the URIs to be used as additional properties when inferring parents and children.
160 * <p>
161 * Changes are applicable only if the service is re-initialized.
162 */
163 void setAdditionalPropertyUris( Set<String> additionalPropertyUris );
164
165 /**
166 * Initialize this ontology service.
167 *
168 * @param forceLoad Force loading of ontology, even if it is already loaded
169 * @param forceIndexing If forceLoad is also true, indexing will be performed. If you know the index is up-to-date,
170 * there's no need to do it again. Normally indexing is only done if there is no index, or if
171 * the ontology has changed since last loaded.
172 */
173 void initialize( boolean forceLoad, boolean forceIndexing );
174
175 /**
176 * Initialize this ontology service from a stream.
177 * <p>
178 * Note that when this method of initialization is used, the ontology cache is not created on-disk.
179 */
180 void initialize( InputStream stream, boolean forceIndexing );
181
182 /**
183 * Looks for any individuals that match the given search string.
184 * <p>
185 * Obsolete terms are filtered out.
186 */
187 default Collection<OntologySearchResult<OntologyIndividual>> findIndividuals( String search, int maxResults ) throws OntologySearchException {
188 return findIndividuals( search, maxResults, false );
189 }
190
191 /**
192 * Looks for any individuals that match the given search string.
193 *
194 * @param search search query
195 * @param keepObsoletes retain obsolete terms
196 */
197 Collection<OntologySearchResult<OntologyIndividual>> findIndividuals( String search, int maxResults, boolean keepObsoletes ) throws OntologySearchException;
198
199 /**
200 * Looks for any resources (terms or individuals) that match the given search string
201 * <p>
202 * Obsolete terms are filtered out.
203 *
204 * @return results, or an empty collection if the results are empty OR the ontology is not available to be
205 * searched.
206 */
207 default Collection<OntologySearchResult<OntologyResource>> findResources( String searchString, int maxResults ) throws OntologySearchException {
208 return findResources( searchString, maxResults, false );
209 }
210
211 /**
212 * Looks for any resources (terms or individuals) that match the given search string
213 *
214 * @param search search query
215 * @param keepObsoletes retain obsolete terms
216 */
217 Collection<OntologySearchResult<OntologyResource>> findResources( String search, int maxResults, boolean keepObsoletes ) throws OntologySearchException;
218
219 /**
220 * Looks for any terms that match the given search string.
221 * <p>
222 * Obsolete terms are filtered out.
223 */
224 default Collection<OntologySearchResult<OntologyTerm>> findTerm( String search, int maxResults ) throws OntologySearchException {
225 return findTerm( search, maxResults, false );
226 }
227
228
229 /**
230 * Looks for any terms that match the given search string.
231 *
232 * @param search search query
233 * @param keepObsoletes retain obsolete terms
234 */
235 Collection<OntologySearchResult<OntologyTerm>> findTerm( String search, int maxResults, boolean keepObsoletes ) throws OntologySearchException;
236
237 /**
238 * Find a term using an alternative ID.
239 */
240 @Nullable
241 OntologyTerm findUsingAlternativeId( String alternativeId );
242
243 /**
244 * Obtain all the resource URIs in this ontology.
245 */
246 Set<String> getAllURIs();
247
248 /**
249 * Looks through both Terms and Individuals for a OntologyResource that has a uri matching the uri given. If no
250 * OntologyTerm is found only then will ontologyIndividuals be searched. returns null if nothing is found.
251 */
252 @Nullable
253 OntologyResource getResource( String uri );
254
255 /**
256 * Looks for a OntologyTerm that has the match in URI given
257 */
258 @Nullable
259 OntologyTerm getTerm( String uri );
260
261 /**
262 * Obtain all the individuals for a given term URI.
263 */
264 Collection<OntologyIndividual> getTermIndividuals( String uri );
265
266 /**
267 * Obtain all the parents of a given set of terms, excluding obsolete terms.
268 *
269 * @see #getParents(Collection, boolean, boolean, boolean)
270 */
271 default Set<OntologyTerm> getParents( Collection<OntologyTerm> terms, boolean direct, boolean includeAdditionalProperties ) {
272 return getParents( terms, direct, includeAdditionalProperties, false );
273 }
274
275 /**
276 * Obtain all the parents of a given set of terms.
277 *
278 * @param terms set of terms whose parents are retrieved
279 * @param direct only retain direct parents
280 * @param includeAdditionalProperties also include parents matched via additional properties
281 * @param keepObsoletes retain obsolete terms
282 * @return a set of parent terms
283 */
284 Set<OntologyTerm> getParents( Collection<OntologyTerm> terms, boolean direct, boolean includeAdditionalProperties, boolean keepObsoletes );
285
286 /**
287 * Obtain all the children of a given set of terms, excluding obsolete terms.
288 *
289 * @see #getChildren(Collection, boolean, boolean, boolean)
290 */
291 default Set<OntologyTerm> getChildren( Collection<OntologyTerm> terms, boolean direct, boolean includeAdditionalProperties ) {
292 return getChildren( terms, direct, includeAdditionalProperties, false );
293 }
294
295 /**
296 * Obtain all the children of a given set of terms.
297 *
298 * @param terms set of terms whose children are retrieved
299 * @param direct only retain direct children
300 * @param includeAdditionalProperties also include children matched via additional properties
301 * @param keepObsoletes retain obsolete terms
302 * @return a set of child terms
303 */
304 Set<OntologyTerm> getChildren( Collection<OntologyTerm> terms, boolean direct, boolean includeAdditionalProperties, boolean keepObsoletes );
305
306 /**
307 * Check if this ontology is enabled.
308 */
309 boolean isEnabled();
310
311 /**
312 * Used for determining if the Ontology has finished loading into memory. Although calls like getParents,
313 * getChildren will still work (its much faster once the ontologies have been preloaded into memory.)
314 */
315 boolean isOntologyLoaded();
316
317 /**
318 * Start the initialization thread.
319 * <p>
320 * If the initialization thread is already running, this method does nothing. If the initialization thread
321 * previously completed, the ontology will be reinitialized.
322 *
323 * @param forceLoad Force loading of ontology, even if it is already loaded
324 * @param forceIndexing If forceLoad is also true, indexing will be performed. If you know the index is
325 * up to date, there's no need to do it again. Normally indexing is only done if there is no
326 * index, or if the ontology has changed since last loaded.
327 */
328 void startInitializationThread( boolean forceLoad, boolean forceIndexing );
329
330 /**
331 * Check if the initialization thread is alive.
332 */
333 boolean isInitializationThreadAlive();
334
335 /**
336 * Check if the initialization thread is cancelled.
337 */
338 boolean isInitializationThreadCancelled();
339
340 /**
341 * Cancel a running initialization thread.
342 */
343 void cancelInitializationThread();
344
345 /**
346 * Wait for the initialization thread to finish.
347 */
348 void waitForInitializationThread() throws InterruptedException;
349
350 /**
351 * Index the ontology for performing full-text searches.
352 *
353 * @param force if true, perform indexing even if an index already exists
354 * @see #findIndividuals(String, int) (String)
355 * @see #findTerm(String, int)
356 * @see #findResources(String, int)
357 */
358 void index( boolean force );
359
360 /**
361 * For testing! Overrides normal way of loading the ontology. This does not index the ontology unless 'force' is
362 * true (if there is an existing index, it will be used)
363 *
364 * @param is input stream from which the ontology model is loaded
365 * @param forceIndex initialize the index. Otherwise it will only be initialized if it doesn't exist.
366 * @deprecated use {@link #initialize(InputStream, boolean)} instead and possibly {@link #cancelInitializationThread()}
367 * prior to get any running initialization thread out of the way
368 */
369 @Deprecated
370 void loadTermsInNameSpace( InputStream is, boolean forceIndex );
371 }