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