src/jalview/ext/ensembl/EnsemblXref.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.ext.ensembl;
  22
  23 import jalview.datamodel.AlignmentI;
  24 import jalview.datamodel.DBRefEntry;
  25 import jalview.util.DBRefUtils;
  26 import jalview.util.JSONUtils;
  27
  28 import java.io.BufferedReader;
  29 import java.io.IOException;
  30 import java.net.MalformedURLException;
  31 import java.net.URL;
  32 import java.util.ArrayList;
  33 import java.util.Iterator;
  34 import java.util.List;
  35 import java.util.Map;
  36
  37 import org.json.simple.parser.ParseException;
  38
  39 /**
  40  * A class to fetch cross-references from Ensembl by calling the /xrefs REST
  41  * service
  42  *
  43  * @author gmcarstairs
  44  * @see http://rest.ensembl.org/documentation/info/xref_id
  45  */
  46 class EnsemblXref extends EnsemblRestClient
  47 {
  48
  49   private static final String GO_GENE_ONTOLOGY = "GO";
  50
  51   private String dbName = "ENSEMBL (xref)";
  52
  53   /**
  54    * Constructor given the target domain to fetch data from
  55    *
  56    * @param d
  57    */
  58   public EnsemblXref(String d, String dbSource, String version)
  59   {
  60     super(d);
  61     dbName = dbSource;
  62     xrefVersion = dbSource + ":" + version;
  63
  64   }
  65
  66   @Override
  67   public String getDbName()
  68   {
  69     return dbName;
  70   }
  71
  72   @Override
  73   public AlignmentI getSequenceRecords(String queries) throws Exception
  74   {
  75     return null;
  76   }
  77
  78   @Override
  79   protected URL getUrl(List<String> ids) throws MalformedURLException
  80   {
  81     return getUrl(ids.get(0));
  82   }
  83
  84   @Override
  85   protected boolean useGetRequest()
  86   {
  87     return true;
  88   }
  89
  90   /**
  91    * Calls the Ensembl xrefs REST endpoint and retrieves any cross-references
  92    * ("primary_id") for the given identifier (Ensembl accession id) and database
  93    * names. The "dbname" returned by Ensembl is canonicalised to Jalview's
  94    * standard version, and a DBRefEntry constructed. Currently takes all
  95    * identifiers apart from GO terms and synonyms.
  96    *
  97    * @param identifier
  98    *          an Ensembl stable identifier
  99    * @return
 100    */
 101   @SuppressWarnings("unchecked")
 102   public List<DBRefEntry> getCrossReferences(String identifier)
 103   {
 104     List<DBRefEntry> result = new ArrayList<>();
 105     List<String> ids = new ArrayList<>();
 106     ids.add(identifier);
 107
 108     try
 109     {
 110       Iterator<Object> rvals = (Iterator<Object>) getJSON(
 111               getUrl(identifier), ids, -1, MODE_ITERATOR, null);
 112       while (rvals.hasNext())
 113       {
 114         Map<String, Object> val = (Map<String, Object>) rvals.next();
 115         String db = val.get("dbname").toString();
 116         String id = val.get("primary_id").toString();
 117         if (db != null && id != null && !GO_GENE_ONTOLOGY.equals(db))
 118         {
 119           db = DBRefUtils.getCanonicalName(db);
 120           DBRefEntry dbref = new DBRefEntry(db, getXRefVersion(), id);
 121           result.add(dbref);
 122         }
 123       }
 124     } catch (ParseException | IOException e)
 125     {
 126       // ignore
 127     }
 128     return result;
 129   }
 130
 131   // /**
 132   // * Parses "primary_id" and "dbname" values from the JSON response and
 133   // * constructs a DBRefEntry. Returns a list of the DBRefEntry created. Note
 134   // we
 135   // * don't parse "synonyms" as they appear to be either redirected or obsolete
 136   // * in Uniprot.
 137   // *
 138   // * @param br
 139   // * @return
 140   // * @throws IOException
 141   // */
 142   // @SuppressWarnings("unchecked")
 143   // protected List<DBRefEntry> parseResponse(BufferedReader br)
 144   // throws IOException
 145   // {
 146   // return result;
 147   // }
 148   //
 149   private String xrefVersion = "ENSEMBL:0";
 150
 151   /**
 152    * version string for Xrefs - for 2.10, hardwired for ENSEMBL:0
 153    *
 154    * @return
 155    */
 156   public String getXRefVersion()
 157   {
 158     return xrefVersion;
 159   }
 160
 161   /**
 162    * Returns the URL for the REST endpoint to fetch all cross-references for an
 163    * identifier. Note this may return protein cross-references for nucleotide.
 164    * Filter the returned list as required.
 165    *
 166    * @param identifier
 167    * @return
 168    */
 169   protected URL getUrl(String identifier)
 170   {
 171     String url = getDomain() + "/xrefs/id/" + identifier + CONTENT_TYPE_JSON
 172             + "&all_levels=1";
 173     try
 174     {
 175       return new URL(url);
 176     } catch (MalformedURLException e)
 177     {
 178       return null;
 179     }
 180   }
 181
 182 }