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