Merge branch 'features/mchmmer' into features/mchmmer_merge_JAL-1950
[jalview.git] / src / jalview / ext / ensembl / EnsemblSymbol.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 java.io.BufferedReader;
24 import java.io.IOException;
25 import java.net.MalformedURLException;
26 import java.net.URL;
27 import java.util.ArrayList;
28 import java.util.Iterator;
29 import java.util.List;
30
31 import org.json.simple.JSONArray;
32 import org.json.simple.JSONObject;
33 import org.json.simple.parser.JSONParser;
34 import org.json.simple.parser.ParseException;
35
36 /**
37  * A client for the Ensembl xrefs/symbol REST service;
38  * 
39  * @see http://rest.ensembl.org/documentation/info/xref_external
40  * @author gmcarstairs
41  *
42  */
43 public class EnsemblSymbol extends EnsemblXref
44 {
45   private static final String GENE = "gene";
46   private static final String TYPE = "type";
47   /**
48    * Constructor given the target domain to fetch data from
49    * 
50    * @param domain
51    * @param dbName
52    * @param dbVersion
53    */
54   public EnsemblSymbol(String domain, String dbName, String dbVersion)
55   {
56     super(domain, dbName, dbVersion);
57   }
58
59   /**
60    * Returns the first "id" value in gene identifier format from the JSON
61    * response, or null if none found
62    * 
63    * @param br
64    * @return
65    * @throws IOException
66    */
67   protected String parseSymbolResponse(BufferedReader br) throws IOException
68   {
69     JSONParser jp = new JSONParser();
70     String result = null;
71     try
72     {
73       JSONArray responses = (JSONArray) jp.parse(br);
74       Iterator rvals = responses.iterator();
75       while (rvals.hasNext())
76       {
77         JSONObject val = (JSONObject) rvals.next();
78         String id = val.get(JSON_ID).toString();
79         String type = val.get(TYPE).toString();
80         if (id != null && GENE.equals(type))
81         {
82           result = id;
83           break;
84         }
85       }
86     } catch (ParseException e)
87     {
88       // ignore
89     }
90     return result;
91   }
92
93   /**
94    * Constructs the URL for the REST symbol endpoint
95    * 
96    * @param id
97    *          the accession id (Ensembl or external)
98    * @param species
99    *          a species name recognisable by Ensembl
100    * @param type
101    *          an optional type to filter the response (gene, transcript,
102    *          translation)
103    * @return
104    */
105   protected URL getUrl(String id, Species species, String... type)
106   {
107     StringBuilder sb = new StringBuilder();
108     sb.append(getDomain()).append("/xrefs/symbol/")
109             .append(species.toString()).append("/").append(id)
110             .append(CONTENT_TYPE_JSON);
111     for (String t : type)
112     {
113       sb.append("&object_type=").append(t);
114     }
115     try
116     {
117       String url = sb.toString();
118       return new URL(url);
119     } catch (MalformedURLException e)
120     {
121       return null;
122     }
123   }
124
125   /**
126    * Calls the Ensembl xrefs REST 'symbol' endpoint and retrieves any gene ids
127    * for the given identifier, for any known model organisms
128    * 
129    * @param identifier
130    * @return
131    */
132   public List<String> getGeneIds(String identifier)
133   {
134     List<String> result = new ArrayList<String>();
135     List<String> ids = new ArrayList<String>();
136     ids.add(identifier);
137
138     String[] queries = identifier.split(getAccessionSeparator());
139     BufferedReader br = null;
140     try
141     {
142       for (String query : queries)
143       {
144         for (Species taxon : Species.getModelOrganisms())
145         {
146           URL url = getUrl(query, taxon, GENE);
147           if (url != null)
148           {
149             br = getHttpResponse(url, ids);
150             if (br != null)
151             {
152               String geneId = parseSymbolResponse(br);
153               if (geneId != null && !result.contains(geneId))
154               {
155                 result.add(geneId);
156               }
157             }
158           }
159         }
160       }
161     } catch (IOException e)
162     {
163       // ignore
164     } finally
165     {
166       if (br != null)
167       {
168         try
169         {
170           br.close();
171         } catch (IOException e)
172         {
173           // ignore
174         }
175       }
176     }
177     return result;
178   }
179
180 }