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\r
  34  * TODO: promote to API\r
  35  */\r
  36 public interface DbSourceProxy\r
  37 {\r
  38   /**\r
  39    * \r
  40    * @return source string constant used for this DB source\r
  41    */\r
  42   public String getDbSource();\r
  43 \r
  44   /**\r
  45    * Short meaningful name for this data source for display in menus or\r
  46    * selection boxes.\r
  47    * \r
  48    * @return String\r
  49    */\r
  50   public String getDbName();\r
  51 \r
  52   /**\r
  53    * \r
  54    * @return version string for this database.\r
  55    */\r
  56   public String getDbVersion();\r
  57 \r
  58   /**\r
  59    * Separator between individual accession queries for a database that allows\r
  60    * multiple IDs to be fetched in a single query. Null implies that only a\r
  61    * single ID can be fetched at a time.\r
  62    * \r
  63    * @return string for separating concatenated queries (as individually\r
  64    *         validated by the accession validator)\r
  65    */\r
  66   public String getAccessionSeparator();\r
  67 \r
  68   /**\r
  69    * Regular expression for checking form of query string understood by this\r
  70    * source. If the Regex includes parenthesis, then the first parenthesis\r
  71    * should yield the same accession string as the one used to annotate the\r
  72    * sequence. This is used to match query strings to returned sequences.\r
  73    * \r
  74    * @return null or a validation regex\r
  75    */\r
  76   public Regex getAccessionValidator();\r
  77 \r
  78   /**\r
  79    * DbSource properties hash - define the capabilities of this source Property\r
  80    * hash methods defined in DbSourceProxyImpl. See constants in\r
  81    * jalview.datamodel.DBRefSource for definition of properties.\r
  82    * \r
  83    * @return\r
  84    */\r
  85   public Hashtable getDbSourceProperties();\r
  86 \r
  87   /**\r
  88    * \r
  89    * @return a test/example query that can be used to validate retrieval and\r
  90    *         parsing mechanisms\r
  91    */\r
  92   public String getTestQuery();\r
  93 \r
  94   /**\r
  95    * optionally implemented\r
  96    * \r
  97    * @param accession\r
  98    * @return\r
  99    */\r
 100   public boolean isValidReference(String accession);\r
 101 \r
 102   /**\r
 103    * make one or more queries to the database and attempt to parse the response\r
 104    * into an alignment\r
 105    * @param queries - one or more queries for database in expected form\r
 106    * @return null if queries were successful but result was not parsable\r
 107    * @throws Exception - propagated from underlying transport to database (note - exceptions are not raised if query not found in database)\r
 108    *           \r
 109    */\r
 110   public AlignmentI getSequenceRecords(String queries) throws Exception;\r
 111 \r
 112   /**\r
 113    * \r
 114    * @return true if a query is currently being made\r
 115    */\r
 116   public boolean queryInProgress();\r
 117 \r
 118   /**\r
 119    * get the raw reponse from the last set of queries\r
 120    * \r
 121    * @return one or more string buffers for each individual query\r
 122    */\r
 123   public StringBuffer getRawRecords();\r
 124 \r
 125   \r
 126   /**\r
 127    * Find out more info about the source.\r
 128    * @param dbsourceproperty - one of the database reference source properties in jalview.datamodel.DBRefSource\r
 129    * @return true if the source has this property\r
 130    */\r
 131   public boolean isA(Object dbsourceproperty);\r
 132 }\r