JAL-2533 update javadoc
[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   /**
46    * Constructor given the target domain to fetch data from
47    * 
48    * @param domain
49    * @param dbName
50    * @param dbVersion
51    */
52   public EnsemblSymbol(String domain, String dbName, String dbVersion)
53   {
54     super(domain, dbName, dbVersion);
55   }
56
57   /**
58    * Returns the first "id" value in gene identifier format from the JSON
59    * response, or null if none found
60    * 
61    * @param br
62    * @return
63    * @throws IOException
64    */
65   protected String parseSymbolResponse(BufferedReader br)
66           throws IOException
67   {
68     JSONParser jp = new JSONParser();
69     String result = null;
70     try
71     {
72       JSONArray responses = (JSONArray) jp.parse(br);
73       Iterator rvals = responses.iterator();
74       while (rvals.hasNext())
75       {
76         JSONObject val = (JSONObject) rvals.next();
77         String id = val.get("id").toString();
78         if (id != null && isGeneIdentifier(id))
79         {
80           result = id;
81           break;
82         }
83       }
84     } catch (ParseException e)
85     {
86       // ignore
87     }
88     return result;
89   }
90
91   protected URL getUrl(String id, Species species)
92   {
93     String url = getDomain() + "/xrefs/symbol/" + species.toString() + "/"
94             + id + "?content-type=application/json";
95     try
96     {
97       return new URL(url);
98     } catch (MalformedURLException e)
99     {
100       return null;
101     }
102   }
103
104   /**
105    * Calls the Ensembl xrefs REST 'symbol' endpoint and retrieves any gene ids
106    * for the given identifier, for any known model organisms
107    * 
108    * @param identifier
109    * @return
110    */
111   public List<String> getIds(String identifier)
112   {
113     List<String> result = new ArrayList<String>();
114     List<String> ids = new ArrayList<String>();
115     ids.add(identifier);
116
117     String[] queries = identifier.split(getAccessionSeparator());
118     BufferedReader br = null;
119     try
120     {
121       for (String query : queries)
122       {
123         for (Species taxon : Species.values())
124         {
125           if (taxon.isModelOrganism())
126           {
127             URL url = getUrl(query, taxon);
128             if (url != null)
129             {
130               br = getHttpResponse(url, ids);
131             }
132             String geneId = parseSymbolResponse(br);
133             if (geneId != null)
134             {
135               result.add(geneId);
136             }
137           }
138         }
139       }
140     } catch (IOException e)
141     {
142       // ignore
143     } finally
144     {
145       if (br != null)
146       {
147         try
148         {
149           br.close();
150         } catch (IOException e)
151         {
152           // ignore
153         }
154       }
155     }
156     return result;
157   }
158
159 }