Context Navigation

source: trunk/grails-app/controllers/nl/tno/metagenomics/integration/RestController.groovy @ 14

Last change on this file since 14 was 14, checked in by robert@…, 11 years ago
Implemented improved authorization (#16) Built in select all checkboxes (#25)
File size: 21.1 KB

Line
1	package nl.tno.metagenomics.integration
2
3	import grails.converters.*
4	import nl.tno.metagenomics.Study
5	import nl.tno.metagenomics.Sample
6	import nl.tno.metagenomics.Assay
7
8	import org.apache.catalina.connector.Response;
9	import org.codehaus.groovy.grails.commons.ConfigurationHolder
10
11	/** Expose the list of features within a certain assay
12	*
13	* @author Robert Horlings (robert@isdat.nl)
14	* @since 20101229
15	* @see SAM.RestController
16	*
17	* $Rev$
18	*
19	* This class provides a REST-full service for getting and setting the data
20	* in the Metagenomics Module. The service consists of several
21	* resources listed below. So far, all resources are GET resoruces, i.e. we
22	* do not use PUT, POST or DELETE. Because we are using Grails' web libaries,
23	* each resource corresponds to exactly one action of this controller.
24	*
25	*
26	* The REST resources implemented in this controller are:
27	*
28	* metagenomics-host:port/metagenomics/rest/getMeasurements(assayToken)
29	* metagenomics-host:port/metagenomics/rest/getMeasurementMetadata(assayToken, measurementTokens)
30	* metagenomics-host:port/metagenomics/rest/getMeasurementData(assayToken, measurementTokens, sampleTokens)
31	* metagenomics-host:port/metagenomics/rest/getAssayURL(assayToken)
32	*
33	* Where 'metagenomics-host' is the url of the metagenomics server's host with port number 'port'.
34	*
35	*/
36	class RestController {
37	def synchronizationService
38
39	/****************************************************************/
40	/* REST resource for handling study change in GSCF */
41	/****************************************************************/
42
43	/**
44	* Is called by GSCF when a study is added, changed or deleted.
45	* Sets the 'dirty' flag of a study to true, so that it will be updated
46	* next time the study is asked for.
47	*
48	* @param studyToken
49	*/
50	def notifyStudyChange = {
51	def studyToken = params.studyToken
52
53	if( !studyToken ) {
54	response.sendError(400, "No studyToken given" )
55	return
56	}
57
58	// Search for the changed study
59	def study = Study.findByStudyToken( studyToken );
60
61	// If the study is not found, it is added in GSCF. Add a dummy (dirty) study, in order to
62	// update it immediately when asked for
63	if( !study ) {
64	log.info( "METAGENOMICS: GSCF notification for new study " + studyToken );
65	study = new Study(
66	name: "",
67	studyToken: studyToken,
68	isDirty: true
69	)
70	} else {
71	log.info( "METAGENOMICS: GSCF notification for existing study " + studyToken );
72	study.isDirty = true;
73	}
74	study.save(flush:true);
75
76	def jsonData = [ 'studyToken': studyToken, message: "Notify succesful" ];
77
78	render jsonData as JSON
79	}
80
81	/**
82	* Return URL to view an assay.
83	*
84	* @param assayToken
85	* @return URL to view an assay as single hash entry with key 'url'.
86	*
87	*/
88	def getAssayURL = {
89	def assayToken = params.assayToken
90
91	if( !assayToken ) {
92	render [] as JSON
93	return
94	}
95
96	def assay = Assay.findByAssayToken( assayToken )
97
98	// If the assay is not found, try synchronizing
99	synchronizationService.sessionToken = session.sessionToken
100
101	if( !assay ) {
102	synchronizationService.synchronizeStudies()
103	assay = Assay.findByAssayToken( assayToken );
104
105	if( !assay ) {
106	response.sendError(404, "Not Found" )
107	return;
108	}
109	} else {
110	try {
111	synchronizationService.synchronizeAssay(assay);
112	} catch( Exception e ) {
113	response.sendError( 500, e.getMessage())
114	return
115	}
116
117	def url = [ 'url' : ConfigurationHolder.config.grails.serverURL + '/assay/show/' + assay.id.toString() ]
118
119	render url as JSON
120	}
121	}
122
123	/***************************************************/
124	/* REST resources related to the querying in GSCF */
125	/***************************************************/
126
127	/**
128	* Retrieves a list of fields that could be queried when searching for a specific entity.
129	*
130	* The module is allowed to return different fields when the user searches for different entities
131	*
132	* Example call: [moduleurl]/rest/getQueryableFields?entity=Study&entity=Sample
133	* Example response: { "Study": [ "# sequences" ], "Sample": [ "# sequences", "# bacteria" ] }
134	*
135	* @param params.entity Entity that is searched for. Might be more than one. If no entity is given,
136	* a list of searchable fields for all entities is given
137	* @return JSON List with the names of the fields
138	*/
139	def getQueryableFields = {
140	// We don't really care about the entity. The only thing is that this module
141	// is only aware of studies, assays and samples, but doesn't know anything about
142	// subjects or events. If the user searches for those entities (maybe in the future)
143	// this module doesn't have anything to search for.
144
145	def entities = params.entity ?: []
146
147	if( entities instanceof String )
148	entities = [entities]
149	else
150	entities = entities.toList()
151
152	if( !entities )
153	entities = [ "Study", "Assay", "Sample" ]
154
155
156	def fields = [:];
157	entities.unique().each { entity ->
158	switch( entity ) {
159	case "Study":
160	case "Assay":
161	case "Sample":
162	fields[ entity ] = [ "# sequences", "Tag name", "Run name" ]
163	break;
164	default:
165	// Do nothing
166	break;
167	}
168	}
169
170	render fields as JSON
171	}
172
173	/**
174	* Returns data for the given field and entities.
175	*
176	* Example call: [moduleurl]/rest/getQueryableFieldData?entity=Study&tokens=abc1&tokens=abc2&fields=# sequences&fields=# bacteria
177	* Example response: { "abc1": { "# sequences": 141, "# bacteria": 0 }, "abc2": { "#sequences": 412 } }
178	*
179	* @param params.entity Entity that is searched for
180	* @param params.tokens One or more tokens of the entities that the data should be returned for
181	* @param params.fields One or more field names of the data to be returned.
182	* @return JSON Map with keys being the entity tokens and the values being maps with entries [field] = [value]. Not all
183	* fields and tokens that are asked for have to be returned by the module (e.g. when a specific entity can
184	* not be found, or a value is not present for an entity)
185	*/
186	def getQueryableFieldData = {
187	def entity = params.entity;
188	def tokens = params.tokens ?: []
189	def fields = params.fields ?: []
190
191	if( tokens instanceof String )
192	tokens = [tokens]
193	else
194	tokens = tokens.toList();
195
196	if( fields instanceof String )
197	fields = [fields]
198	else
199	fields = fields.toList();
200
201	// Only search for unique tokens and fields
202	tokens = tokens.unique()
203	fields = fields.unique()
204
205	// Without tokens or fields we can only return an empty list
206	def map = [:]
207	if( tokens.size() == 0 \|\| fields.size() == 0 ) {
208	log.trace "Return empty string for getQueryableFieldData: #tokens: " + tokens.size() + " #fields: " + fields.size()
209	render map as JSON
210	return;
211	}
212
213	for( token in tokens ) {
214	def object = getQueryableObject( entity, token );
215
216	if( object ) {
217	// Check whether the user has sufficient privileges:
218	def study;
219	switch( entity ) {
220	case "Study":
221	study = object;
222	break;
223	case "Assay":
224	case "Sample":
225	study = object.study
226	break;
227	default:
228	log.error "Incorrect entity used: " + entity;
229	continue;
230	}
231
232	if( !study.canRead( session.user ) ) {
233	log.error "Data was requested for " + entity.toLowerCase() + " " + object.name + " but the user " + session.user.username + " doesn't have the right privileges."
234	continue;
235	}
236
237	map[ token ] = [:]
238	fields.each { field ->
239	def v = getQueryableFieldValue( entity, object, field );
240	if( v != null )
241	map[ token ][ field ] = v
242	}
243	} else {
244	log.trace "No " + entity + " with token " + token + " found."
245	}
246	}
247
248	render map as JSON
249	}
250
251	/**
252	* Searches for a specific entity
253	*
254	* @param entity Entity to search in
255	* @param token Token of the entity to search in
256	* @return
257	*/
258	protected def getQueryableObject( def entity, def token ) {
259	switch( entity ) {
260	case "Study":
261	return Study.findByStudyToken( token );
262	case "Assay":
263	return Assay.findByAssayToken( token );
264	case "Sample":
265	return Sample.findBySampleToken( token );
266	default:
267	// Other entities can't be handled
268	return null;
269	}
270	}
271
272	/**
273	* Searches for the value of a specific field in a specific entity
274	*
275	* @param entity Entity of the given object
276	* @param object Object to search in
277	* @param field Field value to retrieve
278	* @return
279	*/
280	protected def getQueryableFieldValue( def entity, def object, def field ) {
281	if( !entity \|\| !object \|\| !field )
282	return null;
283
284	// First determine all assaysamples involved, in order to return data later.
285	// All data that has to be returned is found in assaysamples
286	def assaySamples
287
288	switch( entity ) {
289	case "Study":
290	assaySamples = object.assays*.assaySamples;
291	if( assaySamples ) {
292	assaySamples = assaySamples.flatten()
293	}
294	break;
295	case "Assay":
296	case "Sample":
297	assaySamples = object.assaySamples;
298	break;
299	default:
300	// Other entities can't be handled
301	return null;
302	}
303
304	// If no assaySamples are involved, return null as empty value
305	if( !assaySamples ) {
306	return null;
307	}
308
309	// Now determine the exact field to return
310	switch( field ) {
311	// Returns the total number of sequences in this sample
312	case "# sequences":
313	return assaySamples.collect { it.numSequences() }.sum();
314	// Returns the unique tag names
315	case "Tag name":
316	return assaySamples.collect { it.tagName }.findAll { it != null }.unique();
317	case "Run name":
318	return assaySamples.collect { it.run?.name }.findAll { it != null }.unique();
319	// Other fields are not handled
320	default:
321	return null;
322	}
323
324	}
325
326	private def checkAssayToken( def assayToken ) {
327	if( !assayToken \|\| assayToken == null ) {
328	return false
329	}
330	def list = []
331	def assay = Assay.findByAssayToken( assayToken )
332
333	if( !assay \|\| assay == null ) {
334	return false;
335	}
336
337	return assay;
338	}
339
340	/****************************************************************/
341	/* REST resources for exporting data from GSCF */
342	/****************************************************************/
343
344	/**
345	* Retrieves a list of actions that can be performed on data with a specific entity.
346	*
347	* The module is allowed to return different fields when the user searches for different entities
348	*
349	* Example call: [moduleurl]/rest/getPossibleActions?entity=Assay&entity=Sample
350	* Example response: { "Assay": [ { name: "excel", description: "Export as excel" } ],
351	* "Sample": [ { name: "excel", description: "Export as excel" }, { name: "fasta", description: : "Export as fasta" } ] }
352	*
353	* @param params.entity Entity that is searched for. Might be more than one. If no entity is given,
354	* a list of searchable fields for all entities is given
355	* @return JSON Hashmap with keys being the entities and the values are lists with the action this module can
356	* perform on this entity. The actions as hashmaps themselves, with keys 'name' and 'description'
357	*/
358	def getPossibleActions = {
359	def entities = params.entity ?: []
360
361	if( entities instanceof String )
362	entities = [entities]
363	else
364	entities = entities.toList()
365
366	if( !entities )
367	entities = [ "Study", "Assay", "Sample" ]
368
369	def actions = [:];
370	entities.unique().each { entity ->
371	switch( entity ) {
372	case "Study":
373	actions[ entity ] = [
374	[ name: "excel", description: "Export metadata", url: createLink( controller: "study", action: "exportMetaData", absolute: true ) ],
375	[ name: "fasta", description: "Export as fasta", url: createLink( controller: "study", action: "exportAsFasta", absolute: true ) ]
376	]
377	break;
378	case "Assay":
379	actions[ entity ] = [
380	[ name: "fasta", description: "Export as fasta", url: createLink( controller: "assay", action: "exportAsFasta", absolute: true ) ],
381	[ name: "excel", description: "Export metadata", url: createLink( controller: "assay", action: "exportMetaData", absolute: true ) ]
382	]
383	break;
384	case "Sample":
385	actions[ entity ] = [
386	[ name: "fasta", description: "Export as fasta", url: createLink( controller: "sample", action: "exportAsFasta", absolute: true ) ],
387	[ name: "excel", description: "Export metadata", url: createLink( controller: "sample", action: "exportMetaData", absolute: true ) ]
388	]
389	break;
390	default:
391	// Do nothing
392	break;
393	}
394	}
395
396	render actions as JSON
397	}
398
399	/****************************************************************/
400	/* REST resources for providing basic data to the GSCF */
401	/****************************************************************/
402	private getMeasurementTypes() {
403	return [ "# sequences" ]
404	}
405
406	/**
407	* Return a list of simple assay measurements matching the querying text.
408	*
409	* @param assayToken
410	* @return list of measurements for token. Each member of the list is a hash.
411	* the hash contains the three keys values pairs: value, sampleToken, and
412	* measurementMetadata.
413	*
414	* Example REST call:
415	* http://localhost:8184/metagenomics/rest/getMeasurements/query?assayToken=16S-5162
416	*
417	* Resulting JSON object:
418	*
419	* [ "# sequences", "average quality" ]
420	*
421	*/
422	def getMeasurements = {
423	def assayToken = params.assayToken;
424
425	if( !checkAssayToken( assayToken ) ) {
426	response.sendError(404)
427	return false
428	}
429
430	render getMeasurementTypes() as JSON
431	}
432
433	/**
434	* Return measurement metadata for measurement
435	*
436	* @param assayToken
437	* @param measurementTokens. List of measurements for which the metadata is returned.
438	* If this is not given, then return metadata for all
439	* measurements belonging to the specified assay.
440	* @return list of measurements
441	*
442	* Example REST call:
443	* http://localhost:8184/metagenomics/rest/getMeasurementMetadata/query?assayToken=16S-5162
444	* &measurementToken=# sequences
445	* &measurementToken=average quality
446	*
447	* Example resulting JSON object:
448	*
449	* [ {"name":"# sequences","type":"raw"},
450	* {"name":"average quality", "unit":"Phred"} ]
451	*/
452	def getMeasurementMetadata = {
453	def assayToken = params.assayToken
454	def measurementTokens = params.measurementToken
455
456	if( !checkAssayToken( assayToken ) ) {
457	response.sendError(404)
458	return false
459	}
460
461	// For now, we don't have any metadata about the measurements
462	def measurements = getMeasurementTypes();
463	def measurementMetadata = []
464
465	measurementTokens.each { token ->
466	if( measurements.contains( token ) )
467	measurementMetadata << [ "name" : token ];
468	}
469
470	render measurementMetadata as JSON
471	}
472
473	/**
474	* Return list of measurement data.
475	*
476	* @param assayTokes
477	* @param measurementToken. Restrict the returned data to the measurementTokens specified here.
478	* If this argument is not given, all samples for the measurementTokens are returned.
479	* Multiple occurences of this argument are possible.
480	* @param sampleToken. Restrict the returned data to the samples specified here.
481	* If this argument is not given, all samples for the measurementTokens are returned.
482	* Multiple occurences of this argument are possible.
483	* @param boolean verbose. If this argument is not present or it's value is true, then return
484	* the date in a redundant format that is easier to process.
485	* By default, return a more compact JSON object as follows.
486	*
487	* The list contains three elements:
488	*
489	* (1) a list of sampleTokens,
490	* (2) a list of measurementTokens,
491	* (3) a list of values.
492	*
493	* The list of values is a matrix represented as a list. Each row of the matrix
494	* contains the values of a measurementToken (in the order given in the measurement
495	* token list, (2)). Each column of the matrix contains the values for the sampleTokens
496	* (in the order given in the list of sampleTokens, (1)).
497	* (cf. example below.)
498	*
499	*
500	* @return table (as hash) with values for given samples and measurements
501	*
502	*
503	* List of examples.
504	*
505	*
506	* Example REST call:
507	* http://localhost:8184/metagenomics/rest/getMeasurementData/doit?assayToken=PPSH-Glu-A
508	* &measurementToken=total carbon dioxide (tCO)
509	* &sampleToken=5_A
510	* &sampleToken=1_A
511	* &verbose=true
512	*
513	* Resulting JSON object:
514	* [ {"sampleToken":"1_A","measurementToken":"total carbon dioxide (tCO)","value":28},
515	* {"sampleToken":"5_A","measurementToken":"total carbon dioxide (tCO)","value":29} ]
516	*
517	*
518	*
519	* Example REST call without sampleToken, without measurementToken,
520	* and with verbose representation:
521	* http://localhost:8184/metagenomics/rest/getMeasurementData/dossit?assayToken=PPSH-Glu-A
522	* &verbose=true
523	*
524	* Resulting JSON object:
525	* [ {"sampleToken":"1_A","measurementToken":"sodium (Na+)","value":139},
526	* {"sampleToken":"1_A","measurementToken":"potassium (K+)","value":4.5},
527	* {"sampleToken":"1_A","measurementToken":"total carbon dioxide (tCO)","value":26},
528	* {"sampleToken":"2_A","measurementToken":"sodium (Na+)","value":136},
529	* {"sampleToken":"2_A","measurementToken":"potassium (K+)","value":4.3},
530	* {"sampleToken":"2_A","measurementToken":"total carbon dioxide (tCO)","value":28},
531	* {"sampleToken":"3_A","measurementToken":"sodium (Na+)","value":139},
532	* {"sampleToken":"3_A","measurementToken":"potassium (K+)","value":4.6},
533	* {"sampleToken":"3_A","measurementToken":"total carbon dioxide (tCO)","value":27},
534	* {"sampleToken":"4_A","measurementToken":"sodium (Na+)","value":137},
535	* {"sampleToken":"4_A","measurementToken":"potassium (K+)","value":4.6},
536	* {"sampleToken":"4_A","measurementToken":"total carbon dioxide (tCO)","value":26},
537	* {"sampleToken":"5_A","measurementToken":"sodium (Na+)","value":133},
538	* {"sampleToken":"5_A","measurementToken":"potassium (K+)","value":4.5},
539	* {"sampleToken":"5_A","measurementToken":"total carbon dioxide (tCO)","value":29} ]
540	*
541	*
542	*
543	* Example REST call with default (non-verbose) view and without sampleToken:
544	*
545	* Resulting JSON object:
546	* http://localhost:8184/metagenomics/rest/getMeasurementData/query?
547	* assayToken=PPSH-Glu-A&
548	* measurementToken=total carbon dioxide (tCO)
549	*
550	* Resulting JSON object:
551	* [ ["1_A","2_A","3_A","4_A","5_A"],
552	* ["sodium (Na+)","potassium (K+)","total carbon dioxide (tCO)"],
553	* [139,136,139,137,133,4.5,4.3,4.6,4.6,4.5,26,28,27,26,29] ]
554	*
555	* Explanation:
556	* The JSON object returned by default (i.e., unless verbose is set) is an array of three arrays.
557	* The first nested array gives the sampleTokens for which data was retrieved.
558	* The second nested array gives the measurementToken for which data was retrieved.
559	* The thrid nested array gives the data for sampleTokens and measurementTokens.
560	*
561	*
562	* In the example, the matrix represents the values of the above Example and
563	* looks like this:
564	*
565	* 1_A 2_A 3_A 4_A 5_A
566	*
567	* Na+ 139 136 139 137 133
568	*
569	* K+ 4.5 4.3 4.6 4.6 4.5
570	*
571	* tCO 26 28 27 26 29
572	*
573	*/
574	def getMeasurementData = {
575	def assayToken = params.assayToken
576	def measurementTokens = params.measurementToken
577	def sampleTokens = params.sampleToken
578	def verbose = false
579
580	if(params.verbose && (params.verbose=='true'\|\|params.verbose==true) ) {
581	verbose=true
582	}
583
584	def assay = checkAssayToken( assayToken );
585	if( !assay ) {
586	response.sendError(404)
587	return false
588	}
589
590	if( !measurementTokens ) {
591	measurementTokens = []
592	}
593	else if( measurementTokens.class == java.lang.String ) {
594	measurementTokens = [ measurementTokens ]
595	}
596
597	if( !sampleTokens ) {
598	sampleTokens = []
599	}
600	else if( sampleTokens.class == java.lang.String ) {
601	sampleTokens = [ sampleTokens ]
602	}
603
604	def data = SampleAssay.findAllByAssay( assay );
605	def measurements = getMeasurementTypes()
606
607	def results = []
608	data.each { sampleAssay ->
609	measurements.each { type ->
610	def sample = sampleAssay.sample.sampleToken
611	def isMatch = false
612
613	// Check if this measurement should be returned
614	if( ( measurementTokens.isEmpty() \|\| measurementTokens.contains( type ) ) &&
615	( sampleTokens.isEmpty() \|\| sampleTokens.contains( sample ) ) ) {
616	results.push( [ 'sampleToken': sample, 'measurementToken': type, 'value': sampleAssay[ type ] ] )
617	}
618	}
619	}
620
621	if(!verbose) {
622	results = compactTable( results )
623	}
624
625	render results as JSON
626	}
627
628
629	/* helper function for getSamples
630	*
631	* Return compact JSON object for data. The format of the returned array is as follows.
632	*
633	* The list contains three elements:
634	*
635	* (1) a list of sampleTokens,
636	* (2) a list of measurementTokens,
637	* (3) a list of values.
638	*
639	* The list of values is a matrix represented as a list. Each row of the matrix
640	* contains the values of a measurementToken (in the order given in the measurement
641	* token list, (2)). Each column of the matrix contains the values for the sampleTokens
642	* (in the order given in the list of sampleTokens, (1)).
643	*/
644	def compactTable( results ) {
645	def i = 0
646	def sampleTokenIndex = [:]
647	def sampleTokens = results.collect( { it['sampleToken'] } ).unique()
648	sampleTokens.each{ sampleTokenIndex[it] = i++ }
649
650	i = 0
651	def measurementTokenIndex= [:]
652	def measurementTokens = results.collect( { it['measurementToken'] } ).unique()
653	measurementTokens.each{ measurementTokenIndex[it] = i++ }
654
655	def data = []
656	measurementTokens.each{ m ->
657	sampleTokens.each{ s ->
658	def item = results.find{ it['sampleToken']==s && it['measurementToken']==m }
659	data.push item ? item['value'] : null
660	}
661	}
662
663	return [ sampleTokens, measurementTokens, data ]
664	}
665
666	}

Note: See TracBrowser for help on using the repository browser.

Download in other formats: