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 /**\r
  28  * generic Reference Retrieval interface for a particular database\r
  29  * source/version as cited in DBRefEntry. TODO: add/define property to describe\r
  30  * max number of queries that this source can cope with at once. TODO:\r
  31  * add/define mechanism for retrieval of Trees and distance matrices from a\r
  32  * database (unify with io)\r
  33  * \r
  34  * @author JimP\r
  35  * \r
  36  */\r
  37 public interface DbSourceProxy\r
  38 {\r
  39   /**\r
  40    * \r
  41    * @return source string constant used for this DB source\r
  42    */\r
  43   public String getDbSource();\r
  44 \r
  45   /**\r
  46    * Short meaningful name for this data source for display in menus or\r
  47    * selection boxes.\r
  48    * \r
  49    * @return String\r
  50    */\r
  51   public String getDbName();\r
  52 \r
  53   /**\r
  54    * \r
  55    * @return version string for this database.\r
  56    */\r
  57   public String getDbVersion();\r
  58 \r
  59   /**\r
  60    * Separator between individual accession queries for a database that allows\r
  61    * multiple IDs to be fetched in a single query. Null implies that only a\r
  62    * single ID can be fetched at a time.\r
  63    * \r
  64    * @return string for separating concatenated queries (as individually\r
  65    *         validated by the accession validator)\r
  66    */\r
  67   public String getAccessionSeparator();\r
  68 \r
  69   /**\r
  70    * Regular expression for checking form of query string understood by this\r
  71    * source.\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    * @return null if queries were successful but result was not parsable\r
 107    * @throws Exception\r
 108    *                 TODO\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