1
0
Fork 0
This commit is contained in:
Frank Celler 2012-05-02 10:34:04 +02:00
parent c7478b4c88
commit b07ea9445e
7 changed files with 208 additions and 218 deletions

View File

@ -340,6 +340,7 @@ DOXYGEN = \
Doxygen/js/actions/system/api-cursor.c \
Doxygen/js/actions/system/api-edges.c \
Doxygen/js/actions/system/api-index.c \
Doxygen/js/actions/system/api-query.c \
Doxygen/js/actions/system/api-simple.c \
Doxygen/js/actions/system/api-system.c \
Doxygen/js/common/bootstrap/modules.c \

View File

@ -929,12 +929,14 @@ DOXYGEN = \
Doxygen/js/actions/system/api-cursor.c \
Doxygen/js/actions/system/api-edges.c \
Doxygen/js/actions/system/api-index.c \
Doxygen/js/actions/system/api-query.c \
Doxygen/js/actions/system/api-simple.c \
Doxygen/js/actions/system/api-system.c \
Doxygen/js/common/bootstrap/modules.c \
Doxygen/js/common/bootstrap/print.c \
Doxygen/js/common/modules/graph.c \
Doxygen/js/common/modules/jsunity.c \
Doxygen/js/common/modules/simple-query-basics.c \
Doxygen/js/server/modules/actions.c \
Doxygen/js/server/modules/simple-query.c \
Doxygen/js/server/server.c

View File

@ -21,7 +21,7 @@
///
/// Copyright holder is triAGENS GmbH, Cologne, Germany
///
/// @author Dr. Frank Celler
/// @author Jan Steemann
/// @author Copyright 2012, triAGENS GmbH, Cologne, Germany
////////////////////////////////////////////////////////////////////////////////
@ -29,8 +29,20 @@
/// @page HttpCursorTOC
///
/// <ol>
/// <li>@ref HttpCursorPut "PUT /_api/cursor/cursor-identifier"</li>
/// <li>@ref HttpCursorDelete "DELETE /_api/cursor/cursor-identifier"</li>
/// <li>@ref HttpCursorResults
/// <ol>
/// <li>@ref HttpCursorResultsSingle</li>
/// <li>@ref HttpCursorResultsCursor</li>
/// </ol>
/// </li>
/// <li>@ref HttpCursorHttp
/// <ol>
/// <li>@ref HttpCursorPost "POST /_api/cursor"</li>
/// <li>@ref HttpCursorPostQuery "POST /_api/query"</li>
/// <li>@ref HttpCursorPut "PUT /_api/cursor/cursor-identifier"</li>
/// <li>@ref HttpCursorDelete "DELETE /_api/cursor/cursor-identifier"</li>
/// </ol>
/// </li>
/// </ol>
////////////////////////////////////////////////////////////////////////////////
@ -49,6 +61,61 @@
/// @copydoc HttpCursorTOC
/// <hr>
///
/// To run a select query, the query details need to be shipped from the client
/// to the server via a HTTP POST request.
///
/// @section HttpCursorResults Retrieving query results
///////////////////////////////////////////////////////
///
/// Select queries are executed on-the-fly on the server and the result set will
/// be returned back to the client.
///
/// There are two ways the client can get the result set from the server:
///
/// - in a single roundtrip
///
/// - using a cursor
///
/// @subsection HttpCursorResultsSingle Single roundtrip
////////////////////////////////////////////////////////
///
/// The server will only transfer a certain number of result documents back to
/// the client in one roundtrip. This number is controllable by the client by
/// setting the @LIT{batchSize} attribute when issueing the query.
///
/// If the complete result can be transferred to the client in one go, the client
/// does not need to issue any further request. The client can check whether
/// it has retrieved the complete result set by checking the @LIT{hasMore}
/// attribute of the result set. If it is set to false, then the client has
/// fetched the complete result set from the server.
///
/// @subsection HttpCursorResultsCursor Using a Cursor
//////////////////////////////////////////////////////
///
/// If the result set contains more documents than should be transferred in a
/// single roundtrip (i.e. as set via the @LIT{batchSize} attribute), the server
/// will return the first few documents and create a temporary cursor. The
/// cursor id will also be returned to the client. The server will put the
/// cursor id in the @LIT{id} attribute of the response object. Furthermore,
/// the @LIT{hasMore} attribute of the response object will be set to
/// @LIT{true}. This is an indication for the client that there are additional
/// results to fetch from the server.
///
/// @EXAMPLES
///
/// @verbinclude cursorput1
///
/// @section HttpCursorHttp Accessing Cursors via Http
//////////////////////////////////////////////////////
///
/// @anchor HttpCursorPost
/// @copydetails JSF_POST_api_cursor
/// <hr>
///
/// @anchor HttpCursorPostQuery
/// @copydetails JSF_POST_api_query
/// <hr>
///
/// @anchor HttpCursorPut
/// @copydetails JSF_PUT_api_cursor
/// <hr>

