src/jalview/ws/seqfetcher/DbSourceProxy.java

   1 /*
   2  * Jalview - A Sequence Alignment Editor and Viewer ($$Version-Rel$$)
   3  * Copyright (C) $$Year-Rel$$ The Jalview Authors
   4  *
   5  * This file is part of Jalview.
   6  *
   7  * Jalview is free software: you can redistribute it and/or
   8  * modify it under the terms of the GNU General Public License
   9  * as published by the Free Software Foundation, either version 3
  10  * of the License, or (at your option) any later version.
  11  *
  12  * Jalview is distributed in the hope that it will be useful, but
  13  * WITHOUT ANY WARRANTY; without even the implied warranty
  14  * of MERCHANTABILITY or FITNESS FOR A PARTICULAR
  15  * PURPOSE.  See the GNU General Public License for more details.
  16  *
  17  * You should have received a copy of the GNU General Public License
  18  * along with Jalview.  If not, see <http://www.gnu.org/licenses/>.
  19  * The Jalview Authors are detailed in the 'AUTHORS' file.
  20  */
  21 package jalview.ws.seqfetcher;
  22
  23 import jalview.datamodel.AlignmentI;
  24
  25 import com.stevesoft.pat.Regex;
  26
  27 /**
  28  * generic Reference Retrieval interface for a particular database
  29  * source/version as cited in DBRefEntry. TODO: add/define property to describe
  30  * max number of queries that this source can cope with at once. TODO:
  31  * add/define mechanism for retrieval of Trees and distance matrices from a
  32  * database (unify with io)
  33  *
  34  * @author JimP TODO: promote to API
  35  */
  36 public interface DbSourceProxy
  37 {
  38   /**
  39    *
  40    * @return source string constant used for this DB source
  41    */
  42   public String getDbSource();
  43
  44   /**
  45    * Short meaningful name for this data source for display in menus or
  46    * selection boxes.
  47    *
  48    * @return String
  49    */
  50   public String getDbName();
  51
  52   /**
  53    *
  54    * @return version string for this database.
  55    */
  56   public String getDbVersion();
  57
  58   /**
  59    * Separator between individual accession queries for a database that allows
  60    * multiple IDs to be fetched in a single query. Null implies that only a
  61    * single ID can be fetched at a time.
  62    *
  63    * @return string for separating concatenated queries (as individually
  64    *         validated by the accession validator)
  65    */
  66   public String getAccessionSeparator();
  67
  68   /**
  69    * Regular expression for checking form of query string understood by this
  70    * source. If the Regex includes parenthesis, then the first parenthesis
  71    * should yield the same accession string as the one used to annotate the
  72    * sequence. This is used to match query strings to returned sequences.
  73    *
  74    * @return null or a validation regex
  75    */
  76   public Regex getAccessionValidator();
  77
  78   /**
  79    *
  80    * @return a test/example query that can be used to validate retrieval and
  81    *         parsing mechanisms
  82    */
  83   public String getTestQuery();
  84
  85   /**
  86    * Required for sources supporting multiple query retrieval for use with the
  87    * DBRefFetcher, which attempts to limit its queries with putative accession
  88    * strings for a source to only those that are likely to be valid.
  89    *
  90    * @param accession
  91    * @return
  92    */
  93   public boolean isValidReference(String accession);
  94
  95   /**
  96    * make one or more queries to the database and attempt to parse the response
  97    * into an alignment
  98    *
  99    * @param queries
 100    *          - one or more queries for database in expected form
 101    * @return null if queries were successful but result was not parsable.
 102    *         Otherwise, an AlignmentI object containing properly annotated data
 103    *         (e.g. sequences with accessions for this datasource)
 104    * @throws Exception
 105    *           - propagated from underlying transport to database (note -
 106    *           exceptions are not raised if query not found in database)
 107    *
 108    */
 109   public AlignmentI getSequenceRecords(String queries) throws Exception;
 110
 111   /**
 112    *
 113    * @return true if a query is currently being made
 114    */
 115   public boolean queryInProgress();
 116
 117   /**
 118    * get the raw reponse from the last set of queries
 119    *
 120    * @return one or more string buffers for each individual query
 121    */
 122   public StringBuffer getRawRecords();
 123
 124   /**
 125    * Tier for this data source
 126    *
 127    * @return 0 - primary datasource, 1 - das primary source, 2 - secondary
 128    */
 129   public int getTier();
 130
 131   /**
 132    * Extracts valid accession strings from a query string. If there is an
 133    * accession id validator, returns the the matched region or the first
 134    * subgroup match from the matched region; else just returns the whole query.
 135    *
 136    * @param query
 137    * @return
 138    */
 139   String getAccessionIdFromQuery(String query);
 140
 141   /**
 142    * Returns the maximum number of accession ids that can be queried in one
 143    * request.
 144    *
 145    * @return
 146    */
 147   public int getMaximumQueryCount();
 148
 149   /**
 150    * Returns true if the source may provide coding DNA i.e. sequences with
 151    * implicit peptide products
 152    *
 153    * @return
 154    */
 155   public boolean isDnaCoding();
 156
 157   /**
 158    * Answers true if the database is a source of alignments (for example, domain
 159    * families)
 160    *
 161    * @return
 162    */
 163   public boolean isAlignmentSource();
 164
 165   /**
 166    * Returns an (optional) description of the source, suitable for display as a
 167    * tooltip, or null
 168    *
 169    * @return
 170    */
 171   public String getDescription();
 172 }