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(getUrl(identifier), ids, -1, MODE_ITERATOR, null);
 111       while (rvals.hasNext())
 112       {
 113         Map<String, Object> val = (Map<String, Object>) rvals.next();
 114         String db = val.get("dbname").toString();
 115         String id = val.get("primary_id").toString();
 116         if (db != null && id != null
 117                 && !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 we
 134 //   * don't parse "synonyms" as they appear to be either redirected or obsolete
 135 //   * in Uniprot.
 136 //   *
 137 //   * @param br
 138 //   * @return
 139 //   * @throws IOException
 140 //   */
 141 //  @SuppressWarnings("unchecked")
 142 //protected List<DBRefEntry> parseResponse(BufferedReader br)
 143 //          throws IOException
 144 //  {
 145 //    return result;
 146 //  }
 147 //
 148   private String xrefVersion = "ENSEMBL:0";
 149
 150   /**
 151    * version string for Xrefs - for 2.10, hardwired for ENSEMBL:0
 152    *
 153    * @return
 154    */
 155   public String getXRefVersion()
 156   {
 157     return xrefVersion;
 158   }
 159
 160   /**
 161    * Returns the URL for the REST endpoint to fetch all cross-references for an
 162    * identifier. Note this may return protein cross-references for nucleotide.
 163    * Filter the returned list as required.
 164    *
 165    * @param identifier
 166    * @return
 167    */
 168   protected URL getUrl(String identifier)
 169   {
 170     String url = getDomain() + "/xrefs/id/" + identifier
 171             + CONTENT_TYPE_JSON + "&all_levels=1";
 172     try
 173     {
 174       return new URL(url);
 175     } catch (MalformedURLException e)
 176     {
 177       return null;
 178     }
 179   }
 180
 181 }