////////////////////////////////////////////////////////////////////////////////
/// @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: