From 27883efbee62de37e035d510c5d22b78fbaae9fd Mon Sep 17 00:00:00 2001 From: Jan Steemann Date: Thu, 29 Nov 2012 10:44:14 +0100 Subject: [PATCH] updated documentation --- .../Examples/api-collection-bad-handle | 2 +- .../Examples/shell-read-document-bad-handle | 2 +- arangod/Documentation/api-collection.dox | 42 +++++++++++-------- arangod/Documentation/api-index.dox | 6 +-- arangod/Documentation/http-interface.dox | 13 +++--- arangod/Documentation/rest-document.dox | 4 +- arangod/Documentation/rest-edge.dox | 4 +- arangod/Documentation/shell-collection.dox | 22 ++++------ arangod/RestHandler/RestDocumentHandler.cpp | 26 ++++++------ arangod/RestHandler/RestEdgeHandler.cpp | 20 +++++---- arangod/RestHandler/RestImportHandler.cpp | 37 +++++++++++----- arangod/V8Server/v8-vocbase.cpp | 11 ++--- 12 files changed, 105 insertions(+), 84 deletions(-) diff --git a/Documentation/Examples/api-collection-bad-handle b/Documentation/Examples/api-collection-bad-handle index b049719f03..d54a0c6fc6 100644 --- a/Documentation/Examples/api-collection-bad-handle +++ b/Documentation/Examples/api-collection-bad-handle @@ -4,7 +4,7 @@ HTTP/1.1 400 Bad Request content-type: application/json { - "errorMessage": "expect GET /_api/collection/", + "errorMessage": "expected GET /_api/collection/", "errorNum": 400, "code": 400, "error": true diff --git a/Documentation/Examples/shell-read-document-bad-handle b/Documentation/Examples/shell-read-document-bad-handle index 52968e8537..f228fb18ad 100644 --- a/Documentation/Examples/shell-read-document-bad-handle +++ b/Documentation/Examples/shell-read-document-bad-handle @@ -1,5 +1,5 @@ arango> db.example.document("12345"); JavaScript exception in file '(arango)' at 1,12: - [ArangoError 10: bad parameter: must be a document identifier] + [ArangoError 10: bad parameter: must be a document identifier] !db.example.document("12345"); ! ^ diff --git a/arangod/Documentation/api-collection.dox b/arangod/Documentation/api-collection.dox index 6cf400c3b1..755eb441fd 100644 --- a/arangod/Documentation/api-collection.dox +++ b/arangod/Documentation/api-collection.dox @@ -48,26 +48,26 @@ ///
  • @ref HttpCollectionConstructor ///
      ///
    • @ref HttpCollectionCreate "POST /_api/collection"
      • -///
    • @ref HttpCollectionDelete "DELETE /_api/collection/collection-identifier"
      • -///
    • @ref HttpCollectionTruncate "PUT /_api/collection/collection-identifier/truncate"
      • +///
    • @ref HttpCollectionDelete "DELETE /_api/collection/collection-name"
      • +///
    • @ref HttpCollectionTruncate "PUT /_api/collection/collection-name/truncate"
      • ///
    ///
    • ///
  • @ref HttpCollectionReading ///
      -///
    • @ref HttpCollectionRead "GET /_api/collection/collection-identifier"
      • -///
    • @ref HttpCollectionRead "GET /_api/collection/collection-identifier/properties"
      • -///
    • @ref HttpCollectionRead "GET /_api/collection/collection-identifier/count"
      • -///
    • @ref HttpCollectionRead "GET /_api/collection/collection-identifier/figures"
      • -///
    • @ref HttpCollectionRead "GET /_api/collection/collection-identifier"
      • +///
    • @ref HttpCollectionRead "GET /_api/collection/collection-name"
      • +///
    • @ref HttpCollectionRead "GET /_api/collection/collection-name/properties"
      • +///
    • @ref HttpCollectionRead "GET /_api/collection/collection-name/count"
      • +///
    • @ref HttpCollectionRead "GET /_api/collection/collection-name/figures"
      • +///
    • @ref HttpCollectionRead "GET /_api/collection/collection-name"
      • ///
    • @ref HttpCollectionReadAll "GET /_api/collection/"
      • ///
    ///
    • ///
  • @ref HttpCollectionChanging ///
      -///
    • @ref HttpCollectionLoad "PUT /_api/collection/collection-identifier/load"
      • -///
    • @ref HttpCollectionUnload "PUT /_api/collection/collection-identifier/unload"
      • -///
    • @ref HttpCollectionProperties "PUT /_api/collection/collection-identifier/properties"
      • -///
    • @ref HttpCollectionRename "PUT /_api/collection/collection-identifier/rename"
      • +///
    • @ref HttpCollectionLoad "PUT /_api/collection/collection-name/load"
      • +///
    • @ref HttpCollectionUnload "PUT /_api/collection/collection-name/unload"
      • +///
    • @ref HttpCollectionProperties "PUT /_api/collection/collection-name/properties"
      • +///
    • @ref HttpCollectionRename "PUT /_api/collection/collection-name/rename"
      • ///
    ///
    • /// @@ -95,16 +95,22 @@ /// @section HttpCollectionResource Address of a Collection //////////////////////////////////////////////////////////// /// -/// All collections in ArangoDB have an unique identifier. This collection -/// identifier identifies a collection and is managed by ArangoDB. All -/// collections are found under the URI +/// All collections in ArangoDB have an unique identifier and +/// a unique name. ArangoDB internally uses the collection's unique +/// identifier to look up collections. This identifier however is +/// managed by ArangoDB and the user has no control over it. In +/// order to allow users use their own names, each collection also +/// has a unique name, which is specified by the user. +/// To access a collection from the user perspective, the +/// collection name should be used, i.e.: /// -/// @LIT{http://server:port/_api/collection/collection-identifier} +/// @LIT{http://server:port/_api/collection/collection-name} /// -/// For example: Assume that the collection identifier is @LIT{7254820}, -/// then the URL of that collection is: +/// For example: Assume that the collection identifier is @LIT{7254820} +/// and the collection name is @LIT{demo}, then the URL of that +/// collection is: /// -/// @LIT{http://localhost:8529/_api/collection/7254820} +/// @LIT{http://localhost:8529/_api/collection/demo} /// /// @section HttpCollectionHttp Working with Collections using HTTP /////////////////////////////////////////////////////////////////// diff --git a/arangod/Documentation/api-index.dox b/arangod/Documentation/api-index.dox index d1cdfb5444..43fec52921 100644 --- a/arangod/Documentation/api-index.dox +++ b/arangod/Documentation/api-index.dox @@ -46,7 +46,7 @@ /// ///
      ///
    • @ref HttpIndexRead "GET /_api/index/index-handle"
      • -///
    • @ref HttpIndexCreate "POST /_api/index?collection=collection-identifier"
      • +///
    • @ref HttpIndexCreate "POST /_api/index?collection=collection-name"
      • ///
    • @ref HttpIndexDelete "DELETE /_api/index/index-handle"
      • ///
    • @ref HttpIndexReadAll "GET /_api/index?collection=index-handle"
      • ///
    @@ -86,10 +86,10 @@ /// /// @LIT{http://server:port/_api/index/index-handle} /// -/// For example: Assume that the index handle is @LIT{7254820/63563528} then +/// For example: Assume that the index handle is @LIT{demo/63563528} then /// the URL of that index is: /// -/// @LIT{http://localhost:8529/_api/index/7254820/63563528} +/// @LIT{http://localhost:8529/_api/index/demo/63563528} /// /// @section HttpIndexHttp Working with Indexes using HTTP ////////////////////////////////////////////////////////// diff --git a/arangod/Documentation/http-interface.dox b/arangod/Documentation/http-interface.dox index b3cc899cc5..c571a028cc 100644 --- a/arangod/Documentation/http-interface.dox +++ b/arangod/Documentation/http-interface.dox @@ -35,17 +35,16 @@ /// Each resource has an identifier, which allows to access the given resource. /// /// - collection: -/// A collection can be referenced using the collection identifier or the -/// collection name. +/// A collection can be referenced using the collection name /// - document: -/// A document can be referenced using the collection identifier and the -/// document identifier. Alternativly you can use a document reference which -/// is a string of the form "collection-identifier:document-identifier". +/// A document can be referenced using the combination of the collection +/// name and the unique document key. Alternativly you can use a document +/// handle which is a string of the form "collection-name/document-key". /// - index: /// An index can be referenced using the index identifier. /// - revision: -/// Each document has a unique document identifier. However, it is possible -/// to update documents. In this case the document identifier stays the +/// Each document has a unique document key. However, it is possible +/// to update documents. In this case the document key stays the /// same. Each new revision of such a document gets a new revision number. /// - etag: /// A revision of a document has an etag. diff --git a/arangod/Documentation/rest-document.dox b/arangod/Documentation/rest-document.dox index fce5024053..3fc5a8c8ba 100644 --- a/arangod/Documentation/rest-document.dox +++ b/arangod/Documentation/rest-document.dox @@ -46,12 +46,12 @@ /// ///
      ///
    • @ref RestDocumentRead "GET /_api/document/document-handle"
      • -///
    • @ref RestDocumentCreate "POST /_api/document?collection=collection-identifier"
      • +///
    • @ref RestDocumentCreate "POST /_api/document?collection=collection-name"
      • ///
    • @ref RestDocumentReplace "PUT /_api/document/document-handle"
      • ///
    • @ref RestDocumentUpdate "PATCH /_api/document/document-handle"
      • ///
    • @ref RestDocumentDelete "DELETE /_api/document/document-handle"
      • ///
    • @ref RestDocumentHead "HEAD /_api/document/document-handle"
      • -///
    • @ref RestDocumentReadAll "GET /_api/document?collection=collection-identifier"
      • +///
    • @ref RestDocumentReadAll "GET /_api/document?collection=collection-name"
      • ///
    //////////////////////////////////////////////////////////////////////////////// diff --git a/arangod/Documentation/rest-edge.dox b/arangod/Documentation/rest-edge.dox index 18c8700963..329cb0ecb6 100644 --- a/arangod/Documentation/rest-edge.dox +++ b/arangod/Documentation/rest-edge.dox @@ -46,11 +46,11 @@ /// ///
      ///
    • @ref RestEdgeRead "GET /_api/edge/document-handle"
      • -///
    • @ref RestEdgeCreate "POST /_api/edge?collection=collection-identifier&from=from-handle&to=to-handle"
      • +///
    • @ref RestEdgeCreate "POST /_api/edge?collection=collection-name&from=from-handle&to=to-handle"
      • ///
    • @ref RestEdgeUpdate "PUT /_api/edge/document-handle"
      • ///
    • @ref RestEdgeDelete "DELETE /_api/edge/document-handle"
      • ///
    • @ref RestEdgeHead "HEAD /_api/edge/document-handle"
      • -///
    • @ref RestEdgeEdges "GET /_api/edges/collection-identifier?vertex=vertex-handle&directory=direction"
      • +///
    • @ref RestEdgeEdges "GET /_api/edges/collection-name?vertex=vertex-handle&directory=direction"
      • ///
    //////////////////////////////////////////////////////////////////////////////// diff --git a/arangod/Documentation/shell-collection.dox b/arangod/Documentation/shell-collection.dox index 8e4c9e3625..5c11ceb2f7 100644 --- a/arangod/Documentation/shell-collection.dox +++ b/arangod/Documentation/shell-collection.dox @@ -93,14 +93,14 @@ /// @section ShellCollectionResource Address of a Collection //////////////////////////////////////////////////////////// /// -/// All collections in ArangoDB have an unique identifier. This collection -/// identifier identifies a collection and is managed by ArangoDB. Each -/// collection, in addition, has a unique name. This name is managed by the -/// user. The interface allows you to access the collections as: -/// -/// @LIT{db._collection(@FA{collection-identifier})} -/// -/// or +/// All collections in ArangoDB have an unique identifier and +/// a unique name. ArangoDB internally uses the collection's unique +/// identifier to look up collections. This identifier however is +/// managed by ArangoDB and the user has no control over it. In +/// order to allow users use their own names, each collection also +/// has a unique name, which is specified by the user. +/// To access a collection from the user perspective, the +/// collection name should be used, i.e.: /// /// @LIT{db._collection(@FA{collection-name})} /// @@ -112,14 +112,10 @@ /// /// @LIT{db._collection("demo")} /// -/// or -/// -/// @LIT{db._collection(7254820)} -/// /// If no collection with such a name or identifier exists, then /// @LIT{null} is returned. /// -/// There is a short-cut +/// There is a short-cut that can be used for non-system collections: /// /// @LIT{db.@FA{collection-name}} /// diff --git a/arangod/RestHandler/RestDocumentHandler.cpp b/arangod/RestHandler/RestDocumentHandler.cpp index 283a2a4e24..4c957838d6 100644 --- a/arangod/RestHandler/RestDocumentHandler.cpp +++ b/arangod/RestHandler/RestDocumentHandler.cpp @@ -167,11 +167,11 @@ HttpHandler::status_e RestDocumentHandler::execute () { /// /// @RESTHEADER{POST /_api/document,creates a document} /// -/// @REST{POST /_api/document?collection=@FA{collection-identifier}} +/// @REST{POST /_api/document?collection=@FA{collection-name}} /// -/// Creates a new document in the collection identified by the -/// @FA{collection-identifier}. A JSON representation of the document must be -/// passed as the body of the POST request. +/// Creates a new document in the collection identified by @FA{collection-name}. +/// A JSON representation of the document must be passed as the body of the POST +/// request. /// /// If the document was created successfully, then a @LIT{HTTP 201} is returned /// and the "Location" header contains the path to the newly created @@ -196,8 +196,9 @@ HttpHandler::status_e RestDocumentHandler::execute () { /// synchronisation for collections that have a default @LIT{waitForSync} value /// of @LIT{true}. /// -/// If the @FA{collection-identifier} is unknown, then a @LIT{HTTP 404} is -/// returned and the body of the response contains an error document. +/// If the collection specified by @FA{collection-name} is unknown, then a +/// @LIT{HTTP 404} is returned and the body of the response contains an error +/// document. /// /// If the body does not contain a valid JSON representation of a document, /// then a @LIT{HTTP 400} is returned and the body of the response contains @@ -205,8 +206,7 @@ HttpHandler::status_e RestDocumentHandler::execute () { /// /// @REST{POST /_api/document?collection=@FA{collection-name}@LATEXBREAK&createCollection=@FA{create-flag}} /// -/// Instead of a @FA{collection-identifier}, a @FA{collection-name} can be -/// used. If @FA{create-flag} has a value of @LIT{true} or @LIT{yes}, then the +/// If @FA{create-flag} has a value of @LIT{true} or @LIT{yes}, then the /// collection is created if it does not yet exist. Other values for @FA{create-flag} /// will be ignored so the collection must be present for the operation to succeed. /// @@ -344,7 +344,7 @@ bool RestDocumentHandler::readDocument () { default: generateError(HttpResponse::BAD, TRI_ERROR_HTTP_SUPERFLUOUS_SUFFICES, - "expecting GET /_api/document/ or GET /_api/document?collection="); + "expecting GET /_api/document/ or GET /_api/document?collection="); return false; } } @@ -471,12 +471,10 @@ bool RestDocumentHandler::readSingleDocument (bool generateBody) { /// /// @RESTHEADER{GET /_api/document,reads all document} /// -/// @REST{GET /_api/document?collection=@FA{collection-identifier}} +/// @REST{GET /_api/document?collection=@FA{collection-name}} /// /// Returns a list of all URI for all documents from the collection identified -/// by @FA{collection-identifier}. -/// -/// Instead of a @FA{collection-identifier}, a collection name can be given. +/// by @FA{collection-name}. /// /// @EXAMPLES /// @@ -623,7 +621,7 @@ bool RestDocumentHandler::checkDocument () { /// /// For example, to conditionally replace a document based on a specific revision /// id, you the following request: -/// @REST{PUT /_api/document/@FA{collection-identifier}/@FA{document-identifier}?rev=@FA{etag}} +/// @REST{PUT /_api/document/@FA{document-handle}?rev=@FA{etag}} /// /// If a target revision id is provided in the request (e.g. via the @FA{etag} value /// in the @LIT{rev} URL parameter above), ArangoDB will check that diff --git a/arangod/RestHandler/RestEdgeHandler.cpp b/arangod/RestHandler/RestEdgeHandler.cpp index 953e294a15..906fe1286d 100644 --- a/arangod/RestHandler/RestEdgeHandler.cpp +++ b/arangod/RestHandler/RestEdgeHandler.cpp @@ -75,19 +75,25 @@ RestEdgeHandler::RestEdgeHandler (HttpRequest* request, TRI_vocbase_t* vocbase) /// /// @RESTHEADER{POST /_api/edge,creates an edge} /// -/// @REST{POST /_api/edge?collection=@FA{collection-identifier}&from=@FA{from-handle}&to=@FA{to-handle}} +/// @REST{POST /_api/edge?collection=@FA{collection-name}&from=@FA{from-handle}&to=@FA{to-handle}} /// -/// Creates a new edge in the collection identified by the -/// @FA{collection-identifier}. A JSON representation of the document must be -/// passed as the body of the POST request. The object handle of the start point -/// must be passed in @FA{from-handle}. The object handle of the end point must -/// be passed in @FA{to-handle}. +/// Creates a new edge in the collection identified by @FA{collection-name}. +/// A JSON representation of the edge document must be passed as the body of +/// the POST request. This JSON object may contain the edge's document key in +/// the @LIT{_key} attribute if needed. It may also contain the boolean +/// @LIT{_bidirectional} attribute. +/// The document handle of the start point must be passed in @FA{from-handle}. +/// The document handle of the end point must be passed in @FA{to-handle}. +/// +/// @LIT{from-handle} and @{to-handle} are immutable once the edge has been +/// created. /// /// In all other respects the method works like @LIT{POST /document}, see /// @ref RestDocument for details. /// /// If you request such an edge, the returned document will also contain the -/// attributes @LIT{_from} and @LIT{_to}. +/// attributes @LIT{_bidirectional} and either @LIT{_vertices} or +/// @LIT{_from} and @LIT{_to}. /// /// @EXAMPLES /// diff --git a/arangod/RestHandler/RestImportHandler.cpp b/arangod/RestHandler/RestImportHandler.cpp index 0c1e901e83..98e979eea9 100644 --- a/arangod/RestHandler/RestImportHandler.cpp +++ b/arangod/RestHandler/RestImportHandler.cpp @@ -161,13 +161,13 @@ HttpHandler::status_e RestImportHandler::execute () { //////////////////////////////////////////////////////////////////////////////// /// @brief creates documents /// -/// @REST{POST /_api/import?type=documents&collection=@FA{collection-identifier}} +/// @REST{POST /_api/import?type=documents&collection=@FA{collection-name}} /// -/// Creates documents in the collection identified by the -/// @FA{collection-identifier}. The JSON representations of the documents must -/// be passed as the body of the POST request. +/// Creates documents in the collection identified by @FA{collection-name}. +/// The JSON representations of the documents must be passed as the body of the +/// POST request. /// -/// If the document was created successfully, then a @LIT{HTTP 201} is returned. +/// If the documents were created successfully, then a @LIT{HTTP 201} is returned. //////////////////////////////////////////////////////////////////////////////// bool RestImportHandler::createByArray () { @@ -278,13 +278,13 @@ bool RestImportHandler::createByArray () { //////////////////////////////////////////////////////////////////////////////// /// @brief creates documents /// -/// @REST{POST /_api/import?collection=@FA{collection-identifier}} +/// @REST{POST /_api/import?collection=@FA{collection-name}} /// -/// Creates documents in the collection identified by the -/// @FA{collection-identifier}. The JSON representations of the documents must -/// be passed as the body of the POST request. +/// Creates documents in the collection identified by @FA{collection-name}. +/// The JSON representations of the documents must be passed as the body of the +/// POST request. /// -/// If the document was created successfully, then a @LIT{HTTP 201} is returned. +/// If the documents were created successfully, then a @LIT{HTTP 201} is returned. //////////////////////////////////////////////////////////////////////////////// bool RestImportHandler::createByList () { @@ -460,6 +460,9 @@ bool RestImportHandler::createByList () { return true; } +//////////////////////////////////////////////////////////////////////////////// +/// @brief create response for number of documents created / failed +//////////////////////////////////////////////////////////////////////////////// void RestImportHandler::generateDocumentsCreated (size_t numCreated, size_t numError, size_t numEmpty) { _response = createResponse(HttpResponse::CREATED); @@ -475,6 +478,10 @@ void RestImportHandler::generateDocumentsCreated (size_t numCreated, size_t numE .appendText("}"); } +//////////////////////////////////////////////////////////////////////////////// +/// @brief parse a single document line +//////////////////////////////////////////////////////////////////////////////// + TRI_json_t* RestImportHandler::parseJsonLine (const string& line) { char* errmsg = 0; TRI_json_t* json = TRI_Json2String(TRI_UNKNOWN_MEM_ZONE, line.c_str(), &errmsg); @@ -486,6 +493,10 @@ TRI_json_t* RestImportHandler::parseJsonLine (const string& line) { return json; } +//////////////////////////////////////////////////////////////////////////////// +/// @brief create a JSON object from a line containing a document +//////////////////////////////////////////////////////////////////////////////// + TRI_json_t* RestImportHandler::createJsonObject (TRI_json_t* keys, TRI_json_t* values, const string& line) { if (values->_type != TRI_JSON_LIST) { @@ -519,12 +530,16 @@ TRI_json_t* RestImportHandler::createJsonObject (TRI_json_t* keys, TRI_json_t* v return result; } +//////////////////////////////////////////////////////////////////////////////// +/// @brief validate keys +//////////////////////////////////////////////////////////////////////////////// + bool RestImportHandler::checkKeys (TRI_json_t* keys) { if (keys->_type != TRI_JSON_LIST) { return false; } - size_t n = keys->_value._objects._length; + const size_t n = keys->_value._objects._length; if (n == 0) { return false; diff --git a/arangod/V8Server/v8-vocbase.cpp b/arangod/V8Server/v8-vocbase.cpp index 14cb295264..d3e6166d53 100755 --- a/arangod/V8Server/v8-vocbase.cpp +++ b/arangod/V8Server/v8-vocbase.cpp @@ -4892,16 +4892,17 @@ static v8::Handle MapGetVocBase (v8::Local name, //////////////////////////////////////////////////////////////////////////////// /// @brief returns a single collection or null /// -/// @FUN{db._collection(@FA{collection-identifier})} -/// -/// Returns the collection with the given identifier or null if no such -/// collection exists. -/// /// @FUN{db._collection(@FA{collection-name})} /// /// Returns the collection with the given name or null if no such collection /// exists. /// +/// @FUN{db._collection(@FA{collection-identifier})} +/// +/// Returns the collection with the given identifier or null if no such +/// collection exists. Accessing collections by identifier is discouraged for +/// end users. End users should access collections using the collection name. +/// /// @EXAMPLES /// /// Get a collection by name: