src/jalview/ext/ensembl/EnsemblXref.java

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