View File

@ -1,202 +0,0 @@
////////////////////////////////////////////////////////////////////////////////
/// @brief statements and cursors
///
/// @file
///
/// DISCLAIMER
///
/// Copyright 2010-2012 triagens GmbH, Cologne, Germany
///
/// Licensed under the Apache License, Version 2.0 (the "License");
/// you may not use this file except in compliance with the License.
/// You may obtain a copy of the License at
///
/// http://www.apache.org/licenses/LICENSE-2.0
///
/// Unless required by applicable law or agreed to in writing, software
/// distributed under the License is distributed on an "AS IS" BASIS,
/// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
/// See the License for the specific language governing permissions and
/// limitations under the License.
///
/// Copyright holder is triAGENS GmbH, Cologne, Germany
///
/// @author Jan Steemann
/// @author Copyright 2012, triagens GmbH, Cologne, Germany
////////////////////////////////////////////////////////////////////////////////
////////////////////////////////////////////////////////////////////////////////
/// @page RestCursor REST Interface for select queries and cursors
///
/// @section RestCursorExecute Executing a query
///
/// To run a select query, the query details need to be shipped from the client
/// to the server via a HTTP POST request.
///
/// @anchor RestCursorPost
/// @REST{POST /_api/cursor}
///
/// The query details include the query string plus optional query options and
/// bind parameters. These values need to be passed in a JSON representation
/// in the body of the POST request.
///
/// The following attributes can be used inside the JSON object:
/// - query: contains the query string to be executed (mandatory)
/// - count: boolean flag that indicates whether the number of documents
/// found should be returned as "count" attribute in the result set
/// (optional).
/// Calculating the "count" attribute might have a performance penalty for
/// some queries so this option is turned off by default.
/// - batchSize: maximum number of result documents to be transferred from
/// the server to the client in one roundtrip (optional). If this attribute
/// is not set, a server-controlled default value will be used.
/// - bindVars: key/value list of bind parameters (optional).
///
/// @verbinclude cursor
///
/// If the JSON representation is malformed or the query specification is missing
/// from the request, the server will respond with @LIT{HTTP 400} or @LIT{HTTP 404}.
///
/// @verbinclude cursor4001
///
/// @verbinclude cursor4002
///
/// The body of the response will contain a JSON object with additional error
/// details. The object has the following attributes:
/// - error: boolean flag to indicate that an error occurred (true in this case)
/// - code: the HTTP status code
/// - errorNum: the server error number
/// - errorMessage: a descriptive error message
///
/// If the query specification is complete, the server will process the query. If an
/// error occurs during query processing, the server will respond with @LIT{HTTP 404}.
/// Again, the body of the response will contain details about the error.
///
/// @verbinclude cursor404
///
/// A list of query errors can be found @ref AvocadoErrors here.
///
/// If the result set can be created by the server, the server will respond with
/// @LIT{HTTP 201}. The body of the response will contain a JSON object with the
/// result set.
///
/// The JSON object has the following properties:
/// - error: boolean flag to indicate that an error occurred (false in this case)
/// - code: the HTTP status code
/// - result: an array of result documents (might be empty if query has no results)
/// - hasMore: a boolean indicator whether there are more results available on the
/// server
/// - count: the total number of result documents available (only available if the
/// query was executed with the @LIT{count} attribute set.
/// - _id: id of temporary cursor created on the server (optional, see below)
///
/// @verbinclude cursor201
///
/// @section RestCursorResults Retrieving query results
///
/// Select queries are executed on-the-fly on the server and the result set will
/// be returned back to the client.
///
/// There are two ways the client can get the result set from the server:
/// - in a single roundtrip
/// - using a cursor
///
/// @subsection RestCursorResultsSingle Single roundtrip
///
/// The server will only transfer a certain number of result documents back to
/// the client in one roundtrip. This number is controllable by the client by
/// setting the @LIT{batchSize} attribute when issueing the query.
///
/// If the complete result can be transferred to the client in one go, the client
/// does not need to issue any further request. The client can check whether
/// it has retrieved the complete result set by checking the @LIT{hasMore}
/// attribute of the result set. If it is set to false, then the client has
/// fetched the complete result set from the server.
///
/// @subsection RestCursorResultsCursor Using a Cursor
///
/// If the result set contains more documents than should be transferred in a
/// single roundtrip (i.e. as set via the @LIT{batchSize} attribute), the
/// server will return the first few documents and create a temporary cursor.
/// The cursor id will also be returned to the client. The server will put
/// the cursor id in the @LIT{_id} attribute of the response object.
/// Furthermore, the @LIT{hasMore} attribute of the response object will be
/// set to @LIT{true}. This is an indication for the client that there are
/// additional results to fetch from the server.
///
/// @verbinclude cursorput1
///
/// @anchor RestCursorPut
/// @REST{PUT /_api/cursor/@FA{cursor-identifier}}
///
/// In this case, the client can use the cursor id to subsequently fetch the
/// remaining result documents from the server until there are no more documents
/// available. This is done by the client issueing additional HTTP PUT requests.
///
/// @verbinclude cursorput2
///
/// The server will respond with @LIT{HTTP 200} in case of success. If the
/// cursor id is ommitted or somehow invalid, the server will respond with
/// @LIT{HTTP 404}.
///
/// @verbinclude cursorputfail
///
/// Once the @LIT{hasMore} attribute has a value of @LIT{false}, the client can
/// stop.
///
/// @verbinclude cursorput3
///
/// @anchor RestCursorDelete
/// @REST{DELETE /_api/cursor/@FA{cursor-identifier}}
///
/// The cursor will be destroyed on the server when the client has retrieved
/// all documents from it. The client can also explicitly destroy the cursor
/// at any earlier time using an HTTP DELETE request. The cursor id must be
/// included as part of the URL.
///
/// @verbinclude cursordelete
///
/// In case the server is aware of the cursor, it will respond with
/// @LIT{HTTP 202}. Otherwise, it will respond with @LIT{404}.
///
/// Cursors that have been explicitly destroyed must not be used afterwards. If
/// a cursor is used after it has been destroyed, the server will respond with
/// @LIT{HTTP 404} as well.
///
/// @verbinclude cursordeletefail
///
/// Note: the server will also destroy abandoned cursors automatically after a
/// certain server-controlled timeout to avoid resource leakage.
///
/// @section RestQueryValidate Validating a query
///
/// To validate a query string without executing it, the query string can be
/// passed to the server via an HTTP POST request.
///
/// @anchor RestQueryPost
/// @REST{POST /_api/query}
///
/// These query string needs to be passed in the attribute @LIT{query} of a
/// JSON object as the body of the POST request.
///
/// The server will respond with @LIT{HTTP 400} or @LIT{HTTP 500} in case of a
/// malformed request or a general error.
/// If the query contains a parse error, the server will respond with an
/// @LIT{HTTP 404} error.
///
/// The body of the response will contain the error details embedded in a JSON
/// object.
///
/// @verbinclude querypostfail
///
/// If the query is valid, the server will respond with @LIT{HTTP 200} and return
/// the names of the bind parameters it found in the query (if any) in the
/// @LIT{"bindVars"} attribute of the response.
///
/// @verbinclude querypost
////////////////////////////////////////////////////////////////////////////////
// Local Variables:
// mode: outline-minor
// outline-regexp: "^\\(/// @brief\\|/// {@inheritDoc}\\|/// @addtogroup\\|// --SECTION--\\|/// @\\}\\)"
// End:

