src/jalview/ws/seqfetcher/DbSourceProxy.java

   1 /*\r
   2  * Jalview - A Sequence Alignment Editor and Viewer (Version 2.4)\r
   3  * Copyright (C) 2008 AM Waterhouse, J Procter, G Barton, M Clamp, S Searle\r
   4  * \r
   5  * This program is free software; you can redistribute it and/or\r
   6  * modify it under the terms of the GNU General Public License\r
   7  * as published by the Free Software Foundation; either version 2\r
   8  * of the License, or (at your option) any later version.\r
   9  * \r
  10  * This program is distributed in the hope that it will be useful,\r
  11  * but WITHOUT ANY WARRANTY; without even the implied warranty of\r
  12  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the\r
  13  * GNU General Public License for more details.\r
  14  * \r
  15  * You should have received a copy of the GNU General Public License\r
  16  * along with this program; if not, write to the Free Software\r
  17  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA\r
  18  */\r
  19 package jalview.ws.seqfetcher;\r
  20 \r
  21 import jalview.datamodel.AlignmentI;\r
  22 \r
  23 import java.util.Hashtable;\r
  24 \r
  25 import com.stevesoft.pat.Regex;\r
  26 /**\r
  27  * generic Reference Retrieval interface for a particular database source/version as cited in DBRefEntry.\r
  28  * TODO: add/define property to describe max number of queries that this source can cope with at once.\r
  29  * TODO: add/define mechanism for retrieval of Trees and distance matrices from a database (unify with io)\r
  30  * @author JimP\r
  31  *\r
  32  */\r
  33 public interface DbSourceProxy\r
  34 {\r
  35   /**\r
  36    * \r
  37    * @return source string constant used for this DB source\r
  38    */\r
  39   public String getDbSource();\r
  40   /**\r
  41    * Short meaningful name for this data source for\r
  42    * display in menus or selection boxes. \r
  43    * @return String\r
  44    */\r
  45   public String getDbName();\r
  46   /**\r
  47    * \r
  48    * @return version string for this database.\r
  49    */\r
  50   public String getDbVersion();\r
  51   /**\r
  52    * Separator between individual accession queries for a database that allows multiple IDs\r
  53    * to be fetched in a single query. Null implies that only a single ID can be fetched at a time.\r
  54    * @return string for separating concatenated queries (as individually validated by the accession validator)\r
  55    */\r
  56   public String getAccessionSeparator();\r
  57   /**\r
  58    * Regular expression for checking form of query string understood by this source.\r
  59    * @return null or a validation regex\r
  60    */\r
  61   public Regex getAccessionValidator();\r
  62   /**\r
  63    * DbSource properties hash - define the capabilities of this source\r
  64    * Property hash methods defined in DbSourceProxyImpl.\r
  65    * See constants in jalview.datamodel.DBRefSource for definition of properties.\r
  66    * @return \r
  67    */\r
  68   public Hashtable getDbSourceProperties();\r
  69   /**\r
  70    * \r
  71    * @return a test/example query that can be used to validate retrieval and parsing mechanisms\r
  72    */\r
  73   public String getTestQuery();\r
  74   /**\r
  75    * optionally implemented\r
  76    * @param accession\r
  77    * @return\r
  78    */\r
  79   public boolean isValidReference(String accession);\r
  80   /**\r
  81    * make one or more queries to the database\r
  82    * and attempt to parse the response into an alignment\r
  83    * @param queries\r
  84    * @return null if queries were successful but result was not parsable\r
  85    * @throws Exception TODO\r
  86    */\r
  87   public AlignmentI getSequenceRecords(String queries) throws Exception;\r
  88   /**\r
  89    * \r
  90    * @return true if a query is currently being made\r
  91    */\r
  92   public boolean queryInProgress();\r
  93   /**\r
  94    * get the raw reponse from the last set of queries\r
  95    * @return one or more string buffers for each individual query\r
  96    */\r
  97   public StringBuffer getRawRecords();\r
  98 }\r