source: trunk/ontoCAT/src/uk/ac/ebi/ontocat/OntologyService.java @ 458

Revision 458, 10.9 KB checked in by tadamusiak, 12 months ago (diff)

added license boilerplate

updated build.xml, distribution now contains a top directory
Line 
1/**
2 * Copyright (c) 2010 - 2011 European Molecular Biology Laboratory and University of Groningen
3 *
4 * Contact: ontocat-users@lists.sourceforge.net
5 *
6 * This file is part of OntoCAT
7 *
8 * OntoCAT is free software: you can redistribute it and/or modify it under
9 * the terms of the GNU Lesser General Public License as published by the Free
10 * Software Foundation; either version 3 of the License, or (at your option) any
11 * later version.
12 *
13 * OntoCAT is distributed in the hope that it will be useful, but WITHOUT
14 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
15 * FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more
16 * details.
17 *
18 * You should have received a copy of the GNU Lesser General Public License along
19 * with OntoCAT. If not, see <http://www.gnu.org/licenses/>.
20 */
21package uk.ac.ebi.ontocat;
22
23import java.util.List;
24import java.util.Map;
25import java.util.Set;
26
27/**
28 * Ontology service interface, e.g. Bioportal REST or OLS
29 *
30 * @author Tomasz Adamusiak, Morris Swertz
31 */
32public interface OntologyService {
33        /**
34         * Enumeration for search options in searchAll and searchOntology. Without
35         * setting any options the search will be the most permissive, i.e. match
36         * substrings and in all properties.
37         * <p>
38         * EXACT - only exact matching of query. EXCLUE_PROPERTIES excludes -
39         * properties from search.
40         */
41        public enum SearchOptions {
42                EXACT, INCLUDE_PROPERTIES
43        };
44
45        /**
46         * Return a term.
47         *
48         * @param ontologyAccession
49         * @param termAccession
50         *
51         * @return OntologyTerm or null if nothing was found
52         * @throws OntologyServiceException
53         */
54        public OntologyTerm getTerm(String ontologyAccession, String termAccession)
55        throws OntologyServiceException;
56
57        /**
58         * Return a term using only its accession. This will only resolve correctly
59         * if the accession is unique within the service.
60         *
61         * @param termAccession
62         *            E.g. GO:00001
63         * @return OntologyTerm or null if nothing was found
64         * @throws OntologyServiceException
65         */
66        public OntologyTerm getTerm(String termAccession) throws OntologyServiceException;
67
68        /**
69         * Return a path to the root of the ontology. Returns a list of terms,
70         * starting with the root and finishing with the term itself.
71         *
72         * @param termAccession
73         * @return List of OntologyTerms or an empty list if nothing was found
74         * @throws OntologyServiceException
75         */
76        public List<OntologyTerm> getTermPath(String ontologyAccession, String termAccession)
77        throws OntologyServiceException;
78
79        /**
80         * Return a path to the root of the ontology. Returns a list of terms,
81         * starting with the root and finishing with the term itself.
82         *
83         * @param term
84         * @return List of OntologyTerms that has at least one element
85         * @throws OntologyServiceException
86         */
87        public List<OntologyTerm> getTermPath(OntologyTerm term) throws OntologyServiceException;
88
89        /**
90         * Return all available ontology accessions in a service.
91         *
92         * @return List of Ontologies or an empty list if nothing was found
93         * @throws OntologyServiceException
94         */
95        public List<Ontology> getOntologies() throws OntologyServiceException;
96
97        /**
98         * Return terms matching query within a particular ontology. Without setting
99         * any options the search will be the most permissive, i.e. match substrings
100         * and in all properties.
101         *
102         * @param ontologyAccession
103         * @param query
104         *            - query to be sent to the OntologyService, usually a keyword
105         *            to be searched for
106         * @param options
107         *            - EXACT - only exact matching of query. EXCLUDE_PROPERTIES
108         *            excludes - properties from search.
109         * @return List of OntologyTerms or an empty list if nothing was found
110         * @throws OntologyServiceException
111         */
112        public List<OntologyTerm> searchOntology(String ontologyAccession, String query,
113                        SearchOptions... options) throws OntologyServiceException;
114
115        /**
116         * Return terms matching query. Without setting any options the search will
117         * match substrings but will not include properties.
118         *
119         * @param query
120         *            - query to be sent to the OntologyService, usually a keyword
121         *            to be searched for
122         * @param options
123         *            - EXACT - only exact matching of query. INCLUDE_PROPERTIES -
124         *            includes properties in search.
125         * @return List of OntologyTerms or an empty list if nothing was found
126         * @throws OntologyServiceException
127         */
128        public List<OntologyTerm> searchAll(String query, SearchOptions... options)
129        throws OntologyServiceException;
130
131        /**
132         * Return the root terms for this ontology
133         *
134         * @param ontologyAccession
135         * @return List of OntologyTerms or an empty list if nothing was found
136         * @throws OntologyServiceException
137         */
138        public List<OntologyTerm> getRootTerms(String ontologyAccession)
139        throws OntologyServiceException;
140
141        /**
142         * Return the root terms for this ontology
143         *
144         * @param ontology
145         * @return List of OntologyTerms or an empty list if nothing was found
146         * @throws OntologyServiceException
147         */
148        public List<OntologyTerm> getRootTerms(Ontology ontology) throws OntologyServiceException;
149
150        /**
151         * Return child concepts for this termAccession
152         *
153         * @param termAccession
154         * @return List of OntologyTerms or an empty list if nothing was found
155         * @throws OntologyServiceException
156         */
157        public List<OntologyTerm> getChildren(String ontologyAccession, String termAccession)
158        throws OntologyServiceException;
159
160        /**
161         * Return child concepts for this termAccession
162         *
163         * @param term
164         * @return List of OntologyTerms or an empty list if nothing was found
165         * @throws OntologyServiceException
166         */
167        public List<OntologyTerm> getChildren(OntologyTerm term) throws OntologyServiceException;
168
169        /**
170         * Return parent concepts for this termAccession
171         *
172         * @param termAccession
173         * @return List of OntologyTerms or an empty list if nothing was found
174         * @throws OntologyServiceException
175         */
176        public List<OntologyTerm> getParents(String ontologyAccession, String termAccession)
177        throws OntologyServiceException;
178
179        /**
180         * Return parent concepts for a particular OntologyTerm
181         *
182         * @param term
183         * @return List of OntologyTerms or an empty list if nothing was found
184         * @throws OntologyServiceException
185         */
186        public List<OntologyTerm> getParents(OntologyTerm term) throws OntologyServiceException;
187
188        /**
189         * Return annotations for this termAccession.
190         *
191         * @param ontologyAccession
192         * @param termAccession
193         * @return Map of OntologyTerms or an empty map if nothing was found
194         * @throws OntologyServiceException
195         */
196        public Map<String, List<String>> getAnnotations(String ontologyAccession, String termAccession)
197        throws OntologyServiceException;
198
199        /**
200         * Return annotations for this termAccession.
201         *
202         * @param term
203         * @return Map of OntologyTerms or an empty map if nothing was found
204         * @throws OntologyServiceException
205         */
206        public Map<String, List<String>> getAnnotations(OntologyTerm term)
207        throws OntologyServiceException;
208
209        /**
210         * Return relations for this termAccession.
211         *
212         * @param ontologyAccession
213         * @param termAccession
214         * @return Map of OntologyTerms or an empty map if nothing was found
215         * @throws OntologyServiceException
216         */
217        public Map<String, Set<OntologyTerm>> getRelations(String ontologyAccession, String termAccession)
218        throws OntologyServiceException;
219
220        /**
221         * Return relations for this termAccession.
222         *
223         * @return Map of OntologyTerms or an empty map if nothing was found
224         * @throws OntologyServiceException
225         */
226        public Map<String, Set<OntologyTerm>> getRelations(OntologyTerm term)
227        throws OntologyServiceException;
228
229        /**
230         * Generate a hyperlink to drill down to ontology source.
231         *
232         * @param termAccession
233         * @return lookup hyperlink or null
234         */
235        public String makeLookupHyperlink(String termAccession);
236
237        /**
238         * Generate a hyperlink to drill down to ontology source.
239         *
240         * @param termAccession
241         * @return lookup hyperlink or null
242         */
243        public String makeLookupHyperlink(String ontologyAccession, String termAccession);
244
245        /**
246         * Return an ontology from the service.
247         *
248         * @param ontologyAccession
249         * @return Ontology or null if nothing was found
250         */
251        public Ontology getOntology(String ontologyAccession) throws OntologyServiceException;
252
253        /**
254         * Return term's synonyms.
255         *
256         * @param ontologyAccession
257         * @param termAccession
258         * @return List of synonyms or an empty list if nothing was found
259         * @throws OntologyServiceException
260         */
261        public List<String> getSynonyms(String ontologyAccession, String termAccession)
262        throws OntologyServiceException;
263
264        /**
265         * Return term's synonyms.
266         *
267         * @param term
268         * @return List of synonyms or an empty list if nothing was found
269         * @throws OntologyServiceException
270         */
271        public List<String> getSynonyms(OntologyTerm term) throws OntologyServiceException;
272
273        /**
274         * Return term's definitions.
275         *
276         * @param ontologyAccession
277         * @param termAccession
278         * @return List of definitions or an empty list if nothing was found
279         * @throws OntologyServiceException
280         */
281        public List<String> getDefinitions(String ontologyAccession, String termAccession)
282        throws OntologyServiceException;
283
284        /**
285         * Return term's definitions.
286         *
287         * @param term
288         * @return List of definitions or an empty list if nothing was found
289         * @throws OntologyServiceException
290         */
291        public List<String> getDefinitions(OntologyTerm term) throws OntologyServiceException;
292
293        /**
294         * Return all the terms in the ontology.
295         *
296         * @param ontologyAccession
297         *            the ontology accession identifying the ontology in the
298         *            service. Can be null if the underlying service is of
299         *            FileOntologyService type. You can however use the base uri for
300         *            an owl ontology, or http://www.geneontology.org/go# for OBO
301         *            ontologies if you wish. Things get easily complicated here,
302         *            that's why null is also an accepted value.
303         *
304         * @return A set as we want to collapse duplicate terms
305         *
306         * @throws OntologyServiceException
307         */
308        public Set<OntologyTerm> getAllTerms(String ontologyAccession) throws OntologyServiceException;
309
310        /**
311         * Get all the children terms of a given term.
312         *
313         * @param ontologyAccession
314         * @param termAccession
315         *
316         * @return all the child terms of the given term in is_a hierarchy or an
317         *         empty set if no parents were found
318         */
319        public Set<OntologyTerm> getAllChildren(String ontologyAccession, String termAccession)
320        throws OntologyServiceException;
321
322        /**
323         * Get all the parent terms of a given term.
324         *
325         * @param ontologyAccession
326         * @param termAccession
327         *
328         * @return all the parent terms of the given term in is_a hierarchy or an
329         *         empty set if no parents were found
330         */
331        public Set<OntologyTerm> getAllParents(String ontologyAccession, String termAccession)
332        throws OntologyServiceException;
333
334}
Note: See TracBrowser for help on using the repository browser.