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       }
 128       return (parseResponse(br));
 129     } catch (IOException e)
 130     {
 131       // ignore
 132     } finally
 133     {
 134       if (br != null)
 135       {
 136         try
 137         {
 138           br.close();
 139         } catch (IOException e)
 140         {
 141           // ignore
 142         }
 143       }
 144     }
 145
 146     return result;
 147   }
 148
 149   /**
 150    * Parses "primary_id" and "dbname" values from the JSON response and
 151    * constructs a DBRefEntry. Returns a list of the DBRefEntry created. Note we
 152    * don't parse "synonyms" as they appear to be either redirected or obsolete
 153    * in Uniprot.
 154    *
 155    * @param br
 156    * @return
 157    * @throws IOException
 158    */
 159   protected List<DBRefEntry> parseResponse(BufferedReader br)
 160           throws IOException
 161   {
 162     JSONParser jp = new JSONParser();
 163     List<DBRefEntry> result = new ArrayList<DBRefEntry>();
 164     try
 165     {
 166       JSONArray responses = (JSONArray) jp.parse(br);
 167       Iterator rvals = responses.iterator();
 168       while (rvals.hasNext())
 169       {
 170         JSONObject val = (JSONObject) rvals.next();
 171         String dbName = val.get("dbname").toString();
 172         if (dbName.equals(GO_GENE_ONTOLOGY))
 173         {
 174           continue;
 175         }
 176         String id = val.get("primary_id").toString();
 177         if (dbName != null && id != null)
 178         {
 179           dbName = DBRefUtils.getCanonicalName(dbName);
 180           DBRefEntry dbref = new DBRefEntry(dbName, 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=application/json&all_levels=1";
 215     try
 216     {
 217       return new URL(url);
 218     } catch (MalformedURLException e)
 219     {
 220       return null;
 221     }
 222   }
 223
 224 }