2 * Jalview - A Sequence Alignment Editor and Viewer (Version 2.8.0b1)
3 * Copyright (C) 2014 The Jalview Authors
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/>.
17 * The Jalview Authors are detailed in the 'AUTHORS' file.
19 package jalview.ws.seqfetcher;
21 import jalview.datamodel.AlignmentI;
23 import java.util.Hashtable;
25 import com.stevesoft.pat.Regex;
28 * generic Reference Retrieval interface for a particular database
29 * source/version as cited in DBRefEntry. TODO: add/define property to describe
30 * max number of queries that this source can cope with at once. TODO:
31 * add/define mechanism for retrieval of Trees and distance matrices from a
32 * database (unify with io)
34 * @author JimP TODO: promote to API
36 public interface DbSourceProxy
40 * @return source string constant used for this DB source
42 public String getDbSource();
45 * Short meaningful name for this data source for display in menus or
50 public String getDbName();
54 * @return version string for this database.
56 public String getDbVersion();
59 * Separator between individual accession queries for a database that allows
60 * multiple IDs to be fetched in a single query. Null implies that only a
61 * single ID can be fetched at a time.
63 * @return string for separating concatenated queries (as individually
64 * validated by the accession validator)
66 public String getAccessionSeparator();
69 * Regular expression for checking form of query string understood by this
70 * source. If the Regex includes parenthesis, then the first parenthesis
71 * should yield the same accession string as the one used to annotate the
72 * sequence. This is used to match query strings to returned sequences.
74 * @return null or a validation regex
76 public Regex getAccessionValidator();
79 * DbSource properties hash - define the capabilities of this source Property
80 * hash methods defined in DbSourceProxyImpl. See constants in
81 * jalview.datamodel.DBRefSource for definition of properties.
85 public Hashtable getDbSourceProperties();
89 * @return a test/example query that can be used to validate retrieval and
92 public String getTestQuery();
95 * optionally implemented
100 public boolean isValidReference(String accession);
103 * make one or more queries to the database and attempt to parse the response
107 * - one or more queries for database in expected form
108 * @return null if queries were successful but result was not parsable
110 * - propagated from underlying transport to database (note -
111 * exceptions are not raised if query not found in database)
114 public AlignmentI getSequenceRecords(String queries) throws Exception;
118 * @return true if a query is currently being made
120 public boolean queryInProgress();
123 * get the raw reponse from the last set of queries
125 * @return one or more string buffers for each individual query
127 public StringBuffer getRawRecords();
130 * Find out more info about the source.
132 * @param dbsourceproperty
133 * - one of the database reference source properties in
134 * jalview.datamodel.DBRefSource
135 * @return true if the source has this property
137 public boolean isA(Object dbsourceproperty);
140 * Tier for this data source
142 * @return 0 - primary datasource, 1 - das primary source, 2 - secondary
144 public int getTier();