////////////////////////////////////////////////////////////////////////////////
/// @brief over the wire protocol
///
/// @file
///
/// DISCLAIMER
///
/// Copyright 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 HttpCursorTOC
///
/// <ol>
///  <li>@ref HttpCursorResults
///   <ol>
///    <li>@ref HttpCursorResultsSingle</li>
///    <li>@ref HttpCursorResultsCursor</li>
///   </ol>
///  </li>
///  <li>@ref HttpCursorHttp
///   @copydetails HttpCursorCallsTOC
///  </li>
/// </ol>
////////////////////////////////////////////////////////////////////////////////

////////////////////////////////////////////////////////////////////////////////
/// @page HttpCursorCallsTOC
///
/// <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>
////////////////////////////////////////////////////////////////////////////////

////////////////////////////////////////////////////////////////////////////////
/// @page HttpCursor HTTP Interface for Cursors
///
/// This is an introduction to AvocadoDB's Http interface for Queries. Results
/// of AQL and simple queries are returned as cursors in order to batch the
/// communication between server and client. Each call returns a number of
/// documents in a batch and an indication, if these was the last
/// batch. Depending on the query the total number of documents in the result
/// might or might not be known. In order to free server resources the client
/// should delete the cursor as soon as it is no longer needed.
///
/// <hr>
/// @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.
///
/// @EXAMPLES
///
/// @verbinclude api-cursor-create-for-limit-return-single
///
/// @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 identifier will also be returned to the client. The server will put
/// the cursor identifier 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
///
/// Create and extract first batch:
///
/// @verbinclude api-cursor-create-for-limit-return
///
/// Extract next batch, still have more:
///
/// @verbinclude api-cursor-create-for-limit-return-cont
///
/// Extract next batch, done:
///
/// @verbinclude api-cursor-create-for-limit-return-cont2
///
/// Do not do this:
///
/// @verbinclude api-cursor-create-for-limit-return-cont3
///
/// @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>
///
/// @anchor HttpCursorDelete
/// @copydetails JSF_DELETE_api_cursor
////////////////////////////////////////////////////////////////////////////////

// Local Variables:
// mode: c++
// mode: outline-minor
// outline-regexp: "^\\(/// @brief\\|/// {@inheritDoc}\\|/// @addtogroup\\|// --SECTION--\\|/// @page\\|/// @\\}\\)"
// End: