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

Started generation of traversal api documentation. Still not successful

This commit is contained in:
Michael Hackstein 2014-06-20 09:20:33 +02:00
parent 79ad6f60af
commit e6519fd292
2 changed files with 68 additions and 2963 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2900
Documentation/Books/Users/HttpTraversal/README.mdpp
View File

File diff suppressed because it is too large Load Diff

131
js/actions/api-traversal.js
View File

@ -68,6 +68,7 @@ function notFound (req, res, code, message) {
//////////////////////////////////////////////////////////////////////////////// ////////////////////////////////////////////////////////////////////////////////
/// @brief execute a server-side traversal /// @brief execute a server-side traversal
/// @startDocuBlock JSF_HTTP_API_TRAVERSAL
/// ///
/// @RESTHEADER{POST /_api/traversal,executes a traversal} /// @RESTHEADER{POST /_api/traversal,executes a traversal}
/// ///
@ -78,48 +79,48 @@ function notFound (req, res, code, message) {
/// edges contained in a given edgeCollection. The request must /// edges contained in a given edgeCollection. The request must
/// contain the following attributes. /// contain the following attributes.
/// ///
/// - `startVertex`: id of the startVertex, e.g. `"users/foo"`. /// - *startVertex*: id of the startVertex, e.g. *"users/foo"*.
/// ///
/// - `edgeCollection`: **Deprecated** name of the collection that contains the edges. /// - *edgeCollection*: **Deprecated** name of the collection that contains the edges.
/// ///
/// - `graphName`: name of the graph that contains the edges. /// - *graphName*: name of the graph that contains the edges.
/// ///
/// - `filter` (optional, default is to include all nodes): /// - *filter* (optional, default is to include all nodes):
/// body (JavaScript code) of custom filter function /// body (JavaScript code) of custom filter function
/// function signature: (config, vertex, path) -> mixed /// function signature: (config, vertex, path) -> mixed
/// can return four different string values: /// can return four different string values:
/// - `"exclude"` -> this vertex will not be visited. /// - *"exclude"* -> this vertex will not be visited.
/// - `"prune"` -> the edges of this vertex will not be followed. /// - *"prune"* -> the edges of this vertex will not be followed.
/// - `""` or `undefined` -> visit the vertex and follow it's edges. /// - *""* or *undefined* -> visit the vertex and follow it's edges.
/// - `Array` -> containing any combination of the above. /// - *Array* -> containing any combination of the above.
/// If there is at least one `"exclude"` or `"prune"` respectivly /// If there is at least one *"exclude"* or *"prune"* respectivly
/// is contained, it's effect will occur. /// is contained, it's effect will occur.
/// ///
/// - `minDepth` (optional, ANDed with any existing filters): /// - *minDepth* (optional, ANDed with any existing filters):
/// visits only nodes in at least the given depth /// visits only nodes in at least the given depth
/// ///
/// - `maxDepth` (optional, ANDed with any existing filters): /// - *maxDepth* (optional, ANDed with any existing filters):
/// visits only nodes in at most the given depth /// visits only nodes in at most the given depth
/// ///
/// - `visitor` (optional): body (JavaScript) code of custom visitor function /// - *visitor* (optional): body (JavaScript) code of custom visitor function
/// function signature: (config, result, vertex, path) -> void /// function signature: (config, result, vertex, path) -> void
/// visitor function can do anything, but its return value is ignored. To /// visitor function can do anything, but its return value is ignored. To
/// populate a result, use the `result` variable by reference /// populate a result, use the *result* variable by reference
/// ///
/// - `direction` (optional): direction for traversal /// - *direction* (optional): direction for traversal
/// - *if set*, must be either `"outbound"`, `"inbound"`, or `"any"` /// - *if set*, must be either *"outbound"*, *"inbound"*, or *"any"*
/// - *if not set*, the `expander` attribute must be specified /// - *if not set*, the *expander* attribute must be specified
/// ///
/// - `init` (optional): body (JavaScript) code of custom result initialisation function /// - *init* (optional): body (JavaScript) code of custom result initialisation function
/// function signature: (config, result) -> void /// function signature: (config, result) -> void
/// initialise any values in result with what is required /// initialise any values in result with what is required
/// ///
/// - `expander` (optional): body (JavaScript) code of custom expander function /// - *expander* (optional): body (JavaScript) code of custom expander function
/// *must* be set if `direction` attribute is *not* set /// *must* be set if *direction* attribute is **not** set
/// function signature: (config, vertex, path) -> array /// function signature: (config, vertex, path) -> array
/// expander must return an array of the connections for `vertex` /// expander must return an array of the connections for *vertex*
/// each connection is an object with the attributes `edge` and `vertex` /// each connection is an object with the attributes *edge* and *vertex*
/// - `sort` (optional): body (JavaScript) code of a custom comparison function /// - *sort* (optional): body (JavaScript) code of a custom comparison function
/// for the edges. The signature of this function is /// for the edges. The signature of this function is
/// (l, r) -> integer (where l and r are edges) and must /// (l, r) -> integer (where l and r are edges) and must
/// return -1 if l is smaller than, +1 if l is greater than, /// return -1 if l is smaller than, +1 if l is greater than,
@ -136,80 +137,80 @@ function notFound (req, res, code, message) {
/// expanders. If you use your custom expander you have to /// expanders. If you use your custom expander you have to
/// do the sorting yourself within the expander code. /// do the sorting yourself within the expander code.
/// ///
/// - `strategy` (optional): traversal strategy /// - *strategy* (optional): traversal strategy
/// can be `"depthfirst"` or `"breadthfirst"` /// can be *"depthfirst"* or *"breadthfirst"*
/// ///
/// - `order` (optional): traversal order /// - *order* (optional): traversal order
/// can be `"preorder"` or `"postorder"` /// can be *"preorder"* or *"postorder"*
/// ///
/// - `itemOrder` (optional): item iteration order /// - *itemOrder* (optional): item iteration order
/// can be `"forward"` or `"backward"` /// can be *"forward"* or *"backward"*
/// ///
/// - `uniqueness` (optional): specifies uniqueness for vertices and edges visited /// - *uniqueness* (optional): specifies uniqueness for vertices and edges visited
/// if set, must be an object like this: /// if set, must be an object like this:
/// `"uniqueness": {"vertices": "none"|"global"|path", "edges": "none"|"global"|"path"}` /// *"uniqueness": {"vertices": "none"|"global"|path", "edges": "none"|"global"|"path"}*
/// ///
/// - `maxIterations` (optional): Maximum number of iterations in each traversal. This number can be /// - *maxIterations* (optional): Maximum number of iterations in each traversal. This number can be
/// set to prevent endless loops in traversal of cyclic graphs. When a traversal performs /// set to prevent endless loops in traversal of cyclic graphs. When a traversal performs
/// as many iterations as the `maxIterations` value, the traversal will abort with an /// as many iterations as the *maxIterations* value, the traversal will abort with an
/// error. If `maxIterations` is not set, a server-defined value may be used. /// error. If *maxIterations* is not set, a server-defined value may be used.
/// ///
/// ///
/// If the Traversal is successfully executed `HTTP 200` will be returned. /// If the Traversal is successfully executed *HTTP 200* will be returned.
/// Additionally the `result` object will be returned by the traversal. /// Additionally the *result* object will be returned by the traversal.
/// ///
/// For successful traversals, the returned JSON object has the /// For successful traversals, the returned JSON object has the
/// following properties: /// following properties:
/// ///
/// - `error`: boolean flag to indicate if an error occurred (`false` /// - *error*: boolean flag to indicate if an error occurred (*false*
/// in this case) /// in this case)
/// ///
/// - `code`: the HTTP status code /// - *code*: the HTTP status code
/// ///
/// - `result`: the return value of the traversal /// - *result*: the return value of the traversal
/// ///
/// If the traversal specification is either missing or malformed, the server /// If the traversal specification is either missing or malformed, the server
/// will respond with `HTTP 400`. /// will respond with *HTTP 400*.
/// ///
/// The body of the response will then contain a JSON object with additional error /// The body of the response will then contain a JSON object with additional error
/// details. The object has the following attributes: /// details. The object has the following attributes:
/// ///
/// - `error`: boolean flag to indicate that an error occurred (`true` in this case) /// - *error*: boolean flag to indicate that an error occurred (*true* in this case)
/// ///
/// - `code`: the HTTP status code /// - *code*: the HTTP status code
/// ///
/// - `errorNum`: the server error number /// - *errorNum*: the server error number
/// ///
/// - `errorMessage`: a descriptive error message /// - *errorMessage*: a descriptive error message
/// ///
/// @RESTRETURNCODES /// @RESTRETURNCODES
/// ///
/// @RESTRETURNCODE{200} /// @RESTRETURNCODE{200}
/// If the traversal is fully executed /// If the traversal is fully executed
/// `HTTP 200` will be returned. /// *HTTP 200* will be returned.
/// ///
/// @RESTRETURNCODE{400} /// @RESTRETURNCODE{400}
/// If the traversal specification is either missing or malformed, the server /// If the traversal specification is either missing or malformed, the server
/// will respond with `HTTP 400`. /// will respond with *HTTP 400*.
/// ///
/// @RESTRETURNCODE{404} /// @RESTRETURNCODE{404}
/// The server will responded with `HTTP 404` if the specified edge collection /// The server will responded with *HTTP 404* if the specified edge collection
/// does not exist, or the specified start vertex cannot be found. /// does not exist, or the specified start vertex cannot be found.
/// ///
/// @RESTRETURNCODE{500} /// @RESTRETURNCODE{500}
/// The server will responded with `HTTP 500` when an error occurs inside the /// The server will responded with *HTTP 500* when an error occurs inside the
/// traversal or if a traversal performs more than `maxIterations` iterations. /// traversal or if a traversal performs more than *maxIterations* iterations.
/// ///
/// *Examples* /// *Examples*
/// ///
/// In the following examples the underlying graph will contain five persons /// In the following examples the underlying graph will contain five persons
/// `Alice`, `Bob`, `Charlie`, `Dave` and `Eve`. /// *Alice*, *Bob*, *Charlie*, *Dave* and *Eve*.
/// We will have the following directed relations: /// We will have the following directed relations:
/// - `Alice` knows `Bob` /// - *Alice* knows *Bob*
/// - `Bob` knows `Charlie` /// - *Bob* knows *Charlie*
/// - `Bob` knows `Dave` /// - *Bob* knows *Dave*
/// - `Eve` knows `Alice` /// - *Eve* knows *Alice*
/// - `Eve` knows `Bob` /// - *Eve* knows *Bob*
/// ///
/// The starting vertex will always be Alice. /// The starting vertex will always be Alice.
/// ///
@ -273,7 +274,7 @@ function notFound (req, res, code, message) {
/// examples.dropGraph("knows_graph"); /// examples.dropGraph("knows_graph");
/// @END_EXAMPLE_ARANGOSH_RUN /// @END_EXAMPLE_ARANGOSH_RUN
/// ///
/// Excluding `Charlie` and `Bob`: /// Excluding *Charlie* and *Bob*:
/// ///
/// @EXAMPLE_ARANGOSH_RUN{RestTraversalFilterExclude} /// @EXAMPLE_ARANGOSH_RUN{RestTraversalFilterExclude}
/// var examples = require("org/arangodb/graph-examples/example-graph.js"); /// var examples = require("org/arangodb/graph-examples/example-graph.js");
@ -296,7 +297,7 @@ function notFound (req, res, code, message) {
/// examples.dropGraph("knows_graph"); /// examples.dropGraph("knows_graph");
/// @END_EXAMPLE_ARANGOSH_RUN /// @END_EXAMPLE_ARANGOSH_RUN
/// ///
/// Do not follow edges from `Bob`: /// Do not follow edges from *Bob*:
/// ///
/// @EXAMPLE_ARANGOSH_RUN{RestTraversalFilterPrune} /// @EXAMPLE_ARANGOSH_RUN{RestTraversalFilterPrune}
/// var examples = require("org/arangodb/graph-examples/example-graph.js"); /// var examples = require("org/arangodb/graph-examples/example-graph.js");
@ -376,7 +377,7 @@ function notFound (req, res, code, message) {
/// examples.dropGraph("knows_graph"); /// examples.dropGraph("knows_graph");
/// @END_EXAMPLE_ARANGOSH_RUN /// @END_EXAMPLE_ARANGOSH_RUN
/// ///
/// Expand only inbound edges of `Alice` and outbound edges of `Eve`: /// Expand only inbound edges of *Alice* and outbound edges of *Eve*:
/// ///
/// @EXAMPLE_ARANGOSH_RUN{RestTraversalVisitorExpander} /// @EXAMPLE_ARANGOSH_RUN{RestTraversalVisitorExpander}
/// var examples = require("org/arangodb/graph-examples/example-graph.js"); /// var examples = require("org/arangodb/graph-examples/example-graph.js");
@ -413,7 +414,7 @@ function notFound (req, res, code, message) {
/// examples.dropGraph("knows_graph"); /// examples.dropGraph("knows_graph");
/// @END_EXAMPLE_ARANGOSH_RUN /// @END_EXAMPLE_ARANGOSH_RUN
/// ///
/// Follow the `depthfirst` strategy: /// Follow the *depthfirst* strategy:
/// ///
/// @EXAMPLE_ARANGOSH_RUN{RestTraversalDepthFirst} /// @EXAMPLE_ARANGOSH_RUN{RestTraversalDepthFirst}
/// var examples = require("org/arangodb/graph-examples/example-graph.js"); /// var examples = require("org/arangodb/graph-examples/example-graph.js");
@ -434,7 +435,7 @@ function notFound (req, res, code, message) {
/// examples.dropGraph("knows_graph"); /// examples.dropGraph("knows_graph");
/// @END_EXAMPLE_ARANGOSH_RUN /// @END_EXAMPLE_ARANGOSH_RUN
/// ///
/// Using `postorder` ordering: /// Using *postorder* ordering:
/// ///
/// @EXAMPLE_ARANGOSH_RUN{RestTraversalPostorder} /// @EXAMPLE_ARANGOSH_RUN{RestTraversalPostorder}
/// var examples = require("org/arangodb/graph-examples/example-graph.js"); /// var examples = require("org/arangodb/graph-examples/example-graph.js");
@ -455,7 +456,7 @@ function notFound (req, res, code, message) {
/// examples.dropGraph("knows_graph"); /// examples.dropGraph("knows_graph");
/// @END_EXAMPLE_ARANGOSH_RUN /// @END_EXAMPLE_ARANGOSH_RUN
/// ///
/// Using `backward` item-ordering: /// Using *backward* item-ordering:
/// ///
/// @EXAMPLE_ARANGOSH_RUN{RestTraversalBackwardItemOrder} /// @EXAMPLE_ARANGOSH_RUN{RestTraversalBackwardItemOrder}
/// var examples = require("org/arangodb/graph-examples/example-graph.js"); /// var examples = require("org/arangodb/graph-examples/example-graph.js");
@ -501,12 +502,12 @@ function notFound (req, res, code, message) {
/// examples.dropGraph("knows_graph"); /// examples.dropGraph("knows_graph");
/// @END_EXAMPLE_ARANGOSH_RUN /// @END_EXAMPLE_ARANGOSH_RUN
/// ///
/// If the underlying graph is cyclic, `maxIterations` should be set: /// If the underlying graph is cyclic, *maxIterations* should be set:
/// ///
/// The underlying graph has two vertices `Alice` and `Bob`. /// The underlying graph has two vertices *Alice* and *Bob*.
/// With the directed edges: /// With the directed edges:
/// - `Alice` knows `Bob` /// - *Alice* knows *Bob*
/// _ `Bob` knows `Alice` /// _ *Bob* knows *Alice*
/// ///
/// ///
/// @EXAMPLE_ARANGOSH_RUN{RestTraversalMaxIterations} /// @EXAMPLE_ARANGOSH_RUN{RestTraversalMaxIterations}
@ -535,6 +536,8 @@ function notFound (req, res, code, message) {
/// logJsonResponse(response); /// logJsonResponse(response);
/// examples.dropGraph("knows_graph"); /// examples.dropGraph("knows_graph");
/// @END_EXAMPLE_ARANGOSH_RUN /// @END_EXAMPLE_ARANGOSH_RUN
///
/// @endDocuBlock
//////////////////////////////////////////////////////////////////////////////// ////////////////////////////////////////////////////////////////////////////////
function post_api_traversal(req, res) { function post_api_traversal(req, res) {