+/*\r
+ * Jalview - A Sequence Alignment Editor and Viewer (Version 2.7)\r
+ * Copyright (C) 2011 J Procter, AM Waterhouse, J Engelhardt, LM Lui, G Barton, M Clamp, S Searle\r
+ * \r
+ * This file is part of Jalview.\r
+ * \r
+ * Jalview is free software: you can redistribute it and/or\r
+ * modify it under the terms of the GNU General Public License \r
+ * as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.\r
+ * \r
+ * Jalview is distributed in the hope that it will be useful, but \r
+ * WITHOUT ANY WARRANTY; without even the implied warranty \r
+ * of MERCHANTABILITY or FITNESS FOR A PARTICULAR \r
+ * PURPOSE. See the GNU General Public License for more details.\r
+ * \r
+ * You should have received a copy of the GNU General Public License along with Jalview. If not, see <http://www.gnu.org/licenses/>.\r
+ */\r
package jalview.ws.seqfetcher;\r
\r
import jalview.datamodel.AlignmentI;\r
import java.util.Hashtable;\r
\r
import com.stevesoft.pat.Regex;\r
+\r
/**\r
- * generic Reference Retrieval interface for a particular database source/version as cited in DBRefEntry.\r
- * TODO: add/define property to describe max number of queries that this source can cope with at once.\r
- * TODO: add/define mechanism for retrieval of Trees and distance matrices from a database (unify with io)\r
+ * generic Reference Retrieval interface for a particular database\r
+ * source/version as cited in DBRefEntry. TODO: add/define property to describe\r
+ * max number of queries that this source can cope with at once. TODO:\r
+ * add/define mechanism for retrieval of Trees and distance matrices from a\r
+ * database (unify with io)\r
+ * \r
* @author JimP\r
- *\r
+ * TODO: promote to API\r
*/\r
public interface DbSourceProxy\r
{\r
* @return source string constant used for this DB source\r
*/\r
public String getDbSource();\r
+\r
+ /**\r
+ * Short meaningful name for this data source for display in menus or\r
+ * selection boxes.\r
+ * \r
+ * @return String\r
+ */\r
+ public String getDbName();\r
+\r
/**\r
* \r
* @return version string for this database.\r
*/\r
public String getDbVersion();\r
+\r
/**\r
- * Separator between individual accession queries for a database that allows multiple IDs\r
- * to be fetched in a single query. Null implies that only a single ID can be fetched at a time.\r
- * @return string for separating concatenated queries (as individually validated by the accession validator)\r
+ * Separator between individual accession queries for a database that allows\r
+ * multiple IDs to be fetched in a single query. Null implies that only a\r
+ * single ID can be fetched at a time.\r
+ * \r
+ * @return string for separating concatenated queries (as individually\r
+ * validated by the accession validator)\r
*/\r
public String getAccessionSeparator();\r
+\r
/**\r
- * Regular expression for checking form of query string understood by this source.\r
+ * Regular expression for checking form of query string understood by this\r
+ * source.\r
+ * \r
* @return null or a validation regex\r
*/\r
public Regex getAccessionValidator();\r
+\r
/**\r
- * DbSource properties hash - define the capabilities of this source\r
- * Property hash methods defined in DbSourceProxyImpl.\r
- * See constants in jalview.datamodel.DBRefSource for definition of properties.\r
- * @return \r
+ * DbSource properties hash - define the capabilities of this source Property\r
+ * hash methods defined in DbSourceProxyImpl. See constants in\r
+ * jalview.datamodel.DBRefSource for definition of properties.\r
+ * \r
+ * @return\r
*/\r
public Hashtable getDbSourceProperties();\r
+\r
/**\r
* \r
- * @return a test/example query that can be used to validate retrieval and parsing mechanisms\r
+ * @return a test/example query that can be used to validate retrieval and\r
+ * parsing mechanisms\r
*/\r
public String getTestQuery();\r
+\r
/**\r
* optionally implemented\r
+ * \r
* @param accession\r
* @return\r
*/\r
public boolean isValidReference(String accession);\r
+\r
/**\r
- * make one or more queries to the database\r
- * and attempt to parse the response into an alignment\r
- * @param queries\r
+ * make one or more queries to the database and attempt to parse the response\r
+ * into an alignment\r
+ * @param queries - one or more queries for database in expected form\r
* @return null if queries were successful but result was not parsable\r
- * @throws Exception TODO\r
+ * @throws Exception - propagated from underlying transport to database (note - exceptions are not raised if query not found in database)\r
+ * \r
*/\r
public AlignmentI getSequenceRecords(String queries) throws Exception;\r
+\r
/**\r
* \r
* @return true if a query is currently being made\r
*/\r
public boolean queryInProgress();\r
+\r
/**\r
* get the raw reponse from the last set of queries\r
+ * \r
* @return one or more string buffers for each individual query\r
*/\r
public StringBuffer getRawRecords();\r
+\r
+ \r
+ /**\r
+ * Find out more info about the source.\r
+ * @param dbsourceproperty - one of the database reference source properties in jalview.datamodel.DBRefSource\r
+ * @return true if the source has this property\r
+ */\r
+ public boolean isA(Object dbsourceproperty);\r
}\r