JAL-2533 update javadoc
[jalview.git] / 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 }