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