9fa904a0b85e7284c2e00574b985a8df6da54cec
[jalview.git] / src / jalview / ws / seqfetcher / DbSourceProxy.java
1 /*\r
2  * Jalview - A Sequence Alignment Editor and Viewer (Version 2.7)\r
3  * Copyright (C) 2011 J Procter, AM Waterhouse, J Engelhardt, LM Lui, G Barton, M Clamp, S Searle\r
4  * \r
5  * This file is part of Jalview.\r
6  * \r
7  * Jalview is free software: you can redistribute it and/or\r
8  * modify it under the terms of the GNU General Public License \r
9  * as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.\r
10  * \r
11  * Jalview is distributed in the hope that it will be useful, but \r
12  * WITHOUT ANY WARRANTY; without even the implied warranty \r
13  * of MERCHANTABILITY or FITNESS FOR A PARTICULAR \r
14  * PURPOSE.  See the GNU General Public License for more details.\r
15  * \r
16  * You should have received a copy of the GNU General Public License along with Jalview.  If not, see <http://www.gnu.org/licenses/>.\r
17  */\r
18 package jalview.ws.seqfetcher;\r
19 \r
20 import jalview.datamodel.AlignmentI;\r
21 \r
22 import java.util.Hashtable;\r
23 \r
24 import com.stevesoft.pat.Regex;\r
25 \r
26 /**\r
27  * generic Reference Retrieval interface for a particular database\r
28  * source/version as cited in DBRefEntry. TODO: add/define property to describe\r
29  * max number of queries that this source can cope with at once. TODO:\r
30  * add/define mechanism for retrieval of Trees and distance matrices from a\r
31  * database (unify with io)\r
32  * \r
33  * @author JimP TODO: promote to API\r
34  */\r
35 public interface DbSourceProxy\r
36 {\r
37   /**\r
38    * \r
39    * @return source string constant used for this DB source\r
40    */\r
41   public String getDbSource();\r
42 \r
43   /**\r
44    * Short meaningful name for this data source for display in menus or\r
45    * selection boxes.\r
46    * \r
47    * @return String\r
48    */\r
49   public String getDbName();\r
50 \r
51   /**\r
52    * \r
53    * @return version string for this database.\r
54    */\r
55   public String getDbVersion();\r
56 \r
57   /**\r
58    * Separator between individual accession queries for a database that allows\r
59    * multiple IDs to be fetched in a single query. Null implies that only a\r
60    * single ID can be fetched at a time.\r
61    * \r
62    * @return string for separating concatenated queries (as individually\r
63    *         validated by the accession validator)\r
64    */\r
65   public String getAccessionSeparator();\r
66 \r
67   /**\r
68    * Regular expression for checking form of query string understood by this\r
69    * source. If the Regex includes parenthesis, then the first parenthesis\r
70    * should yield the same accession string as the one used to annotate the\r
71    * sequence. This is used to match query strings to returned sequences.\r
72    * \r
73    * @return null or a validation regex\r
74    */\r
75   public Regex getAccessionValidator();\r
76 \r
77   /**\r
78    * DbSource properties hash - define the capabilities of this source Property\r
79    * hash methods defined in DbSourceProxyImpl. See constants in\r
80    * jalview.datamodel.DBRefSource for definition of properties.\r
81    * \r
82    * @return\r
83    */\r
84   public Hashtable getDbSourceProperties();\r
85 \r
86   /**\r
87    * \r
88    * @return a test/example query that can be used to validate retrieval and\r
89    *         parsing mechanisms\r
90    */\r
91   public String getTestQuery();\r
92 \r
93   /**\r
94    * optionally implemented\r
95    * \r
96    * @param accession\r
97    * @return\r
98    */\r
99   public boolean isValidReference(String accession);\r
100 \r
101   /**\r
102    * make one or more queries to the database and attempt to parse the response\r
103    * into an alignment\r
104    * \r
105    * @param queries\r
106    *          - one or more queries for database in expected form\r
107    * @return null if queries were successful but result was not parsable\r
108    * @throws Exception\r
109    *           - propagated from underlying transport to database (note -\r
110    *           exceptions are not raised if query not found in database)\r
111    * \r
112    */\r
113   public AlignmentI getSequenceRecords(String queries) throws Exception;\r
114 \r
115   /**\r
116    * \r
117    * @return true if a query is currently being made\r
118    */\r
119   public boolean queryInProgress();\r
120 \r
121   /**\r
122    * get the raw reponse from the last set of queries\r
123    * \r
124    * @return one or more string buffers for each individual query\r
125    */\r
126   public StringBuffer getRawRecords();\r
127 \r
128   /**\r
129    * Find out more info about the source.\r
130    * \r
131    * @param dbsourceproperty\r
132    *          - one of the database reference source properties in\r
133    *          jalview.datamodel.DBRefSource\r
134    * @return true if the source has this property\r
135    */\r
136   public boolean isA(Object dbsourceproperty);\r
137 }\r