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                 if( state->panic ) {
 208                         osrfLogError( OSRF_LOG_MARK, sqlAddMsg( state,
 209                                 "Database connection isn't working" ));
 210                         osrfAppSessionPanic( ctx->session );
 211                 }
 212                 return -1;
 213         }
 214
 215         const char* token = save_query( ctx, state, query );
 216
 217         osrfLogInfo( OSRF_LOG_MARK, "Token for query id # %d is \"%s\"", query_id, token );
 218
 219         // Build an object to return.  It will be a hash containing the query token and a
 220         // list of bind variables.
 221         jsonObject* returned_obj = jsonNewObjectType( JSON_HASH );
 222         jsonObjectSetKey( returned_obj, "token", jsonNewObject( token ));
 223         jsonObjectSetKey( returned_obj, "bind_variables",
 224                 oilsBindVarList( state->bindvar_list ));
 225
 226         osrfAppRespondComplete( ctx, returned_obj );
 227         return 0;
 228 }
 229
 230 /**
 231         @brief Return a list of column names for the SELECT list.
 232         @param ctx Pointer to the current method context.
 233         @return Zero if successful, or -1 if not.
 234
 235         Method parameters:
 236         - query token, as previously returned by the .prepare method.
 237
 238         Returns: An array of column names; unavailable names are represented as nulls.
 239 */
 240 int doColumns( osrfMethodContext* ctx ) {
 241         if(osrfMethodVerifyContext( ctx )) {
 242                 osrfLogError( OSRF_LOG_MARK,  "Invalid method context" );
 243                 return -1;
 244         }
 245
 246         // Get the query token from a method parameter
 247         const jsonObject* token_obj = jsonObjectGetIndex( ctx->params, 0 );
 248         if( token_obj->type != JSON_STRING ) {
 249                 osrfAppSessionStatus( ctx->session, OSRF_STATUS_BADREQUEST, "osrfMethodException",
 250                         ctx->request, "Invalid parameter; query token must be a string" );
 251                 return -1;
 252         }
 253         const char* token = jsonObjectGetString( token_obj );
 254
 255         // Look up the query token in the session-level userData
 256         CachedQuery* query = search_token( ctx, token );
 257         if( !query ) {
 258                 osrfAppSessionStatus( ctx->session, OSRF_STATUS_BADREQUEST, "osrfMethodException",
 259                         ctx->request, "Invalid query token" );
 260                 return -1;
 261         }
 262
 263         osrfLogInfo( OSRF_LOG_MARK, "Listing column names for token %s", token );
 264
 265         jsonObject* col_list = oilsGetColNames( query->state, query->query );
 266         if( query->state->error ) {
 267                 osrfAppSessionStatus( ctx->session, OSRF_STATUS_BADREQUEST, "osrfMethodException",
 268                         ctx->request, "Unable to get column names" );
 269                 if( query->state->panic ) {
 270                         osrfLogError( OSRF_LOG_MARK, sqlAddMsg( query->state,
 271                                 "Database connection isn't working" ));
 272                         osrfAppSessionPanic( ctx->session );
 273                 }
 274                 return -1;
 275         } else {
 276                 osrfAppRespondComplete( ctx, col_list );
 277                 return 0;
 278         }
 279 }
 280
 281 /**
 282         @brief Implement the param_list method.
 283         @param ctx Pointer to the current method context.
 284         @return Zero if successful, or -1 if not.
 285
 286         Provide a list of bind variables for a specified query, along with their various
 287         attributes.
 288
 289         Method parameters:
 290         - query token, as previously returned by the .prepare method.
 291
 292         Returns: A (possibly empty) JSON_HASH, keyed on the names of the bind variables.
 293         The data for each is another level of JSON_HASH with a fixed set of tags:
 294         - "label"
 295         - "type"
 296         - "description"
 297         - "default_value" (as a jsonObject)
 298         - "actual_value" (as a jsonObject)
 299
 300         Any non-existent values are represented as JSON_NULLs.
 301 */
 302 int doParamList( osrfMethodContext* ctx ) {
 303         if(osrfMethodVerifyContext( ctx )) {
 304                 osrfLogError( OSRF_LOG_MARK,  "Invalid method context" );
 305                 return -1;
 306         }
 307
 308         // Get the query token from a method parameter
 309         const jsonObject* token_obj = jsonObjectGetIndex( ctx->params, 0 );
 310         if( token_obj->type != JSON_STRING ) {
 311                 osrfAppSessionStatus( ctx->session, OSRF_STATUS_BADREQUEST, "osrfMethodException",
 312                         ctx->request, "Invalid parameter; query token must be a string" );
 313                 return -1;
 314         }
 315         const char* token = jsonObjectGetString( token_obj );
 316
 317         // Look up the query token in the session-level userData
 318         CachedQuery* query = search_token( ctx, token );
 319         if( !query ) {
 320                 osrfAppSessionStatus( ctx->session, OSRF_STATUS_BADREQUEST, "osrfMethodException",
 321                         ctx->request, "Invalid query token" );
 322                 return -1;
 323         }
 324
 325         osrfLogInfo( OSRF_LOG_MARK, "Returning list of bind variables for token %s", token );
 326
 327         osrfAppRespondComplete( ctx, oilsBindVarList( query->state->bindvar_list ) );
 328         return 0;
 329 }
 330
 331 /**
 332         @brief Implement the bind_param method.
 333         @param ctx Pointer to the current method context.
 334         @return Zero if successful, or -1 if not.
 335
 336         Apply values to bind variables, overriding the defaults, if any.
 337
 338         Method parameters:
 339         - query token, as previously returned by the .prepare method.
 340         - hash of bind variable values, keyed on bind variable names.
 341
 342         Returns: Nothing.
 343 */
 344 int doBindParam( osrfMethodContext* ctx ) {
 345         if(osrfMethodVerifyContext( ctx )) {
 346                 osrfLogError( OSRF_LOG_MARK,  "Invalid method context" );
 347                 return -1;
 348         }
 349
 350         // Get the query token from a method parameter
 351         const jsonObject* token_obj = jsonObjectGetIndex( ctx->params, 0 );
 352         if( token_obj->type != JSON_STRING ) {
 353                 osrfAppSessionStatus( ctx->session, OSRF_STATUS_BADREQUEST, "osrfMethodException",
 354                         ctx->request, "Invalid parameter; query token must be a string" );
 355                 return -1;
 356         }
 357         const char* token = jsonObjectGetString( token_obj );
 358
 359         // Look up the query token in the session-level userData
 360         CachedQuery* query = search_token( ctx, token );
 361         if( !query ) {
 362                 osrfAppSessionStatus( ctx->session, OSRF_STATUS_BADREQUEST, "osrfMethodException",
 363                         ctx->request, "Invalid query token" );
 364                 return -1;
 365         }
 366
 367         osrfLogInfo( OSRF_LOG_MARK, "Binding parameter(s) for token %s", token );
 368
 369         jsonObject* bindings = jsonObjectGetIndex( ctx->params, 1 );
 370         if( !bindings ) {
 371                 osrfAppSessionStatus( ctx->session, OSRF_STATUS_BADREQUEST, "osrfMethodException",
 372                         ctx->request, "No parameter provided for bind variable values" );
 373                 return -1;
 374         } else if( bindings->type != JSON_HASH ) {
 375                 osrfAppSessionStatus( ctx->session, OSRF_STATUS_BADREQUEST, "osrfMethodException",
 376                         ctx->request, "Invalid parameter for bind variable values: not a hash" );
 377                 return -1;
 378         }
 379
 380         if( 0 == bindings->size ) {
 381                 // No values to assign; we're done.
 382                 osrfAppRespondComplete( ctx, NULL );
 383                 return 0;
 384         }
 385
 386         osrfHash* bindvar_list = query->state->bindvar_list;
 387         if( !bindvar_list || osrfHashGetCount( bindvar_list ) == 0 ) {
 388                 osrfAppSessionStatus( ctx->session, OSRF_STATUS_BADREQUEST, "osrfMethodException",
 389                         ctx->request, "There are no bind variables to which to assign values" );
 390                 return -1;
 391         }
 392
 393         if( oilsApplyBindValues( query->state, bindings )) {
 394                 osrfAppSessionStatus( ctx->session, OSRF_STATUS_BADREQUEST, "osrfMethodException",
 395                         ctx->request, "Unable to apply values to bind variables" );
 396                 return -1;
 397         } else {
 398                 osrfAppRespondComplete( ctx, NULL );
 399                 return 0;
 400         }
 401 }
 402
 403 /**
 404         @brief Execute an SQL query and return a result set.
 405         @param ctx Pointer to the current method context.
 406         @return Zero if successful, or -1 if not.
 407
 408         Method parameters:
 409         - query token, as previously returned by the .prepare method.
 410
 411         Returns: A series of responses, each of them a row represented as an array of column values.
 412 */
 413 int doExecute( osrfMethodContext* ctx ) {
 414         if(osrfMethodVerifyContext( ctx )) {
 415                 osrfLogError( OSRF_LOG_MARK,  "Invalid method context" );
 416                 return -1;
 417         }
 418
 419         // Get the query token
 420         const jsonObject* token_obj = jsonObjectGetIndex( ctx->params, 0 );
 421         if( token_obj->type != JSON_STRING ) {
 422                 osrfAppSessionStatus( ctx->session, OSRF_STATUS_BADREQUEST, "osrfMethodException",
 423                         ctx->request, "Invalid parameter; query token must be a string" );
 424                 return -1;
 425         }
 426         const char* token = jsonObjectGetString( token_obj );
 427
 428         // Look up the query token in the session-level userData
 429         CachedQuery* query = search_token( ctx, token );
 430         if( !query ) {
 431                 osrfAppSessionStatus( ctx->session, OSRF_STATUS_BADREQUEST, "osrfMethodException",
 432                         ctx->request, "Invalid query token" );
 433                 return -1;
 434         }
 435
 436         osrfLogInfo( OSRF_LOG_MARK, "Executing query for token \"%s\"", token );
 437         if( query->state->error ) {
 438                 osrfLogWarning( OSRF_LOG_MARK, sqlAddMsg( query->state,
 439                         "No valid prepared query available for query id # %d", query->query->id ));
 440                 osrfAppSessionStatus( ctx->session, OSRF_STATUS_BADREQUEST, "osrfMethodException",
 441                                                           ctx->request, "No valid prepared query available" );
 442                 return -1;
 443         } else if( buildSQL( query->state, query->query )) {
 444                 osrfLogWarning( OSRF_LOG_MARK, sqlAddMsg( query->state,
 445                         "Unable to build SQL statement for query id # %d", query->query->id ));
 446                 osrfAppSessionStatus( ctx->session, OSRF_STATUS_BADREQUEST, "osrfMethodException",
 447                         ctx->request, "Unable to build SQL statement" );
 448                 return -1;
 449         }
 450
 451         jsonObject* row = oilsFirstRow( query->state );
 452         while( row ) {
 453                 osrfAppRespond( ctx, row );
 454                 row = oilsNextRow( query->state );
 455         }
 456
 457         if( query->state->error ) {
 458                 osrfLogWarning( OSRF_LOG_MARK, sqlAddMsg( query->state,
 459                         "Unable to execute SQL statement for query id # %d", query->query->id ));
 460                 osrfAppSessionStatus( ctx->session, OSRF_STATUS_BADREQUEST, "osrfMethodException",
 461                         ctx->request, "Unable to execute SQL statement" );
 462                 if( query->state->panic ) {
 463                         osrfLogError( OSRF_LOG_MARK, sqlAddMsg( query->state,
 464                                 "Database connection isn't working" ));
 465                         osrfAppSessionPanic( ctx->session );
 466                 }
 467                 return -1;
 468         }
 469
 470         osrfAppRespondComplete( ctx, NULL );
 471         return 0;
 472 }
 473
 474 /**
 475         @brief Construct an SQL query, but without executing it.
 476         @param ctx Pointer to the current method context.
 477         @return Zero if successful, or -1 if not.
 478
 479         Method parameters:
 480         - query token, as previously returned by the .prepare method.
 481
 482         Returns: A string containing an SQL query..
 483 */
 484 int doSql( osrfMethodContext* ctx ) {
 485         if(osrfMethodVerifyContext( ctx )) {
 486                 osrfLogError( OSRF_LOG_MARK,  "Invalid method context" );
 487                 return -1;
 488         }
 489
 490         // Get the query token
 491         const jsonObject* token_obj = jsonObjectGetIndex( ctx->params, 0 );
 492         if( token_obj->type != JSON_STRING ) {
 493                 osrfAppSessionStatus( ctx->session, OSRF_STATUS_BADREQUEST, "osrfMethodException",
 494                         ctx->request, "Invalid parameter; query token must be a string" );
 495                 return -1;
 496         }
 497         const char* token = jsonObjectGetString( token_obj );
 498
 499         // Look up the query token in the session-level userData
 500         CachedQuery* query = search_token( ctx, token );
 501         if( !query ) {
 502                 osrfAppSessionStatus( ctx->session, OSRF_STATUS_BADREQUEST, "osrfMethodException",
 503                         ctx->request, "Invalid query token" );
 504                 return -1;
 505         }
 506
 507         osrfLogInfo( OSRF_LOG_MARK, "Returning SQL for token \"%s\"", token );
 508         if( query->state->error ) {
 509                 osrfLogWarning( OSRF_LOG_MARK, sqlAddMsg( query->state,
 510                         "No valid prepared query available for query id # %d", query->query->id ));
 511                 osrfAppSessionStatus( ctx->session, OSRF_STATUS_BADREQUEST, "osrfMethodException",
 512                         ctx->request, "No valid prepared query available" );
 513                 return -1;
 514         } else if( buildSQL( query->state, query->query )) {
 515                 osrfLogWarning( OSRF_LOG_MARK, sqlAddMsg( query->state,
 516                         "Unable to build SQL statement for query id # %d", query->query->id ));
 517                 osrfAppSessionStatus( ctx->session, OSRF_STATUS_BADREQUEST, "osrfMethodException",
 518                         ctx->request, "Unable to build SQL statement" );
 519                 return -1;
 520         }
 521
 522         osrfAppRespondComplete( ctx, jsonNewObject( OSRF_BUFFER_C_STR( query->state->sql )));
 523         return 0;
 524 }
 525
 526 /**
 527         @brief Return a list of previously generated error messages for a specified query.
 528         @param ctx Pointer to the current method context.
 529         @return Zero if successful, or -1 if not.
 530
 531         Method parameters:
 532         - query token, as previously returned by the .prepare method.
 533
 534         Returns: A (possibly empty) array of strings, each one an error message generated during
 535         previous operations in connection with the specified query.
 536 */
 537 int doMessages( osrfMethodContext* ctx ) {
 538         if(osrfMethodVerifyContext( ctx )) {
 539                 osrfLogError( OSRF_LOG_MARK,  "Invalid method context" );
 540                 return -1;
 541         }
 542
 543         // Get the query token from a method parameter
 544         const jsonObject* token_obj = jsonObjectGetIndex( ctx->params, 0 );
 545         if( token_obj->type != JSON_STRING ) {
 546                 osrfAppSessionStatus( ctx->session, OSRF_STATUS_BADREQUEST, "osrfMethodException",
 547                         ctx->request, "Invalid parameter; query token must be a string" );
 548                 return -1;
 549         }
 550         const char* token = jsonObjectGetString( token_obj );
 551
 552         // Look up the query token in the session-level userData
 553         CachedQuery* query = search_token( ctx, token );
 554         if( !query ) {
 555                 osrfAppSessionStatus( ctx->session, OSRF_STATUS_BADREQUEST, "osrfMethodException",
 556                         ctx->request, "Invalid query token" );
 557                 return -1;
 558         }
 559
 560         osrfLogInfo( OSRF_LOG_MARK, "Returning messages for token %s", token );
 561
 562         jsonObject* msgs = jsonNewObjectType( JSON_ARRAY );
 563         const osrfStringArray* error_msgs = query->state->error_msgs;
 564         int i;
 565         for( i = 0; i < error_msgs->size; ++i ) {
 566                 jsonObject* msg = jsonNewObject( osrfStringArrayGetString( error_msgs, i ));
 567                 jsonObjectPush( msgs, msg );
 568         }
 569
 570         osrfAppRespondComplete( ctx, msgs );
 571         return 0;
 572 }
 573
 574 /**
 575         @brief Discard a previously stored query, as identified by a token.
 576         @param ctx Pointer to the current method context.
 577         @return Zero if successful, or -1 if not.
 578
 579         Method parameters:
 580         - query token, as previously returned by the .prepare method.
 581
 582         Returns: Nothing.
 583 */
 584 int doFinish( osrfMethodContext* ctx ) {
 585         if(osrfMethodVerifyContext( ctx )) {
 586                 osrfLogError( OSRF_LOG_MARK,  "Invalid method context" );
 587                 return -1;
 588         }
 589
 590         // Get the query token.
 591         const jsonObject* token_obj = jsonObjectGetIndex( ctx->params, 0 );
 592         if( token_obj->type != JSON_STRING ) {
 593                 osrfAppSessionStatus( ctx->session, OSRF_STATUS_BADREQUEST, "osrfMethodException",
 594                                                           ctx->request, "Invalid parameter; query token must be a string" );
 595                 return -1;
 596         }
 597         const char* token = jsonObjectGetString( token_obj );
 598
 599         // Delete the corresponding entry from the cache.  If there is no cache, or no such entry,
 600         // just ignore the problem and report success.
 601         osrfHash* cache = ctx->session->userData;
 602         if( cache )
 603                 osrfHashRemove( cache, token );
 604
 605         osrfAppRespondComplete( ctx, NULL );
 606         return 0;
 607 }
 608
 609 /**
 610         @brief Save a query in session-level userData for reference in future method calls.
 611         @param ctx Pointer to the current method context.
 612         @param state Pointer to the state of the query.
 613         @param query Pointer to the abstract representation of the query.
 614         @return Pointer to an identifying token to be returned to the client.
 615 */
 616 static const char* save_query(
 617         osrfMethodContext* ctx, BuildSQLState* state, StoredQ* query ) {
 618
 619         CachedQuery* cached_query = safe_malloc( sizeof( CachedQuery ));
 620         cached_query->state       = state;
 621         cached_query->query       = query;
 622
 623         // Get the cache.  If we don't have one yet, make one.
 624         osrfHash* cache = ctx->session->userData;
 625         if( !cache ) {
 626                 cache = osrfNewHash();
 627                 osrfHashSetCallback( cache, free_cached_query );
 628                 ctx->session->userData = cache;
 629                 ctx->session->userDataFree = userDataFree;  // arrange to free it at end of session
 630         }
 631
 632         // Create a token string to be used as a key
 633         static unsigned int token_count = 0;
 634         char* token = va_list_to_string(
 635                 "%u_%ld_%ld", ++token_count, (long) time( NULL ), (long) getpid() );
 636
 637         osrfHashSet( cache, cached_query, token );
 638         return token;
 639 }
 640
 641 /**
 642         @brief Free a CachedQuery
 643         @param Pointer to the CachedQuery to be freed.
 644 */
 645 static void free_cached_query( char* key, void* data ) {
 646         if( data ) {
 647                 CachedQuery* cached_query = data;
 648                 buildSQLStateFree( cached_query->state );
 649                 storedQFree( cached_query->query );
 650         }
 651 }
 652
 653 /**
 654         @brief Callback for freeing session-level userData.
 655         @param blob Opaque pointer t userData.
 656 */
 657 static void userDataFree( void* blob ) {
 658         osrfHashFree( (osrfHash*) blob );
 659 }
 660
 661 /**
 662         @brief Search for the cached query corresponding to a given token.
 663         @param ctx Pointer to the current method context.
 664         @param token Token string from a previous call to the prepare method.
 665         @return A pointer to the cached query, if found, or NULL if not.
 666 */
 667 static CachedQuery* search_token( osrfMethodContext* ctx, const char* token ) {
 668         if( ctx && ctx->session->userData && token ) {
 669                 osrfHash* cache = ctx->session->userData;
 670                 return osrfHashGet( cache, token );
 671         } else
 672                 return NULL;
 673 }