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
8 import javax.annotation.Nullable;
9 import java.io.InputStream;
10 import java.util.Collection;
11 import java.util.Set;
12
13 public interface OntologyService {
14
15 /**
16 * Initialize this ontology service.
17 *
18 * @param forceLoad Force loading of ontology, even if it is already loaded
19 * @param forceIndexing If forceLoad is also true, indexing will be performed. If you know the index is up-to-date,
20 * there's no need to do it again. Normally indexing is only done if there is no index, or if
21 * the ontology has changed since last loaded.
22 */
23 void initialize( boolean forceLoad, boolean forceIndexing );
24
25 /**
26 * Initialize this ontology service from a stream.
27 * <p>
28 * Note that when this method of initialization is used, the ontology cache is not created on-disk.
29 */
30 void initialize( InputStream stream, boolean forceIndexing );
31
32 /**
33 * Looks for any individuals that match the given search string.
34 * <p>
35 * Obsolete terms are filtered out.
36 */
37 default Collection<OntologyIndividual> findIndividuals( String search ) throws OntologySearchException {
38 return findIndividuals( search, false );
39 }
40
41 /**
42 * Looks for any individuals that match the given search string.
43 *
44 * @param search search query
45 * @param keepObsoletes retain obsolete terms
46 */
47 Collection<OntologyIndividual> findIndividuals( String search, boolean keepObsoletes ) throws OntologySearchException;
48
49 /**
50 * Looks for any resources (terms or individuals) that match the given search string
51 * <p>
52 * Obsolete terms are filtered out.
53 *
54 * @return results, or an empty collection if the results are empty OR the ontology is not available to be
55 * searched.
56 */
57 default Collection<OntologyResource> findResources( String searchString ) throws OntologySearchException {
58 return findResources( searchString, false );
59 }
60
61 /**
62 * Looks for any resources (terms or individuals) that match the given search string
63 *
64 * @param search search query
65 * @param keepObsoletes retain obsolete terms
66 */
67 Collection<OntologyResource> findResources( String search, boolean keepObsoletes ) throws OntologySearchException;
68
69 /**
70 * Looks for any terms that match the given search string.
71 * <p>
72 * Obsolete terms are filtered out.
73 */
74 default Collection<OntologyTerm> findTerm( String search ) throws OntologySearchException {
75 return findTerm( search, false );
76 }
77
78
79 /**
80 * Looks for any terms that match the given search string.
81 *
82 * @param search search query
83 * @param keepObsoletes retain obsolete terms
84 */
85 Collection<OntologyTerm> findTerm( String search, boolean keepObsoletes ) throws OntologySearchException;
86
87 /**
88 * Find a term using an alternative ID.
89 */
90 @Nullable
91 OntologyTerm findUsingAlternativeId( String alternativeId );
92
93 /**
94 * Obtain all the resource URIs in this ontology.
95 */
96 Set<String> getAllURIs();
97
98 /**
99 * Looks through both Terms and Individuals for a OntologyResource that has a uri matching the uri given. If no
100 * OntologyTerm is found only then will ontologyIndividuals be searched. returns null if nothing is found.
101 */
102 @Nullable
103 OntologyResource getResource( String uri );
104
105 /**
106 * Looks for a OntologyTerm that has the match in URI given
107 */
108 @Nullable
109 OntologyTerm getTerm( String uri );
110
111 /**
112 * Obtain all the individuals for a given term URI.
113 */
114 Collection<OntologyIndividual> getTermIndividuals( String uri );
115
116 /**
117 * Obtain all the parents of a given set of terms, excluding obsolete terms.
118 *
119 * @see #getParents(Collection, boolean, boolean, boolean)
120 */
121 default Set<OntologyTerm> getParents( Collection<OntologyTerm> terms, boolean direct, boolean includeAdditionalProperties ) {
122 return getParents( terms, direct, includeAdditionalProperties, false );
123 }
124
125 /**
126 * Obtain all the parents of a given set of terms.
127 *
128 * @param terms set of terms whose parents are retrieved
129 * @param direct only retain direct parents
130 * @param includeAdditionalProperties also include parents matched via additional properties
131 * @param keepObsoletes retain obsolete terms
132 * @return a set of parent terms
133 */
134 Set<OntologyTerm> getParents( Collection<OntologyTerm> terms, boolean direct, boolean includeAdditionalProperties, boolean keepObsoletes );
135
136 /**
137 * Obtain all the children of a given set of terms, excluding obsolete terms.
138 *
139 * @see #getChildren(Collection, boolean, boolean, boolean)
140 */
141 default Set<OntologyTerm> getChildren( Collection<OntologyTerm> terms, boolean direct, boolean includeAdditionalProperties ) {
142 return getChildren( terms, direct, includeAdditionalProperties, false );
143 }
144
145 /**
146 * Obtain all the children of a given set of terms.
147 *
148 * @param terms set of terms whose children are retrieved
149 * @param direct only retain direct children
150 * @param includeAdditionalProperties also include children matched via additional properties
151 * @param keepObsoletes retain obsolete terms
152 * @return a set of child terms
153 */
154 Set<OntologyTerm> getChildren( Collection<OntologyTerm> terms, boolean direct, boolean includeAdditionalProperties, boolean keepObsoletes );
155
156
157 /**
158 * Check if this ontology is enabled.
159 */
160 boolean isEnabled();
161
162 /**
163 * Used for determining if the Ontology has finished loading into memory. Although calls like getParents,
164 * getChildren will still work (its much faster once the ontologies have been preloaded into memory.)
165 */
166 boolean isOntologyLoaded();
167
168 /**
169 * Start the initialization thread.
170 * <p>
171 * If the initialization thread is already running, this method does nothing. If the initialization thread
172 * previously completed, the ontology will be reinitialized.
173 *
174 * @param forceLoad Force loading of ontology, even if it is already loaded
175 * @param forceIndexing If forceLoad is also true, indexing will be performed. If you know the index is
176 * up to date, there's no need to do it again. Normally indexing is only done if there is no
177 * index, or if the ontology has changed since last loaded.
178 */
179 void startInitializationThread( boolean forceLoad, boolean forceIndexing );
180
181 /**
182 * Check if the initialization thread is alive.
183 */
184 boolean isInitializationThreadAlive();
185
186 /**
187 * Check if the initialization thread is cancelled.
188 */
189 boolean isInitializationThreadCancelled();
190
191 /**
192 * Cancel a running initialization thread.
193 */
194 void cancelInitializationThread();
195
196 /**
197 * Wait for the initialization thread to finish.
198 */
199 void waitForInitializationThread() throws InterruptedException;
200
201 /**
202 * Index the ontology for performing full-text searches.
203 *
204 * @param force if true, perform indexing even if an index already exists
205 * @see #findIndividuals(String)
206 * @see #findTerm(String)
207 * @see #findResources(String)
208 */
209 void index( boolean force );
210
211 /**
212 * For testing! Overrides normal way of loading the ontology. This does not index the ontology unless 'force' is
213 * true (if there is an existing index, it will be used)
214 *
215 * @param is input stream from which the ontology model is loaded
216 * @param forceIndex initialize the index. Otherwise it will only be initialized if it doesn't exist.
217 * @deprecated use {@link #initialize(InputStream, boolean)} instead and possibly {@link #cancelInitializationThread()}
218 * prior to get any running initialization thread out of the way
219 */
220 @Deprecated
221 void loadTermsInNameSpace( InputStream is, boolean forceIndex );
222 }