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.api.FeatureSettingsModelI;
  24 import jalview.datamodel.AlignmentI;
  25
  26 import com.stevesoft.pat.Regex;
  27
  28 /**
  29  * generic Reference Retrieval interface for a particular database
  30  * source/version as cited in DBRefEntry.
  31  *
  32  * TODO: add/define mechanism for retrieval of Trees and distance matrices from
  33  * a database (unify with io)
  34  *
  35  * @author JimP
  36  */
  37 public interface DbSourceProxy
  38 {
  39   /**
  40    *
  41    * @return source string constant used for this DB source
  42    */
  43   String getDbSource();
  44
  45   /**
  46    * Short meaningful name for this data source for display in menus or
  47    * selection boxes.
  48    *
  49    * @return String
  50    */
  51   String getDbName();
  52
  53   /**
  54    *
  55    * @return version string for this database.
  56    */
  57   String getDbVersion();
  58
  59   /**
  60    * Separator between individual accession queries for a database that allows
  61    * multiple IDs to be fetched in a single query. Null implies that only a
  62    * single ID can be fetched at a time.
  63    *
  64    * @return string for separating concatenated queries (as individually
  65    *         validated by the accession validator)
  66    */
  67   String getAccessionSeparator();
  68
  69   /**
  70    * Regular expression for checking form of query string understood by this
  71    * source. If the Regex includes parenthesis, then the first parenthesis
  72    * should yield the same accession string as the one used to annotate the
  73    * sequence. This is used to match query strings to returned sequences.
  74    *
  75    * @return null or a validation regex
  76    */
  77   Regex getAccessionValidator();
  78
  79   /**
  80    *
  81    * @return a test/example query that can be used to validate retrieval and
  82    *         parsing mechanisms
  83    */
  84   String getTestQuery();
  85
  86   /**
  87    * Required for sources supporting multiple query retrieval for use with the
  88    * DBRefFetcher, which attempts to limit its queries with putative accession
  89    * strings for a source to only those that are likely to be valid.
  90    *
  91    * @param accession
  92    * @return
  93    */
  94   boolean isValidReference(String accession);
  95
  96   /**
  97    * make one or more queries to the database and attempt to parse the response
  98    * into an alignment
  99    *
 100    * @param queries
 101    *          - one or more queries for database in expected form
 102    * @return null if queries were successful but result was not parsable.
 103    *         Otherwise, an AlignmentI object containing properly annotated data
 104    *         (e.g. sequences with accessions for this datasource)
 105    * @throws Exception
 106    *           - propagated from underlying transport to database (note -
 107    *           exceptions are not raised if query not found in database)
 108    *
 109    */
 110   AlignmentI getSequenceRecords(String queries) throws Exception;
 111
 112   /**
 113    *
 114    * @return true if a query is currently being made
 115    */
 116   boolean queryInProgress();
 117
 118   /**
 119    * get the raw reponse from the last set of queries
 120    *
 121    * @return one or more string buffers for each individual query
 122    */
 123   StringBuffer getRawRecords();
 124
 125   /**
 126    * Tier for this data source
 127    *
 128    * @return 0 - primary datasource, 1 - das primary source, 2 - secondary
 129    */
 130   int getTier();
 131
 132   /**
 133    * Extracts valid accession strings from a query string. If there is an
 134    * accession id validator, returns the the matched region or the first
 135    * subgroup match from the matched region; else just returns the whole query.
 136    *
 137    * @param query
 138    * @return
 139    */
 140   String getAccessionIdFromQuery(String query);
 141
 142   /**
 143    * Returns the maximum number of accession ids that can be queried in one
 144    * request.
 145    *
 146    * @return
 147    */
 148   int getMaximumQueryCount();
 149
 150   /**
 151    * Returns true if the source may provide coding DNA i.e. sequences with
 152    * implicit peptide products
 153    *
 154    * @return
 155    */
 156   boolean isDnaCoding();
 157
 158   /**
 159    * Answers true if the database is a source of alignments (for example, domain
 160    * families)
 161    *
 162    * @return
 163    */
 164   boolean isAlignmentSource();
 165
 166   /**
 167    * Returns an (optional) description of the source, suitable for display as a
 168    * tooltip, or null
 169    *
 170    * @return
 171    */
 172   String getDescription();
 173
 174   /**
 175    * Returns the preferred feature colour configuration if there is one, else
 176    * null
 177    *
 178    * @return
 179    */
 180   FeatureSettingsModelI getFeatureColourScheme();
 181 }