mirror of https://gitee.com/bigwinds/arangodb
132 lines
4.9 KiB
Plaintext
132 lines
4.9 KiB
Plaintext
////////////////////////////////////////////////////////////////////////////////
|
|
/// @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
|
|
/// <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>
|
|
////////////////////////////////////////////////////////////////////////////////
|
|
|
|
////////////////////////////////////////////////////////////////////////////////
|
|
/// @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.
|
|
///
|
|
/// @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>
|
|
///
|
|
/// @anchor HttpCursorDelete
|
|
/// @copydetails JSF_DELETE_api_cursor
|
|
////////////////////////////////////////////////////////////////////////////////
|
|
|
|
// Local Variables:
|
|
// mode: c++
|
|
// mode: outline-minor
|
|
// outline-regexp: "^\\(/// @brief\\|/// {@inheritDoc}\\|/// @addtogroup\\|// --SECTION--\\|/// @page\\|/// @\\}\\)"
|
|
// End:
|