src/jalview/ws/seqfetcher/DbSourceProxy.java

   1 /*
   2  * Jalview - A Sequence Alignment Editor and Viewer (Version 2.8)
   3  * Copyright (C) 2012 J Procter, AM Waterhouse, LM Lui, J Engelhardt, G Barton, M Clamp, S Searle
   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 of the License, or (at your option) any later version.
  10  *
  11  * Jalview is distributed in the hope that it will be useful, but
  12  * WITHOUT ANY WARRANTY; without even the implied warranty
  13  * of MERCHANTABILITY or FITNESS FOR A PARTICULAR
  14  * PURPOSE.  See the GNU General Public License for more details.
  15  *
  16  * You should have received a copy of the GNU General Public License along with Jalview.  If not, see <http://www.gnu.org/licenses/>.
  17  */
  18 package jalview.ws.seqfetcher;
  19
  20 import jalview.datamodel.AlignmentI;
  21
  22 import java.util.Hashtable;
  23
  24 import com.stevesoft.pat.Regex;
  25
  26 /**
  27  * generic Reference Retrieval interface for a particular database
  28  * source/version as cited in DBRefEntry. TODO: add/define property to describe
  29  * max number of queries that this source can cope with at once. TODO:
  30  * add/define mechanism for retrieval of Trees and distance matrices from a
  31  * database (unify with io)
  32  *
  33  * @author JimP TODO: promote to API
  34  */
  35 public interface DbSourceProxy
  36 {
  37   /**
  38    *
  39    * @return source string constant used for this DB source
  40    */
  41   public String getDbSource();
  42
  43   /**
  44    * Short meaningful name for this data source for display in menus or
  45    * selection boxes.
  46    *
  47    * @return String
  48    */
  49   public String getDbName();
  50
  51   /**
  52    *
  53    * @return version string for this database.
  54    */
  55   public String getDbVersion();
  56
  57   /**
  58    * Separator between individual accession queries for a database that allows
  59    * multiple IDs to be fetched in a single query. Null implies that only a
  60    * single ID can be fetched at a time.
  61    *
  62    * @return string for separating concatenated queries (as individually
  63    *         validated by the accession validator)
  64    */
  65   public String getAccessionSeparator();
  66
  67   /**
  68    * Regular expression for checking form of query string understood by this
  69    * source. If the Regex includes parenthesis, then the first parenthesis
  70    * should yield the same accession string as the one used to annotate the
  71    * sequence. This is used to match query strings to returned sequences.
  72    *
  73    * @return null or a validation regex
  74    */
  75   public Regex getAccessionValidator();
  76
  77   /**
  78    * DbSource properties hash - define the capabilities of this source Property
  79    * hash methods defined in DbSourceProxyImpl. See constants in
  80    * jalview.datamodel.DBRefSource for definition of properties.
  81    *
  82    * @return
  83    */
  84   public Hashtable getDbSourceProperties();
  85
  86   /**
  87    *
  88    * @return a test/example query that can be used to validate retrieval and
  89    *         parsing mechanisms
  90    */
  91   public String getTestQuery();
  92
  93   /**
  94    * optionally implemented
  95    *
  96    * @param accession
  97    * @return
  98    */
  99   public boolean isValidReference(String accession);
 100
 101   /**
 102    * make one or more queries to the database and attempt to parse the response
 103    * into an alignment
 104    *
 105    * @param queries
 106    *          - one or more queries for database in expected form
 107    * @return null if queries were successful but result was not parsable
 108    * @throws Exception
 109    *           - propagated from underlying transport to database (note -
 110    *           exceptions are not raised if query not found in database)
 111    *
 112    */
 113   public AlignmentI getSequenceRecords(String queries) throws Exception;
 114
 115   /**
 116    *
 117    * @return true if a query is currently being made
 118    */
 119   public boolean queryInProgress();
 120
 121   /**
 122    * get the raw reponse from the last set of queries
 123    *
 124    * @return one or more string buffers for each individual query
 125    */
 126   public StringBuffer getRawRecords();
 127
 128   /**
 129    * Find out more info about the source.
 130    *
 131    * @param dbsourceproperty
 132    *          - one of the database reference source properties in
 133    *          jalview.datamodel.DBRefSource
 134    * @return true if the source has this property
 135    */
 136   public boolean isA(Object dbsourceproperty);
 137
 138   /**
 139    * Tier for this data source
 140    *
 141    * @return 0 - primary datasource, 1 - das primary source, 2 - secondary
 142    */
 143   public int getTier();
 144 }