2 * Jalview - A Sequence Alignment Editor and Viewer (Version 2.8)
3 * Copyright (C) 2012 J Procter, AM Waterhouse, LM Lui, J Engelhardt, G Barton, M Clamp, S Searle
5 * This file is part of Jalview.
7 * Jalview is free software: you can redistribute it and/or
8 * modify it under the terms of the GNU General Public License
9 * as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
11 * Jalview is distributed in the hope that it will be useful, but
12 * WITHOUT ANY WARRANTY; without even the implied warranty
13 * of MERCHANTABILITY or FITNESS FOR A PARTICULAR
14 * PURPOSE. See the GNU General Public License for more details.
16 * You should have received a copy of the GNU General Public License along with Jalview. If not, see <http://www.gnu.org/licenses/>.
18 package jalview.ws.seqfetcher;
20 import jalview.datamodel.AlignmentI;
22 import java.util.Hashtable;
24 import com.stevesoft.pat.Regex;
27 * generic Reference Retrieval interface for a particular database
28 * source/version as cited in DBRefEntry. TODO: add/define property to describe
29 * max number of queries that this source can cope with at once. TODO:
30 * add/define mechanism for retrieval of Trees and distance matrices from a
31 * database (unify with io)
33 * @author JimP TODO: promote to API
35 public interface DbSourceProxy
39 * @return source string constant used for this DB source
41 public String getDbSource();
44 * Short meaningful name for this data source for display in menus or
49 public String getDbName();
53 * @return version string for this database.
55 public String getDbVersion();
58 * Separator between individual accession queries for a database that allows
59 * multiple IDs to be fetched in a single query. Null implies that only a
60 * single ID can be fetched at a time.
62 * @return string for separating concatenated queries (as individually
63 * validated by the accession validator)
65 public String getAccessionSeparator();
68 * Regular expression for checking form of query string understood by this
69 * source. If the Regex includes parenthesis, then the first parenthesis
70 * should yield the same accession string as the one used to annotate the
71 * sequence. This is used to match query strings to returned sequences.
73 * @return null or a validation regex
75 public Regex getAccessionValidator();
78 * DbSource properties hash - define the capabilities of this source Property
79 * hash methods defined in DbSourceProxyImpl. See constants in
80 * jalview.datamodel.DBRefSource for definition of properties.
84 public Hashtable getDbSourceProperties();
88 * @return a test/example query that can be used to validate retrieval and
91 public String getTestQuery();
94 * optionally implemented
99 public boolean isValidReference(String accession);
102 * make one or more queries to the database and attempt to parse the response
106 * - one or more queries for database in expected form
107 * @return null if queries were successful but result was not parsable
109 * - propagated from underlying transport to database (note -
110 * exceptions are not raised if query not found in database)
113 public AlignmentI getSequenceRecords(String queries) throws Exception;
117 * @return true if a query is currently being made
119 public boolean queryInProgress();
122 * get the raw reponse from the last set of queries
124 * @return one or more string buffers for each individual query
126 public StringBuffer getRawRecords();
129 * Find out more info about the source.
131 * @param dbsourceproperty
132 * - one of the database reference source properties in
133 * jalview.datamodel.DBRefSource
134 * @return true if the source has this property
136 public boolean isA(Object dbsourceproperty);
139 * Tier for this data source
141 * @return 0 - primary datasource, 1 - das primary source, 2 - secondary
143 public int getTier();