JAL-1705 code tidy/comment only
[jalview.git] / src / jalview / ext / ensembl / EnsemblFeatures.java
1 package jalview.ext.ensembl;
2
3 import jalview.datamodel.Alignment;
4 import jalview.datamodel.AlignmentI;
5 import jalview.io.FeaturesFile;
6 import jalview.io.FileParse;
7
8 import java.io.IOException;
9 import java.net.MalformedURLException;
10 import java.net.URL;
11 import java.util.ArrayList;
12 import java.util.List;
13
14 /**
15  * A client for fetching and processing Ensembl feature data in GFF format by
16  * calling the overlap REST service
17  * 
18  * @author gmcarstairs
19  * @see http://rest.ensembl.org/documentation/info/overlap_id
20  */
21 class EnsemblFeatures extends EnsemblRestClient
22 {
23   /*
24    * The default features to retrieve from Ensembl
25    * can override in getSequenceRecords parameter
26    */
27   private EnsemblFeatureType[] featuresWanted = { EnsemblFeatureType.cds,
28       EnsemblFeatureType.exon, EnsemblFeatureType.variation };
29
30   /**
31    * Default constructor (to use rest.ensembl.org)
32    */
33   public EnsemblFeatures()
34   {
35     super();
36   }
37
38   /**
39    * Constructor given the target domain to fetch data from
40    * 
41    * @param d
42    */
43   public EnsemblFeatures(String d)
44   {
45     super(d);
46   }
47
48   @Override
49   public String getDbName()
50   {
51     return "ENSEMBL (features)";
52   }
53
54   /**
55    * Makes a query to the REST overlap endpoint for the given sequence
56    * identifier. This returns an 'alignment' consisting of one 'dummy sequence'
57    * (the genomic sequence for which overlap features are returned by the
58    * service). This sequence will have on it sequence features which are the
59    * real information of interest, such as CDS regions or sequence variations.
60    */
61   @Override
62   public AlignmentI getSequenceRecords(String query) throws IOException
63   {
64     // TODO: use a vararg String... for getSequenceRecords instead?
65     List<String> queries = new ArrayList<String>();
66     queries.add(query);
67     FileParse fp = getSequenceReader(queries);
68     FeaturesFile fr = new FeaturesFile(fp);
69     return new Alignment(fr.getSeqsAsArray());
70   }
71
72   /**
73    * Returns a URL for the REST overlap endpoint
74    * 
75    * @param ids
76    * @return
77    */
78   @Override
79   protected URL getUrl(List<String> ids) throws MalformedURLException
80   {
81     StringBuffer urlstring = new StringBuffer(128);
82     urlstring.append(getDomain()).append("/overlap/id/")
83             .append(ids.get(0));
84
85     // @see https://github.com/Ensembl/ensembl-rest/wiki/Output-formats
86     urlstring.append("?content-type=text/x-gff3");
87
88     /*
89      * specify  features to retrieve
90      * @see http://rest.ensembl.org/documentation/info/overlap_id
91      * could make the list a configurable entry in jalview.properties
92      */
93     for (EnsemblFeatureType feature : featuresWanted)
94     {
95       urlstring.append("&feature=").append(feature.name());
96     }
97
98     return new URL(urlstring.toString());
99   }
100
101   @Override
102   protected boolean useGetRequest()
103   {
104     return true;
105   }
106
107   /**
108    * Returns the MIME type for GFF3. For GET requests the Content-type header
109    * describes the required encoding of the response.
110    */
111   @Override
112   protected String getRequestMimeType(boolean multipleIds)
113   {
114     return "text/x-gff3";
115   }
116
117   /**
118    * Returns the MIME type for GFF3.
119    */
120   @Override
121   protected String getResponseMimeType()
122   {
123     return "text/x-gff3";
124   }
125
126   /**
127    * Overloaded method that allows a list of features to retrieve to be
128    * specified
129    * 
130    * @param accId
131    * @param features
132    * @return
133    * @throws IOException
134    */
135   protected AlignmentI getSequenceRecords(String accId,
136           EnsemblFeatureType[] features) throws IOException
137   {
138     featuresWanted = features;
139     return getSequenceRecords(accId);
140   }
141 }