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