src/jalview/ws/seqfetcher/DbSourceProxy.java

   1 /*
   2  * Jalview - A Sequence Alignment Editor and Viewer (Version 2.8.0b1)
   3  * Copyright (C) 2014 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 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  * The Jalview Authors are detailed in the 'AUTHORS' file.
  18  */
  19 package jalview.ws.seqfetcher;
  20
  21 import jalview.datamodel.AlignmentI;
  22
  23 import java.util.Hashtable;
  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    * DbSource properties hash - define the capabilities of this source Property
  80    * hash methods defined in DbSourceProxyImpl. See constants in
  81    * jalview.datamodel.DBRefSource for definition of properties.
  82    *
  83    * @return
  84    */
  85   public Hashtable getDbSourceProperties();
  86
  87   /**
  88    *
  89    * @return a test/example query that can be used to validate retrieval and
  90    *         parsing mechanisms
  91    */
  92   public String getTestQuery();
  93
  94   /**
  95    * optionally implemented
  96    *
  97    * @param accession
  98    * @return
  99    */
 100   public boolean isValidReference(String accession);
 101
 102   /**
 103    * make one or more queries to the database and attempt to parse the response
 104    * into an alignment
 105    *
 106    * @param queries
 107    *          - one or more queries for database in expected form
 108    * @return null if queries were successful but result was not parsable
 109    * @throws Exception
 110    *           - propagated from underlying transport to database (note -
 111    *           exceptions are not raised if query not found in database)
 112    *
 113    */
 114   public AlignmentI getSequenceRecords(String queries) throws Exception;
 115
 116   /**
 117    *
 118    * @return true if a query is currently being made
 119    */
 120   public boolean queryInProgress();
 121
 122   /**
 123    * get the raw reponse from the last set of queries
 124    *
 125    * @return one or more string buffers for each individual query
 126    */
 127   public StringBuffer getRawRecords();
 128
 129   /**
 130    * Find out more info about the source.
 131    *
 132    * @param dbsourceproperty
 133    *          - one of the database reference source properties in
 134    *          jalview.datamodel.DBRefSource
 135    * @return true if the source has this property
 136    */
 137   public boolean isA(Object dbsourceproperty);
 138
 139   /**
 140    * Tier for this data source
 141    *
 142    * @return 0 - primary datasource, 1 - das primary source, 2 - secondary
 143    */
 144   public int getTier();
 145 }