Change the return type of the open-ils.qstore.prepare method.
[working/Evergreen.git] / Open-ILS / src / c-apps / oils_qstore.c
1 /**
2         @file oils_qstore.c
3         @brief As a server, perform database queries as defined in the database itself.
4 */
5
6 #include <stdlib.h>
7 #include <string.h>
8 #include <ctype.h>
9 #include <dbi/dbi.h>
10 #include "opensrf/utils.h"
11 #include "opensrf/log.h"
12 #include "opensrf/osrf_json.h"
13 #include "opensrf/osrf_application.h"
14 #include "openils/oils_utils.h"
15 #include "openils/oils_sql.h"
16 #include "openils/oils_buildq.h"
17
18 /**
19         @brief Information about a previously prepared query.
20
21         We store an osrfHash of CachedQueries in the userData area of the application session,
22         keyed on query token.  That way we can fetch what a previous call to the prepare method
23         has prepared.
24 */
25 typedef struct {
26         BuildSQLState* state;
27         StoredQ*       query;
28 } CachedQuery;
29
30 static dbi_conn dbhandle; /* our db connection */
31
32 static const char modulename[] = "open-ils.qstore";
33
34 int doPrepare( osrfMethodContext* ctx );
35 int doExecute( osrfMethodContext* ctx );
36 int doSql( osrfMethodContext* ctx );
37
38 static const char* save_query(
39         osrfMethodContext* ctx, BuildSQLState* state, StoredQ* query );
40 static void free_cached_query( char* key, void* data );
41 static void userDataFree( void* blob );
42 static CachedQuery* search_token( osrfMethodContext* ctx, const char* token );
43
44 /**
45         @brief Disconnect from the database.
46
47         This function is called when the server drone is about to terminate.
48 */
49 void osrfAppChildExit() {
50         osrfLogDebug( OSRF_LOG_MARK, "Child is exiting, disconnecting from database..." );
51
52         if ( dbhandle ) {
53                 dbi_conn_query( dbhandle, "ROLLBACK;" );
54                 dbi_conn_close( dbhandle );
55                 dbhandle = NULL;
56         }
57 }
58
59 /**
60         @brief Initialize the application.
61         @return Zero if successful, or non-zero if not.
62
63         Load the IDL file into an internal data structure for future reference.  Each non-virtual
64         class in the IDL corresponds to a table or view in the database, or to a subquery defined
65         in the IDL.  Ignore all virtual tables and virtual fields.
66
67         Register the functions for remote procedure calls.
68
69         This function is called when the registering the application, and is executed by the
70         listener before spawning the drones.
71 */
72 int osrfAppInitialize() {
73
74         osrfLogInfo( OSRF_LOG_MARK, "Initializing the QStore Server..." );
75         osrfLogInfo( OSRF_LOG_MARK, "Finding XML file..." );
76
77         if ( !oilsIDLInit( osrf_settings_host_value( "/IDL" )))
78                 return 1; /* return non-zero to indicate error */
79
80         // Set the SQL options.  Here the second and third parameters are irrelevant, but we need
81         // to set the module name for use in error messages.
82         oilsSetSQLOptions( modulename, 0, 100 );
83
84         growing_buffer* method_name = buffer_init( 64 );
85
86         OSRF_BUFFER_ADD( method_name, modulename );
87         OSRF_BUFFER_ADD( method_name, ".prepare" );
88         osrfAppRegisterMethod( modulename, OSRF_BUFFER_C_STR( method_name ),
89                 "doPrepare", "", 1, 0 );
90
91         buffer_reset( method_name );
92         OSRF_BUFFER_ADD( method_name, modulename );
93         OSRF_BUFFER_ADD( method_name, ".columns" );
94         osrfAppRegisterMethod( modulename, OSRF_BUFFER_C_STR( method_name ),
95                 "doColumns", "", 1, 0 );
96
97         buffer_reset( method_name );
98         OSRF_BUFFER_ADD( method_name, modulename );
99         OSRF_BUFFER_ADD( method_name, ".param_list" );
100         osrfAppRegisterMethod( modulename, OSRF_BUFFER_C_STR( method_name ),
101                 "doParamList", "", 1, 0 );
102
103         buffer_reset( method_name );
104         OSRF_BUFFER_ADD( method_name, modulename );
105         OSRF_BUFFER_ADD( method_name, ".bind_param" );
106         osrfAppRegisterMethod( modulename, OSRF_BUFFER_C_STR( method_name ),
107                 "doBindParam", "", 2, 0 );
108
109         buffer_reset( method_name );
110         OSRF_BUFFER_ADD( method_name, modulename );
111         OSRF_BUFFER_ADD( method_name, ".execute" );
112         osrfAppRegisterMethod( modulename, OSRF_BUFFER_C_STR( method_name ),
113                 "doExecute", "", 1, OSRF_METHOD_STREAMING );
114
115         buffer_reset( method_name );
116         OSRF_BUFFER_ADD( method_name, modulename );
117         OSRF_BUFFER_ADD( method_name, ".sql" );
118         osrfAppRegisterMethod( modulename, OSRF_BUFFER_C_STR( method_name ),
119                 "doSql", "", 1, OSRF_METHOD_STREAMING );
120
121         buffer_reset( method_name );
122         OSRF_BUFFER_ADD( method_name, modulename );
123         OSRF_BUFFER_ADD( method_name, ".finish" );
124         osrfAppRegisterMethod( modulename, OSRF_BUFFER_C_STR( method_name ),
125                 "doFinish", "", 1, 0 );
126
127         buffer_reset( method_name );
128         OSRF_BUFFER_ADD( method_name, modulename );
129         OSRF_BUFFER_ADD( method_name, ".messages" );
130         osrfAppRegisterMethod( modulename, OSRF_BUFFER_C_STR( method_name ),
131                 "doMessages", "", 1, 0 );
132
133         return 0;
134 }
135
136 /**
137         @brief Initialize a server drone.
138         @return Zero if successful, -1 if not.
139
140         Connect to the database.  For each non-virtual class in the IDL, execute a dummy "SELECT * "
141         query to get the datatype of each column.  Record the datatypes in the loaded IDL.
142
143         This function is called by a server drone shortly after it is spawned by the listener.
144 */
145 int osrfAppChildInit( void ) {
146
147         dbhandle = oilsConnectDB( modulename );
148         if( !dbhandle )
149                 return -1;
150         else {
151                 oilsSetDBConnection( dbhandle );
152                 osrfLogInfo( OSRF_LOG_MARK, "%s successfully connected to the database", modulename );
153
154                 // Apply datatypes from database to the fields in the IDL
155                 //if( oilsExtendIDL() ) {
156                 //      osrfLogError( OSRF_LOG_MARK, "Error extending the IDL" );
157                 //      return -1;
158                 //}
159                 //else
160                 return 0;
161         }
162 }
163
164 /**
165         @brief Load a specified query from the database query tables.
166         @param ctx Pointer to the current method context.
167         @return Zero if successful, or -1 if not.
168
169         Method parameters:
170         - query id (key of query.stored_query table)
171
172         Returns: a hash with two entries:
173         - "token": A character string serving as a token for future references to the query.
174         - "bind_variables" A hash of bind variables; see notes for doParamList().
175 */
176 int doPrepare( osrfMethodContext* ctx ) {
177         if(osrfMethodVerifyContext( ctx )) {
178                 osrfLogError( OSRF_LOG_MARK,  "Invalid method context" );
179                 return -1;
180         }
181
182         // Get the query id from a method parameter
183         const jsonObject* query_id_obj = jsonObjectGetIndex( ctx->params, 0 );
184         if( query_id_obj->type != JSON_NUMBER ) {
185                 osrfAppSessionStatus( ctx->session, OSRF_STATUS_BADREQUEST, "osrfMethodException",
186                         ctx->request, "Invalid parameter; query id must be a number" );
187                 return -1;
188         }
189
190         int query_id = atoi( jsonObjectGetString( query_id_obj ));
191         if( query_id <= 0 ) {
192                 osrfAppSessionStatus( ctx->session, OSRF_STATUS_BADREQUEST, "osrfMethodException",
193                         ctx->request, "Invalid parameter: query id must be greater than zero" );
194                 return -1;
195         }
196
197         osrfLogInfo( OSRF_LOG_MARK, "Loading query for id # %d", query_id );
198
199         BuildSQLState* state = buildSQLStateNew( dbhandle );
200         state->defaults_usable = 1;
201         state->values_required = 0;
202         StoredQ* query = getStoredQuery( state, query_id );
203         if( state->error ) {
204                 osrfLogWarning( OSRF_LOG_MARK, "Unable to load stored query # %d", query_id );
205                 osrfAppSessionStatus( ctx->session, OSRF_STATUS_BADREQUEST, "osrfMethodException",
206                         ctx->request, "Unable to load stored query" );
207                 return -1;
208         }
209
210         const char* token = save_query( ctx, state, query );
211
212         osrfLogInfo( OSRF_LOG_MARK, "Token for query id # %d is \"%s\"", query_id, token );
213
214         // Build an object to return: a hash containing the query token
215         // and a list of bind variables.
216         jsonObject* returned_obj = jsonNewObjectType( JSON_HASH );
217         jsonObjectSetKey( returned_obj, "token", jsonNewObject( token ));
218         jsonObjectSetKey( returned_obj, "bind_variables",
219                 oilsBindVarList( state->bindvar_list ));
220
221         osrfAppRespondComplete( ctx, returned_obj );
222         return 0;
223 }
224
225 /**
226         @brief Return a list of column names for the SELECT list.
227         @param ctx Pointer to the current method context.
228         @return Zero if successful, or -1 if not.
229
230         Method parameters:
231         - query token, as previously returned by the .prepare method.
232
233         Returns: An array of column names; unavailable names are represented as nulls.
234 */
235 int doColumns( osrfMethodContext* ctx ) {
236         if(osrfMethodVerifyContext( ctx )) {
237                 osrfLogError( OSRF_LOG_MARK,  "Invalid method context" );
238                 return -1;
239         }
240
241         // Get the query token from a method parameter
242         const jsonObject* token_obj = jsonObjectGetIndex( ctx->params, 0 );
243         if( token_obj->type != JSON_STRING ) {
244                 osrfAppSessionStatus( ctx->session, OSRF_STATUS_BADREQUEST, "osrfMethodException",
245                         ctx->request, "Invalid parameter; query token must be a string" );
246                 return -1;
247         }
248         const char* token = jsonObjectGetString( token_obj );
249
250         // Look up the query token in the session-level userData
251         CachedQuery* query = search_token( ctx, token );
252         if( !query ) {
253                 osrfAppSessionStatus( ctx->session, OSRF_STATUS_BADREQUEST, "osrfMethodException",
254                         ctx->request, "Invalid query token" );
255                 return -1;
256         }
257
258         osrfLogInfo( OSRF_LOG_MARK, "Listing column names for token %s", token );
259
260         jsonObject* col_list = oilsGetColNames( query->state, query->query );
261         if( query->state->error ) {
262                 osrfAppSessionStatus( ctx->session, OSRF_STATUS_BADREQUEST, "osrfMethodException",
263                         ctx->request, "Unable to get column names" );
264                 return -1;
265         } else {
266                 osrfAppRespondComplete( ctx, col_list );
267                 return 0;
268         }
269 }
270
271 /**
272         @brief Implement the param_list method.
273         @param ctx Pointer to the current method context.
274         @return Zero if successful, or -1 if not.
275
276         Provide a list of bind variables for a specified query, along with their various
277         attributes.
278
279         Method parameters:
280         - query token, as previously returned by the .prepare method.
281
282         Returns: A (possibly empty) JSON_HASH, keyed on the names of the bind variables.
283         The data for each is another level of JSON_HASH with a fixed set of tags:
284         - "label"
285         - "type"
286         - "description"
287         - "default_value" (as a jsonObject)
288         - "actual_value" (as a jsonObject)
289
290         Any non-existent values are represented as JSON_NULLs.
291 */
292 int doParamList( osrfMethodContext* ctx ) {
293         if(osrfMethodVerifyContext( ctx )) {
294                 osrfLogError( OSRF_LOG_MARK,  "Invalid method context" );
295                 return -1;
296         }
297
298         // Get the query token from a method parameter
299         const jsonObject* token_obj = jsonObjectGetIndex( ctx->params, 0 );
300         if( token_obj->type != JSON_STRING ) {
301                 osrfAppSessionStatus( ctx->session, OSRF_STATUS_BADREQUEST, "osrfMethodException",
302                         ctx->request, "Invalid parameter; query token must be a string" );
303                 return -1;
304         }
305         const char* token = jsonObjectGetString( token_obj );
306
307         // Look up the query token in the session-level userData
308         CachedQuery* query = search_token( ctx, token );
309         if( !query ) {
310                 osrfAppSessionStatus( ctx->session, OSRF_STATUS_BADREQUEST, "osrfMethodException",
311                         ctx->request, "Invalid query token" );
312                 return -1;
313         }
314
315         osrfLogInfo( OSRF_LOG_MARK, "Returning list of bind variables for token %s", token );
316
317         osrfAppRespondComplete( ctx, oilsBindVarList( query->state->bindvar_list ) );
318         return 0;
319 }
320
321 /**
322         @brief Implement the bind_param method.
323         @param ctx Pointer to the current method context.
324         @return Zero if successful, or -1 if not.
325
326         Apply values to bind variables, overriding the defaults, if any.
327
328         Method parameters:
329         - query token, as previously returned by the .prepare method.
330         - hash of bind variable values, keyed on bind variable names.
331
332         Returns: Nothing.
333 */
334 int doBindParam( osrfMethodContext* ctx ) {
335         if(osrfMethodVerifyContext( ctx )) {
336                 osrfLogError( OSRF_LOG_MARK,  "Invalid method context" );
337                 return -1;
338         }
339
340         // Get the query token from a method parameter
341         const jsonObject* token_obj = jsonObjectGetIndex( ctx->params, 0 );
342         if( token_obj->type != JSON_STRING ) {
343                 osrfAppSessionStatus( ctx->session, OSRF_STATUS_BADREQUEST, "osrfMethodException",
344                         ctx->request, "Invalid parameter; query token must be a string" );
345                 return -1;
346         }
347         const char* token = jsonObjectGetString( token_obj );
348
349         // Look up the query token in the session-level userData
350         CachedQuery* query = search_token( ctx, token );
351         if( !query ) {
352                 osrfAppSessionStatus( ctx->session, OSRF_STATUS_BADREQUEST, "osrfMethodException",
353                         ctx->request, "Invalid query token" );
354                 return -1;
355         }
356
357         osrfLogInfo( OSRF_LOG_MARK, "Binding parameter(s) for token %s", token );
358
359         jsonObject* bindings = jsonObjectGetIndex( ctx->params, 1 );
360         if( !bindings ) {
361                 osrfAppSessionStatus( ctx->session, OSRF_STATUS_BADREQUEST, "osrfMethodException",
362                         ctx->request, "No parameter provided for bind variable values" );
363                 return -1;
364         } else if( bindings->type != JSON_HASH ) {
365                 osrfAppSessionStatus( ctx->session, OSRF_STATUS_BADREQUEST, "osrfMethodException",
366                         ctx->request, "Invalid parameter for bind variable values: not a hash" );
367                 return -1;
368         }
369
370         if( 0 == bindings->size ) {
371                 // No values to assign; we're done.
372                 osrfAppRespondComplete( ctx, NULL );
373                 return 0;
374         }
375
376         osrfHash* bindvar_list = query->state->bindvar_list;
377         if( !bindvar_list || osrfHashGetCount( bindvar_list ) == 0 ) {
378                 osrfAppSessionStatus( ctx->session, OSRF_STATUS_BADREQUEST, "osrfMethodException",
379                         ctx->request, "There are no bind variables to which to assign values" );
380                 return -1;
381         }
382
383         if( oilsApplyBindValues( query->state, bindings )) {
384                 osrfAppSessionStatus( ctx->session, OSRF_STATUS_BADREQUEST, "osrfMethodException",
385                         ctx->request, "Unable to apply values to bind variables" );
386                 return -1;
387         } else {
388                 osrfAppRespondComplete( ctx, NULL );
389                 return 0;
390         }
391 }
392
393 /**
394         @brief Execute an SQL query and return a result set.
395         @param ctx Pointer to the current method context.
396         @return Zero if successful, or -1 if not.
397
398         Method parameters:
399         - query token, as previously returned by the .prepare method.
400
401         Returns: A series of responses, each of them a row represented as an array of column values.
402 */
403 int doExecute( osrfMethodContext* ctx ) {
404         if(osrfMethodVerifyContext( ctx )) {
405                 osrfLogError( OSRF_LOG_MARK,  "Invalid method context" );
406                 return -1;
407         }
408
409         // Get the query token
410         const jsonObject* token_obj = jsonObjectGetIndex( ctx->params, 0 );
411         if( token_obj->type != JSON_STRING ) {
412                 osrfAppSessionStatus( ctx->session, OSRF_STATUS_BADREQUEST, "osrfMethodException",
413                         ctx->request, "Invalid parameter; query token must be a string" );
414                 return -1;
415         }
416         const char* token = jsonObjectGetString( token_obj );
417
418         // Look up the query token in the session-level userData
419         CachedQuery* query = search_token( ctx, token );
420         if( !query ) {
421                 osrfAppSessionStatus( ctx->session, OSRF_STATUS_BADREQUEST, "osrfMethodException",
422                         ctx->request, "Invalid query token" );
423                 return -1;
424         }
425
426         osrfLogInfo( OSRF_LOG_MARK, "Executing query for token \"%s\"", token );
427         if( query->state->error ) {
428                 osrfLogWarning( OSRF_LOG_MARK, sqlAddMsg( query->state,
429                         "No valid prepared query available for query id # %d", query->query->id ));
430                 osrfAppSessionStatus( ctx->session, OSRF_STATUS_BADREQUEST, "osrfMethodException",
431                                                           ctx->request, "No valid prepared query available" );
432                 return -1;
433         } else if( buildSQL( query->state, query->query )) {
434                 osrfLogWarning( OSRF_LOG_MARK, sqlAddMsg( query->state,
435                         "Unable to build SQL statement for query id # %d", query->query->id ));
436                 osrfAppSessionStatus( ctx->session, OSRF_STATUS_BADREQUEST, "osrfMethodException",
437                         ctx->request, "Unable to build SQL statement" );
438                 return -1;
439         }
440
441         jsonObject* row = oilsFirstRow( query->state );
442         while( row ) {
443                 osrfAppRespond( ctx, row );
444                 row = oilsNextRow( query->state );
445         }
446
447         if( query->state->error ) {
448                 osrfLogWarning( OSRF_LOG_MARK, sqlAddMsg( query->state,
449                         "Unable to execute SQL statement for query id # %d", query->query->id ));
450                 osrfAppSessionStatus( ctx->session, OSRF_STATUS_BADREQUEST, "osrfMethodException",
451                         ctx->request, "Unable to execute SQL statement" );
452                 return -1;
453         }
454
455         osrfAppRespondComplete( ctx, NULL );
456         return 0;
457 }
458
459 /**
460         @brief Construct an SQL query, but without executing it.
461         @param ctx Pointer to the current method context.
462         @return Zero if successful, or -1 if not.
463
464         Method parameters:
465         - query token, as previously returned by the .prepare method.
466
467         Returns: A string containing an SQL query..
468 */
469 int doSql( osrfMethodContext* ctx ) {
470         if(osrfMethodVerifyContext( ctx )) {
471                 osrfLogError( OSRF_LOG_MARK,  "Invalid method context" );
472                 return -1;
473         }
474
475         // Get the query token
476         const jsonObject* token_obj = jsonObjectGetIndex( ctx->params, 0 );
477         if( token_obj->type != JSON_STRING ) {
478                 osrfAppSessionStatus( ctx->session, OSRF_STATUS_BADREQUEST, "osrfMethodException",
479                         ctx->request, "Invalid parameter; query token must be a string" );
480                 return -1;
481         }
482         const char* token = jsonObjectGetString( token_obj );
483
484         // Look up the query token in the session-level userData
485         CachedQuery* query = search_token( ctx, token );
486         if( !query ) {
487                 osrfAppSessionStatus( ctx->session, OSRF_STATUS_BADREQUEST, "osrfMethodException",
488                         ctx->request, "Invalid query token" );
489                 return -1;
490         }
491
492         osrfLogInfo( OSRF_LOG_MARK, "Returning SQL for token \"%s\"", token );
493         if( query->state->error ) {
494                 osrfLogWarning( OSRF_LOG_MARK, sqlAddMsg( query->state,
495                         "No valid prepared query available for query id # %d", query->query->id ));
496                 osrfAppSessionStatus( ctx->session, OSRF_STATUS_BADREQUEST, "osrfMethodException",
497                         ctx->request, "No valid prepared query available" );
498                 return -1;
499         } else if( buildSQL( query->state, query->query )) {
500                 osrfLogWarning( OSRF_LOG_MARK, sqlAddMsg( query->state,
501                         "Unable to build SQL statement for query id # %d", query->query->id ));
502                 osrfAppSessionStatus( ctx->session, OSRF_STATUS_BADREQUEST, "osrfMethodException",
503                         ctx->request, "Unable to build SQL statement" );
504                 return -1;
505         }
506
507         osrfAppRespondComplete( ctx, jsonNewObject( OSRF_BUFFER_C_STR( query->state->sql )));
508         return 0;
509 }
510
511 /**
512         @brief Return a list of previously generated error messages for a specified query.
513         @param ctx Pointer to the current method context.
514         @return Zero if successful, or -1 if not.
515
516         Method parameters:
517         - query token, as previously returned by the .prepare method.
518
519         Returns: A (possibly empty) array of strings, each one an error message generated during
520         previous operations in connection with the specified query.
521 */
522 int doMessages( osrfMethodContext* ctx ) {
523         if(osrfMethodVerifyContext( ctx )) {
524                 osrfLogError( OSRF_LOG_MARK,  "Invalid method context" );
525                 return -1;
526         }
527
528         // Get the query token from a method parameter
529         const jsonObject* token_obj = jsonObjectGetIndex( ctx->params, 0 );
530         if( token_obj->type != JSON_STRING ) {
531                 osrfAppSessionStatus( ctx->session, OSRF_STATUS_BADREQUEST, "osrfMethodException",
532                         ctx->request, "Invalid parameter; query token must be a string" );
533                 return -1;
534         }
535         const char* token = jsonObjectGetString( token_obj );
536
537         // Look up the query token in the session-level userData
538         CachedQuery* query = search_token( ctx, token );
539         if( !query ) {
540                 osrfAppSessionStatus( ctx->session, OSRF_STATUS_BADREQUEST, "osrfMethodException",
541                         ctx->request, "Invalid query token" );
542                 return -1;
543         }
544
545         osrfLogInfo( OSRF_LOG_MARK, "Returning messages for token %s", token );
546
547         jsonObject* msgs = jsonNewObjectType( JSON_ARRAY );
548         const osrfStringArray* error_msgs = query->state->error_msgs;
549         int i;
550         for( i = 0; i < error_msgs->size; ++i ) {
551                 jsonObject* msg = jsonNewObject( osrfStringArrayGetString( error_msgs, i ));
552                 jsonObjectPush( msgs, msg );
553         }
554
555         osrfAppRespondComplete( ctx, msgs );
556         return 0;
557 }
558
559 /**
560         @brief Discard a previously stored query, as identified by a token.
561         @param ctx Pointer to the current method context.
562         @return Zero if successful, or -1 if not.
563
564         Method parameters:
565         - query token, as previously returned by the .prepare method.
566
567         Returns: Nothing.
568 */
569 int doFinish( osrfMethodContext* ctx ) {
570         if(osrfMethodVerifyContext( ctx )) {
571                 osrfLogError( OSRF_LOG_MARK,  "Invalid method context" );
572                 return -1;
573         }
574
575         // Get the query token.
576         const jsonObject* token_obj = jsonObjectGetIndex( ctx->params, 0 );
577         if( token_obj->type != JSON_STRING ) {
578                 osrfAppSessionStatus( ctx->session, OSRF_STATUS_BADREQUEST, "osrfMethodException",
579                                                           ctx->request, "Invalid parameter; query token must be a string" );
580                 return -1;
581         }
582         const char* token = jsonObjectGetString( token_obj );
583
584         // Delete the corresponding entry from the cache.  If there is no cache, or no such entry,
585         // just ignore the problem and report success.
586         osrfHash* cache = ctx->session->userData;
587         if( cache )
588                 osrfHashRemove( cache, token );
589
590         osrfAppRespondComplete( ctx, NULL );
591         return 0;
592 }
593
594 /**
595         @brief Save a query in session-level userData for reference in future method calls.
596         @param ctx Pointer to the current method context.
597         @param state Pointer to the state of the query.
598         @param query Pointer to the abstract representation of the query.
599         @return Pointer to an identifying token to be returned to the client.
600 */
601 static const char* save_query(
602         osrfMethodContext* ctx, BuildSQLState* state, StoredQ* query ) {
603
604         CachedQuery* cached_query = safe_malloc( sizeof( CachedQuery ));
605         cached_query->state       = state;
606         cached_query->query       = query;
607
608         // Get the cache.  If we don't have one yet, make one.
609         osrfHash* cache = ctx->session->userData;
610         if( !cache ) {
611                 cache = osrfNewHash();
612                 osrfHashSetCallback( cache, free_cached_query );
613                 ctx->session->userData = cache;
614                 ctx->session->userDataFree = userDataFree;  // arrange to free it at end of session
615         }
616
617         // Create a token string to be used as a key
618         static unsigned int token_count = 0;
619         char* token = va_list_to_string(
620                 "%u_%ld_%ld", ++token_count, (long) time( NULL ), (long) getpid() );
621
622         osrfHashSet( cache, cached_query, token );
623         return token;
624 }
625
626 /**
627         @brief Free a CachedQuery
628         @param Pointer to the CachedQuery to be freed.
629 */
630 static void free_cached_query( char* key, void* data ) {
631         if( data ) {
632                 CachedQuery* cached_query = data;
633                 buildSQLStateFree( cached_query->state );
634                 storedQFree( cached_query->query );
635         }
636 }
637
638 /**
639         @brief Callback for freeing session-level userData.
640         @param blob Opaque pointer t userData.
641 */
642 static void userDataFree( void* blob ) {
643         osrfHashFree( (osrfHash*) blob );
644 }
645
646 /**
647         @brief Search for the cached query corresponding to a given token.
648         @param ctx Pointer to the current method context.
649         @param token Token string from a previous call to the prepare method.
650         @return A pointer to the cached query, if found, or NULL if not.
651 */
652 static CachedQuery* search_token( osrfMethodContext* ctx, const char* token ) {
653         if( ctx && ctx->session->userData && token ) {
654                 osrfHash* cache = ctx->session->userData;
655                 return osrfHashGet( cache, token );
656         } else
657                 return NULL;
658 }