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