Hawkin
/
arangodb
mirror of https://gitee.com/bigwinds/arangodb
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

updated documentation

This commit is contained in:
Jan Steemann 2012-11-29 10:44:14 +01:00
parent 77f3115ac7
commit 27883efbee
12 changed files with 105 additions and 84 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
Documentation/Examples/api-collection-bad-handle
View File

@ -4,7 +4,7 @@ HTTP/1.1 400 Bad Request
content-type: application/json
{
"errorMessage": "expect GET /_api/collection/<collection-identifer>",
"errorMessage": "expected GET /_api/collection/<collection-name>",
"errorNum": 400,
"code": 400,
"error": true

2
Documentation/Examples/shell-read-document-bad-handle
View File

@ -1,5 +1,5 @@
arango> db.example.document("12345");
JavaScript exception in file '(arango)' at 1,12:
[ArangoError 10: bad parameter: <document-idenifier> must be a document identifier]
[ArangoError 10: bad parameter: <document-identifier> must be a document identifier]
!db.example.document("12345");
! ^

42
arangod/Documentation/api-collection.dox
View File

@ -48,26 +48,26 @@
/// <li>@ref HttpCollectionConstructor
/// <ul>
/// <li>@ref HttpCollectionCreate "POST /_api/collection"</li>
/// <li>@ref HttpCollectionDelete "DELETE /_api/collection/collection-identifier"</li>
/// <li>@ref HttpCollectionTruncate "PUT /_api/collection/collection-identifier/truncate"</li>
/// <li>@ref HttpCollectionDelete "DELETE /_api/collection/collection-name"</li>
/// <li>@ref HttpCollectionTruncate "PUT /_api/collection/collection-name/truncate"</li>
/// </ul>
/// </li>
/// <li>@ref HttpCollectionReading
/// <ul>
/// <li>@ref HttpCollectionRead "GET /_api/collection/collection-identifier"</li>
/// <li>@ref HttpCollectionRead "GET /_api/collection/collection-identifier/properties"</li>
/// <li>@ref HttpCollectionRead "GET /_api/collection/collection-identifier/count"</li>
/// <li>@ref HttpCollectionRead "GET /_api/collection/collection-identifier/figures"</li>
/// <li>@ref HttpCollectionRead "GET /_api/collection/collection-identifier"</li>
/// <li>@ref HttpCollectionRead "GET /_api/collection/collection-name"</li>
/// <li>@ref HttpCollectionRead "GET /_api/collection/collection-name/properties"</li>
/// <li>@ref HttpCollectionRead "GET /_api/collection/collection-name/count"</li>
/// <li>@ref HttpCollectionRead "GET /_api/collection/collection-name/figures"</li>
/// <li>@ref HttpCollectionRead "GET /_api/collection/collection-name"</li>
/// <li>@ref HttpCollectionReadAll "GET /_api/collection/"</li>
/// </ul>
/// </li>
/// <li>@ref HttpCollectionChanging
/// <ul>
/// <li>@ref HttpCollectionLoad "PUT /_api/collection/collection-identifier/load"</li>
/// <li>@ref HttpCollectionUnload "PUT /_api/collection/collection-identifier/unload"</li>
/// <li>@ref HttpCollectionProperties "PUT /_api/collection/collection-identifier/properties"</li>
/// <li>@ref HttpCollectionRename "PUT /_api/collection/collection-identifier/rename"</li>
/// <li>@ref HttpCollectionLoad "PUT /_api/collection/collection-name/load"</li>
/// <li>@ref HttpCollectionUnload "PUT /_api/collection/collection-name/unload"</li>
/// <li>@ref HttpCollectionProperties "PUT /_api/collection/collection-name/properties"</li>
/// <li>@ref HttpCollectionRename "PUT /_api/collection/collection-name/rename"</li>
/// </ul>
/// </li>
/// </ul>
@ -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
///////////////////////////////////////////////////////////////////

6
arangod/Documentation/api-index.dox
View File

@ -46,7 +46,7 @@
///
/// <ul>
/// <li>@ref HttpIndexRead "GET /_api/index/index-handle"</li>
/// <li>@ref HttpIndexCreate "POST /_api/index?collection=collection-identifier"</li>
/// <li>@ref HttpIndexCreate "POST /_api/index?collection=collection-name"</li>
/// <li>@ref HttpIndexDelete "DELETE /_api/index/index-handle"</li>
/// <li>@ref HttpIndexReadAll "GET /_api/index?collection=index-handle"</li>
/// </ul>
@ -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
//////////////////////////////////////////////////////////

13
arangod/Documentation/http-interface.dox
View File

@ -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.

4
arangod/Documentation/rest-document.dox
View File

@ -46,12 +46,12 @@
///
/// <ul>
/// <li>@ref RestDocumentRead "GET /_api/document/document-handle"</li>
/// <li>@ref RestDocumentCreate "POST /_api/document?collection=collection-identifier"</li>
/// <li>@ref RestDocumentCreate "POST /_api/document?collection=collection-name"</li>
/// <li>@ref RestDocumentReplace "PUT /_api/document/document-handle"</li>
/// <li>@ref RestDocumentUpdate "PATCH /_api/document/document-handle"</li>
/// <li>@ref RestDocumentDelete "DELETE /_api/document/document-handle"</li>
/// <li>@ref RestDocumentHead "HEAD /_api/document/document-handle"</li>
/// <li>@ref RestDocumentReadAll "GET /_api/document?collection=collection-identifier"</li>
/// <li>@ref RestDocumentReadAll "GET /_api/document?collection=collection-name"</li>
/// </ul>
////////////////////////////////////////////////////////////////////////////////

4
arangod/Documentation/rest-edge.dox
View File

@ -46,11 +46,11 @@
///
/// <ul>
/// <li>@ref RestEdgeRead "GET /_api/edge/document-handle"</li>
/// <li>@ref RestEdgeCreate "POST /_api/edge?collection=collection-identifier&from=from-handle&to=to-handle"</li>
/// <li>@ref RestEdgeCreate "POST /_api/edge?collection=collection-name&from=from-handle&to=to-handle"</li>
/// <li>@ref RestEdgeUpdate "PUT /_api/edge/document-handle"</li>
/// <li>@ref RestEdgeDelete "DELETE /_api/edge/document-handle"</li>
/// <li>@ref RestEdgeHead "HEAD /_api/edge/document-handle"</li>
/// <li>@ref RestEdgeEdges "GET /_api/edges/collection-identifier?vertex=vertex-handle&directory=direction"</li>
/// <li>@ref RestEdgeEdges "GET /_api/edges/collection-name?vertex=vertex-handle&directory=direction"</li>
/// </ul>
////////////////////////////////////////////////////////////////////////////////

22
arangod/Documentation/shell-collection.dox
View File

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

26
arangod/RestHandler/RestDocumentHandler.cpp
View File

@ -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/<document-handle> or GET /_api/document?collection=<collection-identifier>");
"expecting GET /_api/document/<document-handle> or GET /_api/document?collection=<collection-name>");
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

20
arangod/RestHandler/RestEdgeHandler.cpp
View File

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

37
arangod/RestHandler/RestImportHandler.cpp
View File

@ -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;

11
arangod/V8Server/v8-vocbase.cpp
View File

@ -4892,16 +4892,17 @@ static v8::Handle<v8::Value> MapGetVocBase (v8::Local<v8::String> 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: