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
/// @startDocuBlock JSF_HTTP_API_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
/// 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
/// function signature: (config, vertex, path) -> mixed
/// can return four different string values:
/// - `"exclude"` -> this vertex will not be visited.
/// - `"prune"` -> the edges of this vertex will not be followed.
/// - `""` or `undefined` -> visit the vertex and follow it's edges.
/// - `Array` -> containing any combination of the above.
/// If there is at least one `"exclude"` or `"prune"` respectivly
/// - *"exclude"* -> this vertex will not be visited.
/// - *"prune"* -> the edges of this vertex will not be followed.
/// - *""* or *undefined* -> visit the vertex and follow it's edges.
/// - *Array* -> containing any combination of the above.
/// If there is at least one *"exclude"* or *"prune"* respectivly
/// 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
///
/// - `maxDepth` (optional, ANDed with any existing filters):
/// - *maxDepth* (optional, ANDed with any existing filters):
/// 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
/// 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
/// - *if set*, must be either `"outbound"`, `"inbound"`, or `"any"`
/// - *if not set*, the `expander` attribute must be specified
/// - *direction* (optional): direction for traversal
/// - *if set*, must be either *"outbound"*, *"inbound"*, or *"any"*
/// - *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
/// initialise any values in result with what is required
///
/// - `expander` (optional): body (JavaScript) code of custom expander function
/// *must* be set if `direction` attribute is *not* set
/// - *expander* (optional): body (JavaScript) code of custom expander function
/// *must* be set if *direction* attribute is **not** set
/// function signature: (config, vertex, path) -> array
/// expander must return an array of the connections for `vertex`
/// each connection is an object with the attributes `edge` and `vertex`
/// - `sort` (optional): body (JavaScript) code of a custom comparison function
/// expander must return an array of the connections for *vertex*
/// each connection is an object with the attributes *edge* and *vertex*
/// - *sort* (optional): body (JavaScript) code of a custom comparison function
/// for the edges. The signature of this function is
/// (l, r) -> integer (where l and r are edges) and must
/// 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
/// do the sorting yourself within the expander code.
///
/// - `strategy` (optional): traversal strategy
/// can be `"depthfirst"` or `"breadthfirst"`
/// - *strategy* (optional): traversal strategy
/// can be *"depthfirst"* or *"breadthfirst"*
///
/// - `order` (optional): traversal order
/// can be `"preorder"` or `"postorder"`
/// - *order* (optional): traversal order
/// can be *"preorder"* or *"postorder"*
///
/// - `itemOrder` (optional): item iteration order
/// can be `"forward"` or `"backward"`
/// - *itemOrder* (optional): item iteration order
/// 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:
/// `"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
/// 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.
/// 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.
///
///
/// If the Traversal is successfully executed `HTTP 200` will be returned.
/// Additionally the `result` object will be returned by the traversal.
/// If the Traversal is successfully executed *HTTP 200* will be returned.
/// Additionally the *result* object will be returned by the traversal.
///
/// For successful traversals, the returned JSON object has the
/// 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)
///
/// - `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
/// will respond with `HTTP 400`.
/// will respond with *HTTP 400*.
///
/// The body of the response will then contain a JSON object with additional error
/// 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
///
/// @RESTRETURNCODE{200}
/// If the traversal is fully executed
/// `HTTP 200` will be returned.
/// *HTTP 200* will be returned.
///
/// @RESTRETURNCODE{400}
/// If the traversal specification is either missing or malformed, the server
/// will respond with `HTTP 400`.
/// will respond with *HTTP 400*.
///
/// @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.
///
/// @RESTRETURNCODE{500}
/// The server will responded with `HTTP 500` when an error occurs inside the
/// traversal or if a traversal performs more than `maxIterations` iterations.
/// The server will responded with *HTTP 500* when an error occurs inside the
/// traversal or if a traversal performs more than *maxIterations* iterations.
///
/// *Examples*
///
/// 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:
/// - `Alice` knows `Bob`
/// - `Bob` knows `Charlie`
/// - `Bob` knows `Dave`
/// - `Eve` knows `Alice`
/// - `Eve` knows `Bob`
/// - *Alice* knows *Bob*
/// - *Bob* knows *Charlie*
/// - *Bob* knows *Dave*
/// - *Eve* knows *Alice*
/// - *Eve* knows *Bob*
///
/// The starting vertex will always be Alice.
///
@ -273,7 +274,7 @@ function notFound (req, res, code, message) {
/// examples.dropGraph("knows_graph");
/// @END_EXAMPLE_ARANGOSH_RUN
///
/// Excluding `Charlie` and `Bob`:
/// Excluding *Charlie* and *Bob*:
///
/// @EXAMPLE_ARANGOSH_RUN{RestTraversalFilterExclude}
/// var examples = require("org/arangodb/graph-examples/example-graph.js");
@ -296,7 +297,7 @@ function notFound (req, res, code, message) {
/// examples.dropGraph("knows_graph");
/// @END_EXAMPLE_ARANGOSH_RUN
///
/// Do not follow edges from `Bob`:
/// Do not follow edges from *Bob*:
///
/// @EXAMPLE_ARANGOSH_RUN{RestTraversalFilterPrune}
/// var examples = require("org/arangodb/graph-examples/example-graph.js");
@ -376,7 +377,7 @@ function notFound (req, res, code, message) {
/// examples.dropGraph("knows_graph");
/// @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}
/// var examples = require("org/arangodb/graph-examples/example-graph.js");
@ -413,7 +414,7 @@ function notFound (req, res, code, message) {
/// examples.dropGraph("knows_graph");
/// @END_EXAMPLE_ARANGOSH_RUN
///
/// Follow the `depthfirst` strategy:
/// Follow the *depthfirst* strategy:
///
/// @EXAMPLE_ARANGOSH_RUN{RestTraversalDepthFirst}
/// var examples = require("org/arangodb/graph-examples/example-graph.js");
@ -434,7 +435,7 @@ function notFound (req, res, code, message) {
/// examples.dropGraph("knows_graph");
/// @END_EXAMPLE_ARANGOSH_RUN
///
/// Using `postorder` ordering:
/// Using *postorder* ordering:
///
/// @EXAMPLE_ARANGOSH_RUN{RestTraversalPostorder}
/// var examples = require("org/arangodb/graph-examples/example-graph.js");
@ -455,7 +456,7 @@ function notFound (req, res, code, message) {
/// examples.dropGraph("knows_graph");
/// @END_EXAMPLE_ARANGOSH_RUN
///
/// Using `backward` item-ordering:
/// Using *backward* item-ordering:
///
/// @EXAMPLE_ARANGOSH_RUN{RestTraversalBackwardItemOrder}
/// var examples = require("org/arangodb/graph-examples/example-graph.js");
@ -501,12 +502,12 @@ function notFound (req, res, code, message) {
/// examples.dropGraph("knows_graph");
/// @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:
/// - `Alice` knows `Bob`
/// _ `Bob` knows `Alice`
/// - *Alice* knows *Bob*
/// _ *Bob* knows *Alice*
///
///
/// @EXAMPLE_ARANGOSH_RUN{RestTraversalMaxIterations}
@ -535,6 +536,8 @@ function notFound (req, res, code, message) {
/// logJsonResponse(response);
/// examples.dropGraph("knows_graph");
/// @END_EXAMPLE_ARANGOSH_RUN
///
/// @endDocuBlock
////////////////////////////////////////////////////////////////////////////////
function post_api_traversal(req, res) {