Context Navigation

source: trunk/grails-app/controllers/RestController.groovy @ 1348

Last change on this file since 1348 was 1328, checked in by robert@…, 12 years ago
Added metagenomics module and improved rest controller to give 404 and 401 errors when appropriate
Property svn:keywords set to `Author Date Rev`
File size: 18.1 KB

Line
1	/**
2	* RestController
3	*
4	* This controler provides a REST service.
5	* The names of the RESET resources are the same as the names of this
6	* controller's actions. E.g., the resources called getStudies simply
7	* corresponds to the action getStudies. Some of the resources are parameterized.
8	* The parameters are passed as parameters in the url and are available in the
9	* params respecting Grails' conventions. In this file, we adher to the javadoc
10	* convention for describing parameters ("@param"), but actually we mean
11	* key-value pairs in the params object of each Grails action we comment on.
12	*
13	* @author Jahn-Takeshi Saito
14	* @since 20100601
15	*
16	*/
17
18	import dbnp.studycapturing.Study
19	import dbnp.studycapturing.Assay
20	import dbnp.authentication.SecUser
21	import grails.converters.*
22	import nl.metabolomicscentre.dsp.http.BasicAuthentication
23	import dbnp.rest.common.CommunicationManager
24	import org.springframework.security.core.context.SecurityContextHolder;
25
26	class RestController {
27
28	/**************************************************/
29	/ Rest resources for Simple Assay Module (SAM) /
30	/**************************************************/
31
32	def AuthenticationService
33	def beforeInterceptor = [action:this.&auth,except:["isUser"]]
34	def credentials
35	def requestUser
36
37	/**
38	* Authorization closure, which is run before executing any of the REST resource actions
39	* It fetches a consumer/token combination from the url and checks whether
40	* that is a correct and known combination
41	*
42	* @param consumer consumer name of the calling module
43	* @param token token for the authenticated user (e.g. session_id)
44	* @return true if the user is remotely logged in, false otherwise
45	*/
46	private def auth() {
47	if( !AuthenticationService.isRemotelyLoggedIn( params.consumer, params.token ) ) {
48	response.sendError(403)
49	return false
50	} else {
51	return true
52	}
53	}
54
55	/**
56	* REST resource for data modules.
57	* Consumer and token should be supplied via URL parameters.
58	* Determines whether the given user/password combination is a valid GSCF account.
59	*
60	* @param consumer consumer name of the calling module
61	* @param token token for the authenticated user (e.g. session_id)
62	* @return bool {"authenticated":true} when user/password is a valid GSCF account, {"authenticated":false} otherwise.
63	*/
64	def isUser = {
65	boolean isUser = AuthenticationService.isRemotelyLoggedIn( params.consumer, params.token )
66	def reply = ['authenticated':isUser]
67	render reply as JSON
68	}
69
70	/**
71	* REST resource for data modules.
72	* Consumer and token should be supplied via URL parameters.
73	* Provides the details of the user that has logged in
74	*
75	* @param consumer consumer name of the calling module
76	* @param token token for the authenticated user (e.g. session_id)
77	* @return bool {"username": "...", "id": ... } when user/password is logged in.
78	*/
79	def getUser = {
80	SecUser user = AuthenticationService.getRemotelyLoggedInUser( params.consumer, params.token )
81	def reply = [username: user.username, id: user.id]
82	render reply as JSON
83	}
84
85
86	/**
87	* REST resource for data modules.
88	* Consumer and token should be supplied via URL parameters.
89	* Provide a list of all studies owned by the supplied user.
90	*
91	* @param studyToken optional parameter. If no studyToken is given, all studies available to user are returned.
92	* Otherwise, the studies for which the studyTokens are given are be returned.
93	* @param consumer consumer name of the calling module
94	* @param token token for the authenticated user (e.g. session_id)
95	* @return JSON object list containing 'studyToken', and 'name' (title) for each study
96	*
97	* If one study is requested, a 404 error might occur if the study doesn't exist, and a 401 error if the user is not
98	* authorized to access this study. If multiple studies are requrested, non-existing studies or studies for which the
99	* user is not authorized are not returned in the list (so the list might be empty).
100	*
101	* Example 1. REST call without studyToken.
102	*
103	* Call: http://localhost:8080/gscf/rest/getStudies/query
104	*
105	* Result: [{"title":"NuGO PPS3 mouse study leptin module","studyToken":"PPS3_leptin_module",
106	* "startDate":"2008-01-01T23:00:00Z","published":false,"Description":"C57Bl/6 mice were fed a high fat (45 en%)
107	* or low fat (10 en%) diet after a four week run-in on low fat diet.","Objectives":null,"Consortium":null,
108	* "Cohort name":null,"Lab id":null,"Institute":null,"Study protocol":null},
109	* {"title":"NuGO PPS human study","studyToken":"PPSH","startDate":"2008-01-13T23:00:00Z","published":false,
110	* "Description":"Human study performed at RRI; centres involved: RRI, IFR, TUM, Maastricht U.","Objectives":null,
111	* "Consortium":null,"Cohort name":null,"Lab id":null,"Institute":null,"Study protocol":null}]
112	*
113	*
114	* Example 2. REST call with one studyToken.
115	*
116	* Call: http://localhost:8080/gscf/rest/getStudies/query?studyToken=PPSH
117	*
118	* Result: [{"title":"NuGO PPS human study","studyToken":"PPSH","startDate":"2008-01-13T23:00:00Z",
119	* "published":false,"Description":"Human study performed at RRI; centres involved: RRI, IFR, TUM, Maastricht U.",
120	* "Objectives":null,"Consortium":null,"Cohort name":null,"Lab id":null,"Institute":null,"Study protocol":null}]
121	*
122	*
123	*
124	* Example 2. REST call with two studyTokens.
125	*
126	* http://localhost:8080/gscf/rest/getStudies/query?studyToken=PPSH&studyToken=PPS3_leptin_module
127	*
128	* Result: same as result of Example 1.
129	*/
130	def getStudies = {
131
132	List returnStudies = []
133	List studies = []
134
135	if( !params.studyToken ) {
136	studies = Study.findAll()
137	}
138	else if( params.studyToken instanceof String ) {
139	def study = Study.findByCode( params.studyToken )
140	if( study ) {
141	if( !study.canRead(AuthenticationService.getRemotelyLoggedInUser( params.consumer, params.token )) ) {
142	response.sendError(401)
143	return false
144	}
145
146	studies.push study
147	} else {
148	response.sendError(404)
149	return false
150	}
151
152	}
153	else {
154	params.studyToken.each{ studyToken ->
155	def study = Study.findByCode( studyToken );
156	if( study )
157	studies.push study
158	}
159	}
160
161
162	studies.each { study ->
163	if(study) {
164	def user = AuthenticationService.getRemotelyLoggedInUser( params.consumer, params.token )
165	// Check whether the person is allowed to read the data of this study
166	if( study.canRead(AuthenticationService.getRemotelyLoggedInUser( params.consumer, params.token ))) {
167
168	def items = [:]
169	study.giveFields().each { field ->
170	def name = field.name
171	def value = study.getFieldValue( name )
172	if( name=='code' ) {
173	name = 'studyToken'
174	}
175	items[name] = value
176	}
177	returnStudies.push items
178	}
179	}
180	}
181
182	render returnStudies as JSON
183	}
184
185
186	/**
187	* REST resource for data modules.
188	* Consumer and token should be supplied via URL parameters.
189	* Provide a list of all subjects belonging to a study.
190	*
191	* If the user is not allowed to read the study contents, a 401 error is given. If the study doesn't exist, a 404 error is given
192	*
193	* @param studyToken String The external study id (code) of the target GSCF Study object
194	* @param consumer consumer name of the calling module
195	* @param token token for the authenticated user (e.g. session_id)
196	* @return JSON object list of subject names
197	*/
198	def getSubjects = {
199	List subjects = []
200	if( params.studyToken ) {
201	def id = params.studyToken
202	def study = Study.find( "from Study as s where s.code=?", [id])
203
204	if(study) {
205	// Check whether the person is allowed to read the data of this study
206	if( !study.canRead(AuthenticationService.getRemotelyLoggedInUser( params.consumer, params.token ))) {
207	response.sendError(401)
208	return false
209	}
210
211	study.subjects.each { subjects.push it.name }
212	} else {
213	response.sendError(404)
214	return false
215	}
216	}
217	render subjects as JSON
218	}
219
220
221	/**
222	* REST resource for data modules.
223	* Consumer and token should be supplied via URL parameters.
224	* Provide a list of all assays for a given study.
225	*
226	* If the user is not allowed to read the study contents, a 401 error is given. If the study doesn't exist, a 404 error is given
227	*
228	* @param studyToken String The external study id (code) of the target GSCF Study object
229	* @param consumer consumer name of the calling module
230	* @return list of assays in the study as JSON object list, filtered to only contain assays
231	* for the specified module, with 'assayToken' and 'name' for each assay
232	*
233	*
234	* Example 1. REST call without assayToken
235	* http://localhost:8080/gscf/rest/getAssays/aas?studyToken=PPSH
236	* &consumer=http://localhost:8182/sam
237	*
238	* Result: [{"name":"Glucose assay after",
239	* "module":{"class":"dbnp.studycapturing.AssayModule","id":1,"name":"SAM module for clinical data",
240	* "platform":"clinical measurements","url":"http://localhost:8182/sam"},
241	* "externalAssayID":"PPSH-Glu-A", "Description":null,"parentStudyToken":"PPSH"},
242	* {"name":"Glucose assay before",
243	* "module":{"class":"dbnp.studycapturing.AssayModule","id":1,"name":"SAM module for clinical data",
244	* "platform":"clinical measurements","url":"http://localhost:8182/sam"},
245	* "externalAssayID":"PPSH-Glu-B","Description":null,"parentStudyToken":"PPSH"}]
246	*
247	*
248	* Example 2. REST call with one assayToken
249	* http://localhost:8080/gscf/rest/getAssays/queryOneTokenz?studyToken=PPSH
250	* &consumer=http://localhost:8182/sam&assayToken=PPSH-Glu-A
251	*
252	* Result: [{"name":"Glucose assay after","module":{"class":"dbnp.studycapturing.AssayModule","id":1,
253	* "name":"SAM module for clinical data","platform":"clinical measurements","url":"http://localhost:8182/sam"},
254	* "externalAssayID":"PPSH-Glu-A","Description":null,"parentStudyToken":"PPSH"}]
255	*
256	*
257	* Example 3. REST call with two assayTokens.
258	*
259	* Result: Same as result in Example 1.
260	*/
261	def getAssays = {
262
263	List returnList = [] // return list of hashes each containing fields and values belonging to an assay
264
265	// Check if required parameters are present
266	def validCall = CommunicationManager.hasValidParams( params, "consumer", "studyToken" )
267	if( !validCall ) {
268	render "Error. Wrong or insufficient parameters." as JSON
269	return
270	}
271
272	if( params.studyToken ) {
273
274	def id = params.studyToken
275	def study = Study.findByCode(id)
276
277	if(study) {
278	// Check whether the person is allowed to read the data of this study
279	if( !study.canRead(AuthenticationService.getRemotelyLoggedInUser( params.consumer, params.token ))) {
280	response.sendError(401)
281	return false
282	}
283
284	def assays = []
285	if(params.assayToken==null) {
286	assays = study.assays
287	}
288	else if( params.assayToken instanceof String ) {
289	def assay = study.assays.find{ it.externalAssayID==params.assayToken }
290	if( assay ) {
291	assays.push assay
292	}
293	}
294	else { // there are multiple assayTokens instances
295	params.assayToken.each { assayToken ->
296	def assay = study.assays.find{ it.externalAssayID==assayToken }
297	if(assay) {
298	assays.push assay
299	}
300	}
301	}
302
303	assays.each{ assay ->
304	if (assay.module.url.equals(params.consumer)) {
305	if(assay) {
306	def map = [:]
307	assay.giveFields().each { field ->
308	def name = field.name
309	def value = assay.getFieldValue( name )
310	if(field.name=='externalAssayID') {
311	name = 'assayToken'
312	}
313	map[name] = value
314	}
315	map["parentStudyToken"] = assay.parent.getToken()
316	returnList.push( map )
317	}
318	}
319	}
320	} else {
321	response.sendError(404)
322	return false
323	}
324
325	}
326	render returnList as JSON
327	}
328
329
330
331
332
333
334
335	/**
336	* REST resource for data modules.
337	* Provide all samples of a given Assay. The result is an enriched list with additional information for each sample.
338	*
339	* If the user is not allowed to read the study contents, a 401 error is given. If the assay doesn't exist, a 404 error is given
340	*
341	* @param assayToken String (assayToken of some Assay in GSCF)
342	* @param sampleToken Optional parameter. One or more sampleTokens to specify what sample to give exectly.
343	* If not given, return all samples for specified assay.
344	* @param consumer consumer name of the calling module
345	* @param token token for the authenticated user (e.g. session_id)
346	* @return As a JSON object list, for each sample in that assay:
347	* @return 'name' (Sample name, which is unique)
348	* @return 'material' (Sample material)
349	* @return 'subject' (The name of the subject from which the sample was taken)
350	* @return 'event' (the name of the template of the SamplingEvent describing the sampling)
351	* @return 'startTime' (the time the sample was taken relative to the start of the study, as a string)
352	* @return additional template fields are returned
353	*
354	*
355	*
356	* Example 1: no sampleTokens given.
357	* Query:
358	* http://localhost:8080/gscf/rest/getSamples/query?assayToken=PPSH-Glu-A
359	*
360	* Result:
361	* [{"sampleToken":"5_A","material":"blood plasma","subject":"5","event":"Blood extraction","startTime":"4 days, 6 hours"},
362	* {"sampleToken":"6_A","material":"blood plasma","subject":"6","event":"Blood extraction","startTime":"4 days, 6 hours"},
363	* {"sampleToken":"10_A","material":"blood plasma","subject":"10","event":"Blood extraction","startTime":"4 days, 6 hours"},
364	* {"sampleToken":"2_A","material":"blood plasma","subject":"2","event":"Blood extraction","startTime":"4 days, 6 hours"},
365	* {"sampleToken":"11_A","material":"blood plasma","subject":"11","event":"Blood extraction","startTime":"4 days, 6 hours"},
366	* {"sampleToken":"1_A","material":"blood plasma","subject":"1","event":"Blood extraction","startTime":"4 days, 6 hours"},
367	* {"sampleToken":"9_A","material":"blood plasma","subject":"9","event":"Blood extraction","startTime":"4 days, 6 hours"},
368	* {"sampleToken":"4_A","material":"blood plasma","subject":"4","event":"Blood extraction","startTime":"4 days, 6 hours"},
369	* {"sampleToken":"8_A","material":"blood plasma","subject":"8","event":"Blood extraction","startTime":"4 days, 6 hours"},
370	* {"sampleToken":"7_A","material":"blood plasma","subject":"7","event":"Blood extraction","startTime":"4 days, 6 hours"},
371	* {"sampleToken":"3_A","material":"blood plasma","subject":"3","event":"Blood extraction","startTime":"4 days, 6 hours"}]
372	*
373	*
374	*
375	* Example 2: one sampleToken given.
376	* Query:
377	* http://localhost:8080/gscf/rest/getSamples/query?assayToken=PPSH-Glu-A&sampleToken=5_A
378	*
379	* Result:
380	* [{"sampleToken":"5_A","material":"blood plasma","subject":"5","event":"Blood extraction","startTime":"4 days, 6 hours"}]
381	*
382	*
383	*
384	* Example 3: two sampleTokens given.
385	* Query:
386	* http://localhost:8080/gscf/rest/getSamples/query?assayToken=PPSH-Glu-A&sampleToken=5_A
387	*
388	* Result:
389	* [{"sampleToken":"5_A","material":"blood plasma","subject":"5","event":"Blood extraction","startTime":"4 days, 6 hours"},
390	* {"sampleToken":"6_A","material":"blood plasma","subject":"6","event":"Blood extraction","startTime":"4 days, 6 hours"}]
391	*/
392	def getSamples = {
393	def items = []
394	if( params.assayToken ) {
395	def assay = Assay.find( "from Assay as a where externalAssayID=?",[params.assayToken])
396
397	if( assay ) {
398	// Check whether the person is allowed to read the data of this study
399	if( !assay.parent.canRead(AuthenticationService.getRemotelyLoggedInUser( params.consumer, params.token ))) {
400	response.sendError(401)
401	return false
402	}
403
404	def samples = assay.getSamples() // on all samples
405
406	if( params.sampleToken ) { // or on a subset of samples?
407	def sampleTokens = (params.sampleToken instanceof String) ?
408	[params.sampleToken] : params.sampleToken
409	samples = []
410	sampleTokens.each{ sampleToken ->
411	samples.addAll(assay.getSamples().find{ sample -> sampleToken == sample.name })
412	}
413	}
414
415	samples.each { sample ->
416
417	def item = [
418	'material' : sample.material?.name,
419	'subject' : sample.parentSubject?.name,
420	'event' : sample.parentEvent?.template?.name,
421	'startTime' : sample.parentEvent?.getStartTimeString()
422	]
423
424	sample.giveFields().each { field ->
425	def name = field.name
426	def value = sample.getFieldValue( name )
427	if(name!='material')
428	{
429	item[name]=value
430	}
431	}
432
433	if(sample.parentEvent) {
434	def parentEvent = sample.parentEvent
435	def eventHash = [:]
436	parentEvent.giveFields().each { field ->
437	def name = field.name
438	if( name!='sampleTemplate' && name!='fields') {
439	def value = parentEvent.getFieldValue( name )
440	eventHash[name]=value
441	}
442	}
443	item['eventObject'] = eventHash
444	}
445
446	if(sample.parentSubject) {
447	def parentSubject = sample.parentSubject
448	def subject = [:]
449	parentSubject.giveFields().each { field ->
450	def name = field.name
451	if( name!='fields') {
452	def value = parentSubject.getFieldValue( name )
453	subject[name]=value
454	}
455	}
456	item['subjectObject'] = subject
457	}
458
459	items.push item
460	}
461	} else {
462	// Assay not found
463	response.sendError(404)
464	return false
465	}
466	}
467	render items as JSON
468	}
469
470
471
472
473
474
475
476
477	/**
478	* Returns the authorization level the user has for a given study.
479	*
480	* If no studyToken is given, a 400 (Bad Request) error is given.
481	* If the given study doesn't exist, a 404 (Not found) error is given.
482	*
483	* @param consumer consumer name of the calling module
484	* @param token token for the authenticated user (e.g. session_id)
485	* @return JSON Object
486	* @return { isOwner: true/false, 'canRead': true/false, 'canWrite': true/false }
487	*/
488	def getAuthorizationLevel = {
489	if( params.studyToken ) {
490	def id = params.studyToken
491	def study = Study.find( "from Study as s where s.code=?", [id])
492
493	if( !study ) {
494	response.sendError(404)
495	return false
496	}
497
498	def user = AuthenticationService.getRemotelyLoggedInUser( params.consumer, params.token );
499	render( ['isOwner': study.isOwner(user), 'canRead': study.canRead(user), 'canWrite': study.canWrite(user)] as JSON )
500	} else {
501	response.sendError(400)
502	return false
503	}
504	}
505
506	}

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

Download in other formats: