[open-ils-commits] r16653 - trunk/Open-ILS/src/c-apps (scottmk)

[svn at svn.open-ils.org]

Author: scottmk
Date: 2010-06-10 12:28:50 -0400 (Thu, 10 Jun 2010)
New Revision: 16653

Modified:
   trunk/Open-ILS/src/c-apps/oils_qstore.c
Log:
Change the return type of the open-ils.qstore.prepare method.

Formerly, this method merely returned a string to be used as 
token for future references to the query.

Now it returns an object, with the following elements:

"token" -- the query token as returned formerly
"bind_variables" -- a (possibly empty) object containing a
list of bind variables and their various attributes, as
returned by the param_list method.

Rationale: an interactive query-building client will always
want a list of bind variables so that it can prompt the user
for values.  With this change to the return type, the client
can get such a list without having to make a separate call
to the param_list method.

M    Open-ILS/src/c-apps/oils_qstore.c


Modified: trunk/Open-ILS/src/c-apps/oils_qstore.c
===================================================================
--- trunk/Open-ILS/src/c-apps/oils_qstore.c	2010-06-10 16:12:16 UTC (rev 16652)
+++ trunk/Open-ILS/src/c-apps/oils_qstore.c	2010-06-10 16:28:50 UTC (rev 16653)
@@ -169,10 +169,9 @@
 	Method parameters:
 	- query id (key of query.stored_query table)
 
-	Returns: a character string serving as a token for future references to the query.
-
-	NB: the method return type is temporary.  Eventually this method will return both a token
-	and a list of bind variables.
+	Returns: a hash with two entries:
+	- "token": A character string serving as a token for future references to the query.
+	- "bind_variables" A hash of bind variables; see notes for doParamList().
 */
 int doPrepare( osrfMethodContext* ctx ) {
 	if(osrfMethodVerifyContext( ctx )) {
@@ -212,7 +211,14 @@
 
 	osrfLogInfo( OSRF_LOG_MARK, "Token for query id # %d is \"%s\"", query_id, token );
 
-	osrfAppRespondComplete( ctx, jsonNewObject( token ));
+	// Build an object to return: a hash containing the query token
+	// and a list of bind variables.
+	jsonObject* returned_obj = jsonNewObjectType( JSON_HASH );
+	jsonObjectSetKey( returned_obj, "token", jsonNewObject( token ));
+	jsonObjectSetKey( returned_obj, "bind_variables",
+		oilsBindVarList( state->bindvar_list ));
+
+	osrfAppRespondComplete( ctx, returned_obj );
 	return 0;
 }
 
@@ -250,7 +256,7 @@
 	}
 
 	osrfLogInfo( OSRF_LOG_MARK, "Listing column names for token %s", token );
-	
+
 	jsonObject* col_list = oilsGetColNames( query->state, query->query );
 	if( query->state->error ) {
 		osrfAppSessionStatus( ctx->session, OSRF_STATUS_BADREQUEST, "osrfMethodException",
@@ -262,6 +268,27 @@
 	}
 }
 
+/**
+	@brief Implement the param_list method.
+	@param ctx Pointer to the current method context.
+	@return Zero if successful, or -1 if not.
+
+	Provide a list of bind variables for a specified query, along with their various
+	attributes.
+
+	Method parameters:
+	- query token, as previously returned by the .prepare method.
+
+	Returns: A (possibly empty) JSON_HASH, keyed on the names of the bind variables.
+	The data for each is another level of JSON_HASH with a fixed set of tags:
+	- "label"
+	- "type"
+	- "description"
+	- "default_value" (as a jsonObject)
+	- "actual_value" (as a jsonObject)
+
+	Any non-existent values are represented as JSON_NULLs.
+*/
 int doParamList( osrfMethodContext* ctx ) {
 	if(osrfMethodVerifyContext( ctx )) {
 		osrfLogError( OSRF_LOG_MARK,  "Invalid method context" );
@@ -296,6 +323,8 @@
 	@param ctx Pointer to the current method context.
 	@return Zero if successful, or -1 if not.
 
+	Apply values to bind variables, overriding the defaults, if any.
+
 	Method parameters:
 	- query token, as previously returned by the .prepare method.
 	- hash of bind variable values, keyed on bind variable names.