View File

@ -42,14 +42,6 @@
/// <li>@ref OTWPSimpleQueriesWithin "PUT /_api/simple/within"</li>
/// </ol>
/// </li>
/// <li>Queries and Cursors
/// <ol>
/// <li>@ref RestCursorPost "POST /_api/cursor"</li>
/// <li>@ref RestCursorPut "PUT /_api/cursor/@FA{cursor-identifier}"</li>
/// <li>@ref RestCursorDelete "DELETE /_api/cursor/@FA{cursor-identifier}"</li>
/// <li>@ref RestQueryPost "POST /_api/query"</li>
/// </ol>
/// </li>
/// <li>@ref Key-Value
/// <ol>
/// <li>@ref Key-ValuePost "POST /_api/key/@FA{collection-name}/@FA{key}"</li>

View File

@ -80,6 +80,84 @@ function getCursorResult (cursor) {
////////////////////////////////////////////////////////////////////////////////
/// @brief create a cursor and return the first results
///
/// @REST{POST /_api/cursor}
///
/// The query details include the query string plus optional query options and
/// bind parameters. These values need to be passed in a JSON representation in
/// the body of the POST request.
///
/// The following attributes can be used inside the JSON object:
///
/// - @LIT{query}: contains the query string to be executed (mandatory)
///
/// - @LIT{count}: boolean flag that indicates whether the number of documents
/// found should be returned as "count" attribute in the result set (optional).
/// Calculating the "count" attribute might have a performance penalty for
/// some queries so this option is turned off by default.
///
/// - @LIT{batchSize}: maximum number of result documents to be transferred from
/// the server to the client in one roundtrip (optional). If this attribute is
/// not set, a server-controlled default value will be used.
///
/// - @LIT{bindVars}: key/value list of bind parameters (optional).
///
/// If the result set can be created by the server, the server will respond with
/// @LIT{HTTP 201}. The body of the response will contain a JSON object with the
/// result set.
///
/// The JSON object has the following properties:
///
/// - @LIT{error}: boolean flag to indicate that an error occurred (@LIT{false}
/// in this case)
///
/// - @LIT{code}: the HTTP status code
///
/// - @LIT{result}: an array of result documents (might be empty if query has no results)
///
/// - @LIT{hasMore}: a boolean indicator whether there are more results
/// available on the server
///
/// - @LIT{count}: the total number of result documents available (only
/// available if the query was executed with the @LIT{count} attribute set.
///
/// - @LIT{id}: id of temporary cursor created on the server (optional, see below)
///
/// If the JSON representation is malformed or the query specification is
/// missing from the request, the server will respond with @LIT{HTTP 400}.
///
/// The body of the response will contain a JSON object with additional error
/// details. The object has the following attributes:
///
/// - @LIT{error}: boolean flag to indicate that an error occurred (@LIT{true} in this case)
///
/// - @LIT{code}: the HTTP status code
///
/// - @LIT{errorNum}: the server error number
///
/// - @LIT{errorMessage}: a descriptive error message
///
/// If the query specification is complete, the server will process the query. If an
/// error occurs during query processing, the server will respond with @LIT{HTTP 400}.
/// Again, the body of the response will contain details about the error.
///
/// A list of query errors can be found @ref AvocadoErrors here.
///
/// @EXAMPLES
///
/// @verbinclude cursor
///
/// Bad queries:
///
/// @verbinclude cursor4001
///
/// @verbinclude cursor4002
///
/// @verbinclude cursor404
///
/// Valid query:
///
/// @verbinclude cursor201
////////////////////////////////////////////////////////////////////////////////
function POST_api_cursor(req, res) {
@ -139,9 +217,18 @@ function POST_api_cursor(req, res) {
///
/// Note that even if @LIT{hasMore} returns @LIT{true}, the next call might
/// still return no documents. If, however, @LIT{hasMore} is @LIT{false}, then
/// the cursor is exhausted.
/// the cursor is exhausted. Once the @LIT{hasMore} attribute has a value of
/// @LIT{false}, the client can stop.
///
/// An @LIT{HTTP 404} is returned if the cursor no longer exists.
/// The server will respond with @LIT{HTTP 200} in case of success. If the
/// cursor id is ommitted or somehow invalid, the server will respond with
/// @LIT{HTTP 404}.
///
/// @EXAMPLES
///
/// @verbinclude cursorputfail
///
/// @verbinclude cursorput3
////////////////////////////////////////////////////////////////////////////////
function PUT_api_cursor(req, res) {
@ -172,7 +259,26 @@ function PUT_api_cursor(req, res) {
///
/// @REST{DELETE /_api/cursor/@FA{cursor-identifier}}
///
/// Deletes the cursor and frees the resources associated with it.
/// Deletes the cursor and frees the resources associated with it.
///
/// The cursor will automatically be destroyed on the server when the client has
/// retrieved all documents from it. The client can also explicitly destroy the
/// cursor at any earlier time using an HTTP DELETE request. The cursor id must
/// be included as part of the URL.
///
/// In case the server is aware of the cursor, it will respond with @LIT{HTTP
/// 202}. Otherwise, it will respond with @LIT{404}.
///
/// Cursors that have been explicitly destroyed must not be used afterwards. If
/// a cursor is used after it has been destroyed, the server will respond with
/// @LIT{HTTP 404} as well.
///
/// Note: the server will also destroy abandoned cursors automatically after a
/// certain server-controlled timeout to avoid resource leakage.
///
/// @EXAMPLES
///
/// @verbinclude cursordeletefail
////////////////////////////////////////////////////////////////////////////////
function DELETE_api_cursor(req, res) {

View File

@ -38,9 +38,33 @@ var actions = require("actions");
////////////////////////////////////////////////////////////////////////////////
/// @brief parse a query and return information about it
///
/// @REST{POST /_api/query}
///
/// To validate a query string without executing it, the query string can be
/// passed to the server via an HTTP POST request.
///
/// These query string needs to be passed in the attribute @LIT{query} of a
/// JSON object as the body of the POST request.
///
/// The server will respond with @LIT{HTTP 400} or @LIT{HTTP 500} in case of a
/// malformed request or a general error.
/// If the query contains a parse error, the server will respond with an
/// @LIT{HTTP 404} error.
///
/// The body of the response will contain the error details embedded in a JSON
/// object.
///
/// @verbinclude querypostfail
///
/// If the query is valid, the server will respond with @LIT{HTTP 200} and return
/// the names of the bind parameters it found in the query (if any) in the
/// @LIT{"bindVars"} attribute of the response.
///
/// @verbinclude querypost
////////////////////////////////////////////////////////////////////////////////
function postQuery(req, res) {
function POST_api_query (req, res) {
if (req.suffix.length != 0) {
actions.resultNotFound(req, res, actions.ERROR_HTTP_NOT_FOUND);
return;
@ -84,7 +108,7 @@ actions.defineHttp({
callback : function (req, res) {
switch (req.requestType) {
case (actions.POST) :
postQuery(req, res);
POST_api_query(req, res);
break;
default: