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

de-indent the blocks we want to inline in the next step.

This commit is contained in:
Wilfried Goesgens 2016-01-11 15:08:49 +01:00
parent 0859d3fa20
commit 679e2db476
362 changed files with 9996 additions and 10358 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

53
Documentation/DocuBlocks/DatabaseDirectory.md
View File

@ -1,27 +1,26 @@
////////////////////////////////////////////////////////////////////////////////
/// @startDocuBlock DatabaseDirectory
/// @brief path to the database
/// `--database.directory directory`
///
/// The directory containing the collections and datafiles. Defaults
/// to */var/lib/arango*. When specifying the database directory, please
/// make sure the directory is actually writable by the arangod process.
///
/// You should further not use a database directory which is provided by a
/// network filesystem such as NFS. The reason is that networked filesystems
/// might cause inconsistencies when there are multiple parallel readers or
/// writers or they lack features required by arangod (e.g. flock()).
///
/// `directory`
///
/// When using the command line version, you can simply supply the database
/// directory as argument.
///
/// @EXAMPLES
///
/// ```
/// > ./arangod --server.endpoint tcp://127.0.0.1:8529 --database.directory
/// /tmp/vocbase
/// ```
/// @endDocuBlock
////////////////////////////////////////////////////////////////////////////////
@brief path to the database
`--database.directory directory`
The directory containing the collections and datafiles. Defaults
to */var/lib/arango*. When specifying the database directory, please
make sure the directory is actually writable by the arangod process.
You should further not use a database directory which is provided by a
network filesystem such as NFS. The reason is that networked filesystems
might cause inconsistencies when there are multiple parallel readers or
writers or they lack features required by arangod (e.g. flock()).
`directory`
When using the command line version, you can simply supply the database
directory as argument.
@EXAMPLES
```
> ./arangod --server.endpoint tcp://127.0.0.1:8529 --database.directory
/tmp/vocbase
```

27
Documentation/DocuBlocks/DefaultLanguage.md
View File

@ -1,14 +1,13 @@
////////////////////////////////////////////////////////////////////////////////
/// @startDocuBlock DefaultLanguage
/// @brief server default language for sorting strings
/// `--default-language default-language`
///
/// The default language ist used for sorting and comparing strings.
/// The language value is a two-letter language code (ISO-639) or it is
/// composed by a two-letter language code with and a two letter country code
/// (ISO-3166). Valid languages are "de", "en", "en_US" or "en_UK".
///
/// The default default-language is set to be the system locale on that
/// platform.
/// @endDocuBlock
////////////////////////////////////////////////////////////////////////////////
@brief server default language for sorting strings
`--default-language default-language`
The default language ist used for sorting and comparing strings.
The language value is a two-letter language code (ISO-639) or it is
composed by a two-letter language code with and a two letter country code
(ISO-3166). Valid languages are "de", "en", "en_US" or "en_UK".
The default default-language is set to be the system locale on that
platform.

35
Documentation/DocuBlocks/IndexHandle.md
View File

@ -1,18 +1,17 @@
////////////////////////////////////////////////////////////////////////////////
/// @startDocuBlock IndexHandle
/// @brief finds an index
/// `db._index(index-handle)`
///
/// Returns the index with *index-handle* or null if no such index exists.
///
/// @EXAMPLE_ARANGOSH_OUTPUT{IndexHandle}
/// ~db._create("example");
/// db.example.ensureIndex({ type: "skiplist", fields: [ "a", "b" ] });
/// var indexInfo = db.example.getIndexes().map(function(x) { return x.id; });
/// indexInfo;
/// db._index(indexInfo[0])
/// db._index(indexInfo[1])
/// ~db._drop("example");
/// @END_EXAMPLE_ARANGOSH_OUTPUT
/// @endDocuBlock
////////////////////////////////////////////////////////////////////////////////
@brief finds an index
`db._index(index-handle)`
Returns the index with *index-handle* or null if no such index exists.
@EXAMPLE_ARANGOSH_OUTPUT{IndexHandle}
~db._create("example");
db.example.ensureIndex({ type: "skiplist", fields: [ "a", "b" ] });
var indexInfo = db.example.getIndexes().map(function(x) { return x.id; });
indexInfo;
db._index(indexInfo[0])
db._index(indexInfo[1])
~db._drop("example");
@END_EXAMPLE_ARANGOSH_OUTPUT

37
Documentation/DocuBlocks/IndexVerify.md
View File

@ -1,19 +1,18 @@
////////////////////////////////////////////////////////////////////////////////
/// @startDocuBlock IndexVerify
/// @brief finds an index
///
/// So you've created an index, and since its maintainance isn't for free,
/// you definitely want to know whether your query can utilize it.
///
/// You can use explain to verify whether **skiplists** or **hash indexes** are
/// used (if you omit `colors: false` you will get nice colors in ArangoShell):
///
/// @EXAMPLE_ARANGOSH_OUTPUT{IndexVerify}
/// ~db._create("example");
/// var explain = require("@arangodb/aql/explainer").explain;
/// db.example.ensureIndex({ type: "skiplist", fields: [ "a", "b" ] });
/// explain("FOR doc IN example FILTER doc.a < 23 RETURN doc", {colors:false});
/// ~db._drop("example");
/// @END_EXAMPLE_ARANGOSH_OUTPUT
/// @endDocuBlock
////////////////////////////////////////////////////////////////////////////////
@brief finds an index
So you've created an index, and since its maintainance isn't for free,
you definitely want to know whether your query can utilize it.
You can use explain to verify whether **skiplists** or **hash indexes** are
used (if you omit `colors: false` you will get nice colors in ArangoShell):
@EXAMPLE_ARANGOSH_OUTPUT{IndexVerify}
~db._create("example");
var explain = require("@arangodb/aql/explainer").explain;
db.example.ensureIndex({ type: "skiplist", fields: [ "a", "b" ] });
explain("FOR doc IN example FILTER doc.a < 23 RETURN doc", {colors:false});
~db._drop("example");
@END_EXAMPLE_ARANGOSH_OUTPUT

71
Documentation/DocuBlocks/InsertEdgeCol.md
View File

@ -1,36 +1,35 @@
////////////////////////////////////////////////////////////////////////////////
/// @startDocuBlock InsertEdgeCol
/// @brief saves a new edge document
/// `edge-collection.insert(from, to, document)`
///
/// Saves a new edge and returns the document-handle. *from* and *to*
/// must be documents or document references.
///
/// `edge-collection.insert(from, to, document, waitForSync)`
///
/// The optional *waitForSync* parameter can be used to force
/// synchronization of the document creation operation to disk even in case
/// that the *waitForSync* flag had been disabled for the entire collection.
/// Thus, the *waitForSync* parameter can be used to force synchronization
/// of just specific operations. To use this, set the *waitForSync* parameter
/// to *true*. If the *waitForSync* parameter is not specified or set to
/// *false*, then the collection's default *waitForSync* behavior is
/// applied. The *waitForSync* parameter cannot be used to disable
/// synchronization for collections that have a default *waitForSync* value
/// of *true*.
///
/// @EXAMPLES
///
/// @EXAMPLE_ARANGOSH_OUTPUT{EDGCOL_01_SaveEdgeCol}
/// db._create("vertex");
/// db._createEdgeCollection("relation");
/// v1 = db.vertex.insert({ name : "vertex 1" });
/// v2 = db.vertex.insert({ name : "vertex 2" });
/// e1 = db.relation.insert(v1, v2, { label : "knows" });
/// db._document(e1);
/// ~ db._drop("relation");
/// ~ db._drop("vertex");
/// @END_EXAMPLE_ARANGOSH_OUTPUT
///
/// @endDocuBlock
////////////////////////////////////////////////////////////////////////////////
@brief saves a new edge document
`edge-collection.insert(from, to, document)`
Saves a new edge and returns the document-handle. *from* and *to*
must be documents or document references.
`edge-collection.insert(from, to, document, waitForSync)`
The optional *waitForSync* parameter can be used to force
synchronization of the document creation operation to disk even in case
that the *waitForSync* flag had been disabled for the entire collection.
Thus, the *waitForSync* parameter can be used to force synchronization
of just specific operations. To use this, set the *waitForSync* parameter
to *true*. If the *waitForSync* parameter is not specified or set to
*false*, then the collection's default *waitForSync* behavior is
applied. The *waitForSync* parameter cannot be used to disable
synchronization for collections that have a default *waitForSync* value
of *true*.
@EXAMPLES
@EXAMPLE_ARANGOSH_OUTPUT{EDGCOL_01_SaveEdgeCol}
db._create("vertex");
db._createEdgeCollection("relation");
v1 = db.vertex.insert({ name : "vertex 1" });
v2 = db.vertex.insert({ name : "vertex 2" });
e1 = db.relation.insert(v1, v2, { label : "knows" });
db._document(e1);
~ db._drop("relation");
~ db._drop("vertex");
@END_EXAMPLE_ARANGOSH_OUTPUT

37
Documentation/DocuBlocks/JSF_Cluster_Kickstarter_Constructor.md
View File

@ -1,19 +1,18 @@
////////////////////////////////////////////////////////////////////////////////
/// @startDocuBlock JSF_Cluster_Kickstarter_Constructor
///
/// `new require("@arangodb/cluster").Kickstarter(plan)`
///
/// This constructor constructs a kickstarter object. Its first
/// argument is a cluster plan as for example provided by the planner
/// (see Cluster Planner Constructor and the general
/// explanations before this reference). The second argument is
/// optional and is taken to be "me" if omitted, it is the ID of the
/// dispatcher this object should consider itself to be. If the plan
/// contains startup commands for the dispatcher with this ID, these
/// commands are executed immediately. Otherwise they are handed over
/// to another responsible dispatcher via a REST call.
///
/// The resulting object of this constructors allows to launch,
/// shutdown, relaunch the cluster described in the plan.
/// @endDocuBlock
////////////////////////////////////////////////////////////////////////////////
`new require("@arangodb/cluster").Kickstarter(plan)`
This constructor constructs a kickstarter object. Its first
argument is a cluster plan as for example provided by the planner
(see Cluster Planner Constructor and the general
explanations before this reference). The second argument is
optional and is taken to be "me" if omitted, it is the ID of the
dispatcher this object should consider itself to be. If the plan
contains startup commands for the dispatcher with this ID, these
commands are executed immediately. Otherwise they are handed over
to another responsible dispatcher via a REST call.
The resulting object of this constructors allows to launch,
shutdown, relaunch the cluster described in the plan.

323
Documentation/DocuBlocks/JSF_Cluster_Planner_Constructor.md
View File

@ -1,162 +1,161 @@
////////////////////////////////////////////////////////////////////////////////
/// @startDocuBlock JSF_Cluster_Planner_Constructor
///
/// *new require("@arangodb/cluster").Planner(userConfig)*
///
/// This constructor builds a cluster planner object. The one and only
/// argument is an object that can have the properties described below.
/// The planner can plan clusters on a single machine (basically for
/// testing purposes) and on multiple machines. The resulting "cluster plans"
/// can be used by the kickstarter to start up the processes comprising
/// the cluster, including the agency. To this end, there has to be one
/// dispatcher on every machine participating in the cluster. A dispatcher
/// is a simple instance of ArangoDB, compiled with the cluster extensions,
/// but not running in cluster mode. This is why the configuration option
/// *dispatchers* below is of central importance.
///
/// - *dispatchers*: an object with a property for each dispatcher,
/// the property name is the ID of the dispatcher and the value
/// should be an object with at least the property *endpoint*
/// containing the endpoint of the corresponding dispatcher.
/// Further optional properties are:
///
/// - *avoidPorts* which is an object
/// in which all port numbers that should not be used are bound to
/// *true*, default is empty, that is, all ports can be used
/// - *arangodExtraArgs*, which is a list of additional
/// command line arguments that will be given to DBservers and
/// coordinators started by this dispatcher, the default is
/// an empty list. These arguments will be appended to those
/// produced automatically, such that one can overwrite
/// things with this.
/// - *allowCoordinators*, which is a boolean value indicating
/// whether or not coordinators should be started on this
/// dispatcher, the default is *true*
/// - *allowDBservers*, which is a boolean value indicating
/// whether or not DBservers should be started on this dispatcher,
/// the default is *true*
/// - *allowAgents*, which is a boolean value indicating whether or
/// not agents should be started on this dispatcher, the default is
/// *true*
/// - *username*, which is a string that contains the user name
/// for authentication with this dispatcher
/// - *passwd*, which is a string that contains the password
/// for authentication with this dispatcher, if not both
/// *username* and *passwd* are set, then no authentication
/// is used between dispatchers. Note that this will not work
/// if the dispatchers are configured with authentication.
///
/// If *.dispatchers* is empty (no property), then an entry for the
/// local arangod itself is automatically added. Note that if the
/// only configured dispatcher has endpoint *tcp://localhost:*,
/// all processes are started in a special "local" mode and are
/// configured to bind their endpoints only to the localhost device.
/// In all other cases both agents and *arangod* instances bind
/// their endpoints to all available network devices.
/// - *numberOfAgents*: the number of agents in the agency,
/// usually there is no reason to deviate from the default of 3. The
/// planner distributes them amongst the dispatchers, if possible.
/// - *agencyPrefix*: a string that is used as prefix for all keys of
/// configuration data stored in the agency.
/// - *numberOfDBservers*: the number of DBservers in the
/// cluster. The planner distributes them evenly amongst the dispatchers.
/// - *startSecondaries*: a boolean flag indicating whether or not
/// secondary servers are started. In this version, this flag is
/// silently ignored, since we do not yet have secondary servers.
/// - *numberOfCoordinators*: the number of coordinators in the cluster,
/// the planner distributes them evenly amongst the dispatchers.
/// - *DBserverIDs*: a list of DBserver IDs (strings). If the planner
/// runs out of IDs it creates its own ones using *DBserver*
/// concatenated with a unique number.
/// - *coordinatorIDs*: a list of coordinator IDs (strings). If the planner
/// runs out of IDs it creates its own ones using *Coordinator*
/// concatenated with a unique number.
/// - *dataPath*: this is a string and describes the path under which
/// the agents, the DBservers and the coordinators store their
/// data directories. This can either be an absolute path (in which
/// case all machines in the clusters must use the same path), or
/// it can be a relative path. In the latter case it is relative
/// to the directory that is configured in the dispatcher with the
/// *cluster.data-path* option (command line or configuration file).
/// The directories created will be called *data-PREFIX-ID* where
/// *PREFIX* is replaced with the agency prefix (see above) and *ID*
/// is the ID of the DBserver or coordinator.
/// - *logPath*: this is a string and describes the path under which
/// the DBservers and the coordinators store their log file. This can
/// either be an absolute path (in which case all machines in the cluster
/// must use the same path), or it can be a relative path. In the
/// latter case it is relative to the directory that is configured
/// in the dispatcher with the *cluster.log-path* option.
/// - *arangodPath*: this is a string and describes the path to the
/// actual executable *arangod* that will be started for the
/// DBservers and coordinators. If this is an absolute path, it
/// obviously has to be the same on all machines in the cluster
/// as described for *dataPath*. If it is an empty string, the
/// dispatcher uses the executable that is configured with the
/// *cluster.arangod-path* option, which is by default the same
/// executable as the dispatcher uses.
/// - *agentPath*: this is a string and describes the path to the
/// actual executable that will be started for the agents in the
/// agency. If this is an absolute path, it obviously has to be
/// the same on all machines in the cluster, as described for
/// *arangodPath*. If it is an empty string, the dispatcher
/// uses its *cluster.agent-path* option.
/// - *agentExtPorts*: a list of port numbers to use for the external
/// ports of the agents. When running out of numbers in this list,
/// the planner increments the last one used by one for every port
/// needed. Note that the planner checks availability of the ports
/// during the planning phase by contacting the dispatchers on the
/// different machines, and uses only ports that are free during
/// the planning phase. Obviously, if those ports are connected
/// before the actual startup, things can go wrong.
/// - *agentIntPorts*: a list of port numbers to use for the internal
/// ports of the agents. The same comments as for *agentExtPorts*
/// apply.
/// - *DBserverPorts*: a list of port numbers to use for the
/// DBservers. The same comments as for *agentExtPorts* apply.
/// - *coordinatorPorts*: a list of port numbers to use for the
/// coordinators. The same comments as for *agentExtPorts* apply.
/// - *useSSLonDBservers*: a boolean flag indicating whether or not
/// we use SSL on all DBservers in the cluster
/// - *useSSLonCoordinators*: a boolean flag indicating whether or not
/// we use SSL on all coordinators in the cluster
/// - *valgrind*: a string to contain the path of the valgrind binary
/// if we should run the cluster components in it
/// - *valgrindopts*: commandline options to the valgrind process
/// - *valgrindXmlFileBase*: pattern for logfiles
/// - *valgrindTestname*: name of test to add to the logfiles
/// - *valgrindHosts*: which host classes should run in valgrind?
/// Coordinator / DBServer
/// - *extremeVerbosity* : if set to true, then there will be more test
/// run output, especially for cluster tests.
///
/// All these values have default values. Here is the current set of
/// default values:
///
/// ```js
/// {
/// "agencyPrefix" : "arango",
/// "numberOfAgents" : 1,
/// "numberOfDBservers" : 2,
/// "startSecondaries" : false,
/// "numberOfCoordinators" : 1,
/// "DBserverIDs" : ["Pavel", "Perry", "Pancho", "Paul", "Pierre",
/// "Pit", "Pia", "Pablo" ],
/// "coordinatorIDs" : ["Claus", "Chantalle", "Claire", "Claudia",
/// "Claas", "Clemens", "Chris" ],
/// "dataPath" : "", // means configured in dispatcher
/// "logPath" : "", // means configured in dispatcher
/// "arangodPath" : "", // means configured as dispatcher
/// "agentPath" : "", // means configured in dispatcher
/// "agentExtPorts" : [4001],
/// "agentIntPorts" : [7001],
/// "DBserverPorts" : [8629],
/// "coordinatorPorts" : [8530],
/// "dispatchers" : {"me": {"endpoint": "tcp://localhost:"}},
/// // this means only we as a local instance
/// "useSSLonDBservers" : false,
/// "useSSLonCoordinators" : false
/// };
/// ```
/// @endDocuBlock
////////////////////////////////////////////////////////////////////////////////
*new require("@arangodb/cluster").Planner(userConfig)*
This constructor builds a cluster planner object. The one and only
argument is an object that can have the properties described below.
The planner can plan clusters on a single machine (basically for
testing purposes) and on multiple machines. The resulting "cluster plans"
can be used by the kickstarter to start up the processes comprising
the cluster, including the agency. To this end, there has to be one
dispatcher on every machine participating in the cluster. A dispatcher
is a simple instance of ArangoDB, compiled with the cluster extensions,
but not running in cluster mode. This is why the configuration option
*dispatchers* below is of central importance.
- *dispatchers*: an object with a property for each dispatcher,
the property name is the ID of the dispatcher and the value
should be an object with at least the property *endpoint*
containing the endpoint of the corresponding dispatcher.
Further optional properties are:
- *avoidPorts* which is an object
in which all port numbers that should not be used are bound to
*true*, default is empty, that is, all ports can be used
- *arangodExtraArgs*, which is a list of additional
command line arguments that will be given to DBservers and
coordinators started by this dispatcher, the default is
an empty list. These arguments will be appended to those
produced automatically, such that one can overwrite
things with this.
- *allowCoordinators*, which is a boolean value indicating
whether or not coordinators should be started on this
dispatcher, the default is *true*
- *allowDBservers*, which is a boolean value indicating
whether or not DBservers should be started on this dispatcher,
the default is *true*
- *allowAgents*, which is a boolean value indicating whether or
not agents should be started on this dispatcher, the default is
*true*
- *username*, which is a string that contains the user name
for authentication with this dispatcher
- *passwd*, which is a string that contains the password
for authentication with this dispatcher, if not both
*username* and *passwd* are set, then no authentication
is used between dispatchers. Note that this will not work
if the dispatchers are configured with authentication.
If *.dispatchers* is empty (no property), then an entry for the
local arangod itself is automatically added. Note that if the
only configured dispatcher has endpoint *tcp://localhost:*,
all processes are started in a special "local" mode and are
configured to bind their endpoints only to the localhost device.
In all other cases both agents and *arangod* instances bind
their endpoints to all available network devices.
- *numberOfAgents*: the number of agents in the agency,
usually there is no reason to deviate from the default of 3. The
planner distributes them amongst the dispatchers, if possible.
- *agencyPrefix*: a string that is used as prefix for all keys of
configuration data stored in the agency.
- *numberOfDBservers*: the number of DBservers in the
cluster. The planner distributes them evenly amongst the dispatchers.
- *startSecondaries*: a boolean flag indicating whether or not
secondary servers are started. In this version, this flag is
silently ignored, since we do not yet have secondary servers.
- *numberOfCoordinators*: the number of coordinators in the cluster,
the planner distributes them evenly amongst the dispatchers.
- *DBserverIDs*: a list of DBserver IDs (strings). If the planner
runs out of IDs it creates its own ones using *DBserver*
concatenated with a unique number.
- *coordinatorIDs*: a list of coordinator IDs (strings). If the planner
runs out of IDs it creates its own ones using *Coordinator*
concatenated with a unique number.
- *dataPath*: this is a string and describes the path under which
the agents, the DBservers and the coordinators store their
data directories. This can either be an absolute path (in which
case all machines in the clusters must use the same path), or
it can be a relative path. In the latter case it is relative
to the directory that is configured in the dispatcher with the
*cluster.data-path* option (command line or configuration file).
The directories created will be called *data-PREFIX-ID* where
*PREFIX* is replaced with the agency prefix (see above) and *ID*
is the ID of the DBserver or coordinator.
- *logPath*: this is a string and describes the path under which
the DBservers and the coordinators store their log file. This can
either be an absolute path (in which case all machines in the cluster
must use the same path), or it can be a relative path. In the
latter case it is relative to the directory that is configured
in the dispatcher with the *cluster.log-path* option.
- *arangodPath*: this is a string and describes the path to the
actual executable *arangod* that will be started for the
DBservers and coordinators. If this is an absolute path, it
obviously has to be the same on all machines in the cluster
as described for *dataPath*. If it is an empty string, the
dispatcher uses the executable that is configured with the
*cluster.arangod-path* option, which is by default the same
executable as the dispatcher uses.
- *agentPath*: this is a string and describes the path to the
actual executable that will be started for the agents in the
agency. If this is an absolute path, it obviously has to be
the same on all machines in the cluster, as described for
*arangodPath*. If it is an empty string, the dispatcher
uses its *cluster.agent-path* option.
- *agentExtPorts*: a list of port numbers to use for the external
ports of the agents. When running out of numbers in this list,
the planner increments the last one used by one for every port
needed. Note that the planner checks availability of the ports
during the planning phase by contacting the dispatchers on the
different machines, and uses only ports that are free during
the planning phase. Obviously, if those ports are connected
before the actual startup, things can go wrong.
- *agentIntPorts*: a list of port numbers to use for the internal
ports of the agents. The same comments as for *agentExtPorts*
apply.
- *DBserverPorts*: a list of port numbers to use for the
DBservers. The same comments as for *agentExtPorts* apply.
- *coordinatorPorts*: a list of port numbers to use for the
coordinators. The same comments as for *agentExtPorts* apply.
- *useSSLonDBservers*: a boolean flag indicating whether or not
we use SSL on all DBservers in the cluster
- *useSSLonCoordinators*: a boolean flag indicating whether or not
we use SSL on all coordinators in the cluster
- *valgrind*: a string to contain the path of the valgrind binary
if we should run the cluster components in it
- *valgrindopts*: commandline options to the valgrind process
- *valgrindXmlFileBase*: pattern for logfiles
- *valgrindTestname*: name of test to add to the logfiles
- *valgrindHosts*: which host classes should run in valgrind?
Coordinator / DBServer
- *extremeVerbosity* : if set to true, then there will be more test
run output, especially for cluster tests.
All these values have default values. Here is the current set of
default values:
```js
{
"agencyPrefix" : "arango",
"numberOfAgents" : 1,
"numberOfDBservers" : 2,
"startSecondaries" : false,
"numberOfCoordinators" : 1,
"DBserverIDs" : ["Pavel", "Perry", "Pancho", "Paul", "Pierre",
"Pit", "Pia", "Pablo" ],
"coordinatorIDs" : ["Claus", "Chantalle", "Claire", "Claudia",
"Claas", "Clemens", "Chris" ],
"dataPath" : "", // means configured in dispatcher
"logPath" : "", // means configured in dispatcher
"arangodPath" : "", // means configured as dispatcher
"agentPath" : "", // means configured in dispatcher
"agentExtPorts" : [4001],
"agentIntPorts" : [7001],
"DBserverPorts" : [8629],
"coordinatorPorts" : [8530],
"dispatchers" : {"me": {"endpoint": "tcp://localhost:"}},
// this means only we as a local instance
"useSSLonDBservers" : false,
"useSSLonCoordinators" : false
};
```

23
Documentation/DocuBlocks/JSF_Kickstarter_prototype_cleanup.md
View File

@ -1,12 +1,11 @@
////////////////////////////////////////////////////////////////////////////////
/// @startDocuBlock JSF_Kickstarter_prototype_cleanup
///
/// `Kickstarter.cleanup()`
///
/// This cleans up all the data and logs of a previously shut down cluster.
/// To this end, other dispatchers are contacted as necessary.
/// [Use shutdown](../ModulePlanner/README.md#shutdown) first and
/// use with caution, since potentially a lot of data is being erased with
/// this call!
/// @endDocuBlock
////////////////////////////////////////////////////////////////////////////////
`Kickstarter.cleanup()`
This cleans up all the data and logs of a previously shut down cluster.
To this end, other dispatchers are contacted as necessary.
[Use shutdown](../ModulePlanner/README.md#shutdown) first and
use with caution, since potentially a lot of data is being erased with
this call!

21
Documentation/DocuBlocks/JSF_Kickstarter_prototype_isHealthy.md
View File

@ -1,11 +1,10 @@
////////////////////////////////////////////////////////////////////////////////
/// @startDocuBlock JSF_Kickstarter_prototype_isHealthy
///
/// `Kickstarter.isHealthy()`
///
/// This checks that all processes belonging to a running cluster are
/// healthy. To this end, other dispatchers are contacted as necessary.
/// At this stage it is only checked that the processes are still up and
/// running.
/// @endDocuBlock
////////////////////////////////////////////////////////////////////////////////
`Kickstarter.isHealthy()`
This checks that all processes belonging to a running cluster are
healthy. To this end, other dispatchers are contacted as necessary.
At this stage it is only checked that the processes are still up and
running.

49
Documentation/DocuBlocks/JSF_Kickstarter_prototype_launch.md
View File

@ -1,25 +1,24 @@
////////////////////////////////////////////////////////////////////////////////
/// @startDocuBlock JSF_Kickstarter_prototype_launch
///
/// `Kickstarter.launch()`
///
/// This starts up a cluster as described in the plan which was given to
/// the constructor. To this end, other dispatchers are contacted as
/// necessary. All startup commands for the local dispatcher are
/// executed immediately.
///
/// The result is an object that contains information about the started
/// processes, this object is also stored in the Kickstarter object
/// itself. We do not go into details here about the data structure,
/// but the most important information are the process IDs of the
/// started processes. The corresponding
/// [see shutdown method](../ModulePlanner/README.md#shutdown) needs this
/// information to shut down all processes.
///
/// Note that all data in the DBservers and all log files and all agency
/// information in the cluster is deleted by this call. This is because
/// it is intended to set up a cluster for the first time. See
/// the [relaunch method](../ModulePlanner/README.md#relaunch)
/// for restarting a cluster without data loss.
/// @endDocuBlock
////////////////////////////////////////////////////////////////////////////////
`Kickstarter.launch()`
This starts up a cluster as described in the plan which was given to
the constructor. To this end, other dispatchers are contacted as
necessary. All startup commands for the local dispatcher are
executed immediately.
The result is an object that contains information about the started
processes, this object is also stored in the Kickstarter object
itself. We do not go into details here about the data structure,
but the most important information are the process IDs of the
started processes. The corresponding
[see shutdown method](../ModulePlanner/README.md#shutdown) needs this
information to shut down all processes.
Note that all data in the DBservers and all log files and all agency
information in the cluster is deleted by this call. This is because
it is intended to set up a cluster for the first time. See
the [relaunch method](../ModulePlanner/README.md#relaunch)
for restarting a cluster without data loss.

47
Documentation/DocuBlocks/JSF_Kickstarter_prototype_relaunch.md
View File

@ -1,24 +1,23 @@
////////////////////////////////////////////////////////////////////////////////
/// @startDocuBlock JSF_Kickstarter_prototype_relaunch
///
/// `Kickstarter.relaunch()`
///
/// This starts up a cluster as described in the plan which was given to
/// the constructor. To this end, other dispatchers are contacted as
/// necessary. All startup commands for the local dispatcher are
/// executed immediately.
///
/// The result is an object that contains information about the started
/// processes, this object is also stored in the Kickstarter object
/// itself. We do not go into details here about the data structure,
/// but the most important information are the process IDs of the
/// started processes. The corresponding
/// [shutdown method ](../ModulePlanner/README.md#shutdown) needs this information to
/// shut down all processes.
///
/// Note that this methods needs that all data in the DBservers and the
/// agency information in the cluster are already set up properly. See
/// the [launch method](../ModulePlanner/README.md#launch) for
/// starting a cluster for the first time.
/// @endDocuBlock
////////////////////////////////////////////////////////////////////////////////
`Kickstarter.relaunch()`
This starts up a cluster as described in the plan which was given to
the constructor. To this end, other dispatchers are contacted as
necessary. All startup commands for the local dispatcher are
executed immediately.
The result is an object that contains information about the started
processes, this object is also stored in the Kickstarter object
itself. We do not go into details here about the data structure,
but the most important information are the process IDs of the
started processes. The corresponding
[shutdown method ](../ModulePlanner/README.md#shutdown) needs this information to
shut down all processes.
Note that this methods needs that all data in the DBservers and the
agency information in the cluster are already set up properly. See
the [launch method](../ModulePlanner/README.md#launch) for
starting a cluster for the first time.

21
Documentation/DocuBlocks/JSF_Kickstarter_prototype_shutdown.md
View File

@ -1,11 +1,10 @@
////////////////////////////////////////////////////////////////////////////////
/// @startDocuBlock JSF_Kickstarter_prototype_shutdown
///
/// `Kickstarter.shutdown()`
///
/// This shuts down a cluster as described in the plan which was given to
/// the constructor. To this end, other dispatchers are contacted as
/// necessary. All processes in the cluster are gracefully shut down
/// in the right order.
/// @endDocuBlock
////////////////////////////////////////////////////////////////////////////////
`Kickstarter.shutdown()`
This shuts down a cluster as described in the plan which was given to
the constructor. To this end, other dispatchers are contacted as
necessary. All processes in the cluster are gracefully shut down
in the right order.

57
Documentation/DocuBlocks/JSF_Kickstarter_prototype_upgrade.md
View File

@ -1,29 +1,28 @@
////////////////////////////////////////////////////////////////////////////////
/// @startDocuBlock JSF_Kickstarter_prototype_upgrade
///
/// `Kickstarter.upgrade(username, passwd)`
///
/// This performs an upgrade procedure on a cluster as described in
/// the plan which was given to the constructor. To this end, other
/// dispatchers are contacted as necessary. All commands for the local
/// dispatcher are executed immediately. The basic approach for the
/// upgrade is as follows: The agency is started first (exactly as
/// in relaunch), no configuration is sent there (exactly as in the
/// relaunch action), all servers are first started with the option
/// "--upgrade" and then normally. In the end, the upgrade-database.js
/// script is run on one of the coordinators, as in the launch action.
///
/// The result is an object that contains information about the started
/// processes, this object is also stored in the Kickstarter object
/// itself. We do not go into details here about the data structure,
/// but the most important information are the process IDs of the
/// started processes. The corresponding
/// [shutdown method](../ModulePlanner/README.md#shutdown) needs
/// this information to shut down all processes.
///
/// Note that this methods needs that all data in the DBservers and the
/// agency information in the cluster are already set up properly. See
/// the [launch method](../ModulePlanner/README.md#launch) for
/// starting a cluster for the first time.
/// @endDocuBlock
////////////////////////////////////////////////////////////////////////////////
`Kickstarter.upgrade(username, passwd)`
This performs an upgrade procedure on a cluster as described in
the plan which was given to the constructor. To this end, other
dispatchers are contacted as necessary. All commands for the local
dispatcher are executed immediately. The basic approach for the
upgrade is as follows: The agency is started first (exactly as
in relaunch), no configuration is sent there (exactly as in the
relaunch action), all servers are first started with the option
"--upgrade" and then normally. In the end, the upgrade-database.js
script is run on one of the coordinators, as in the launch action.
The result is an object that contains information about the started
processes, this object is also stored in the Kickstarter object
itself. We do not go into details here about the data structure,
but the most important information are the process IDs of the
started processes. The corresponding
[shutdown method](../ModulePlanner/README.md#shutdown) needs
this information to shut down all processes.
Note that this methods needs that all data in the DBservers and the
agency information in the cluster are already set up properly. See
the [launch method](../ModulePlanner/README.md#launch) for
starting a cluster for the first time.

17
Documentation/DocuBlocks/JSF_Planner_prototype_getPlan.md
View File

@ -1,9 +1,8 @@
////////////////////////////////////////////////////////////////////////////////
/// @startDocuBlock JSF_Planner_prototype_getPlan
///
/// `Planner.getPlan()`
///
/// returns the cluster plan as a JavaScript object. The result of this
/// method can be given to the constructor of a Kickstarter.
/// @endDocuBlock
////////////////////////////////////////////////////////////////////////////////
`Planner.getPlan()`
returns the cluster plan as a JavaScript object. The result of this
method can be given to the constructor of a Kickstarter.

121
Documentation/DocuBlocks/JSF_aql_general_graph_absolute_betweenness.md
View File

@ -1,61 +1,60 @@
////////////////////////////////////////////////////////////////////////////////
/// @startDocuBlock JSF_aql_general_graph_absolute_betweenness
///
/// `GRAPH_ABSOLUTE_BETWEENNESS (graphName, options)`
///
/// The GRAPH\_ABSOLUTE\_BETWEENNESS function returns the
/// [betweenness](http://en.wikipedia.org/wiki/Betweenness_centrality)
/// of all vertices in the graph.
///
/// The complexity of the function is described
/// [here](#the-complexity-of-the-shortest-path-algorithms).
///
///
/// * *graphName* : The name of the graph as a string.
/// * *options* : An object containing the following options:
/// * *direction* : The direction of the edges.
/// Possible values are *outbound*, *inbound* and *any* (default).
/// * *weight* : The name of the attribute of
/// the edges containing the length.
/// * *defaultWeight* : Only used with the option *weight*.
/// If an edge does not have the attribute named as defined in option *weight* this default
/// is used as length.
/// If no default is supplied the default would be positive Infinity so the path and
/// hence the betweenness can not be calculated.
///
/// @EXAMPLES
///
/// A route planner example, the absolute betweenness of all locations.
///
/// @EXAMPLE_ARANGOSH_OUTPUT{generalGraphAbsBetweenness1}
/// var examples = require("@arangodb/graph-examples/example-graph.js");
/// var g = examples.loadGraph("routeplanner");
/// db._query("RETURN GRAPH_ABSOLUTE_BETWEENNESS('routeplanner', {})").toArray();
/// ~ examples.dropGraph("routeplanner");
/// @END_EXAMPLE_ARANGOSH_OUTPUT
///
/// A route planner example, the absolute betweenness of all locations.
/// This considers the actual distances.
///
/// @EXAMPLE_ARANGOSH_OUTPUT{generalGraphAbsBetweenness2}
/// var examples = require("@arangodb/graph-examples/example-graph.js");
/// var g = examples.loadGraph("routeplanner");
/// | db._query("RETURN GRAPH_ABSOLUTE_BETWEENNESS("
/// +"'routeplanner', {weight : 'distance'})").toArray();
/// ~ examples.dropGraph("routeplanner");
/// @END_EXAMPLE_ARANGOSH_OUTPUT
///
/// A route planner example, the absolute closeness regarding only
/// outbound paths.
///
/// @EXAMPLE_ARANGOSH_OUTPUT{generalGraphAbsBetweenness3}
/// var examples = require("@arangodb/graph-examples/example-graph.js");
/// var g = examples.loadGraph("routeplanner");
/// | db._query("RETURN GRAPH_ABSOLUTE_BETWEENNESS("
/// | + "'routeplanner', {direction : 'outbound', weight : 'distance'})"
/// ).toArray();
/// ~ examples.dropGraph("routeplanner");
/// @END_EXAMPLE_ARANGOSH_OUTPUT
///
/// @endDocuBlock
////////////////////////////////////////////////////////////////////////////////
`GRAPH_ABSOLUTE_BETWEENNESS (graphName, options)`
The GRAPH\_ABSOLUTE\_BETWEENNESS function returns the
[betweenness](http://en.wikipedia.org/wiki/Betweenness_centrality)
of all vertices in the graph.
The complexity of the function is described
[here](#the-complexity-of-the-shortest-path-algorithms).
* *graphName* : The name of the graph as a string.
* *options* : An object containing the following options:
* *direction* : The direction of the edges.
Possible values are *outbound*, *inbound* and *any* (default).
* *weight* : The name of the attribute of
the edges containing the length.
* *defaultWeight* : Only used with the option *weight*.
If an edge does not have the attribute named as defined in option *weight* this default
is used as length.
If no default is supplied the default would be positive Infinity so the path and
hence the betweenness can not be calculated.
@EXAMPLES
A route planner example, the absolute betweenness of all locations.
@EXAMPLE_ARANGOSH_OUTPUT{generalGraphAbsBetweenness1}
var examples = require("@arangodb/graph-examples/example-graph.js");
var g = examples.loadGraph("routeplanner");
db._query("RETURN GRAPH_ABSOLUTE_BETWEENNESS('routeplanner', {})").toArray();
~ examples.dropGraph("routeplanner");
@END_EXAMPLE_ARANGOSH_OUTPUT
A route planner example, the absolute betweenness of all locations.
This considers the actual distances.
@EXAMPLE_ARANGOSH_OUTPUT{generalGraphAbsBetweenness2}
var examples = require("@arangodb/graph-examples/example-graph.js");
var g = examples.loadGraph("routeplanner");
| db._query("RETURN GRAPH_ABSOLUTE_BETWEENNESS("
+"'routeplanner', {weight : 'distance'})").toArray();
~ examples.dropGraph("routeplanner");
@END_EXAMPLE_ARANGOSH_OUTPUT
A route planner example, the absolute closeness regarding only
outbound paths.
@EXAMPLE_ARANGOSH_OUTPUT{generalGraphAbsBetweenness3}
var examples = require("@arangodb/graph-examples/example-graph.js");
var g = examples.loadGraph("routeplanner");
| db._query("RETURN GRAPH_ABSOLUTE_BETWEENNESS("
| + "'routeplanner', {direction : 'outbound', weight : 'distance'})"
).toArray();
~ examples.dropGraph("routeplanner");
@END_EXAMPLE_ARANGOSH_OUTPUT

157
Documentation/DocuBlocks/JSF_aql_general_graph_absolute_closeness.md
View File

@ -1,79 +1,78 @@
////////////////////////////////////////////////////////////////////////////////
/// @startDocuBlock JSF_aql_general_graph_absolute_closeness
///
/// `GRAPH_ABSOLUTE_CLOSENESS (graphName, vertexExample, options)`
///
/// The GRAPH\_ABSOLUTE\_CLOSENESS function returns the
/// [closeness](http://en.wikipedia.org/wiki/Centrality#Closeness-centrality)
/// of the vertices defined by the examples.
///
/// The complexity of the function is described
/// [here](#the-complexity-of-the-shortest-path-algorithms).
///
/// *Parameters*
///
/// * *graphName* : The name of the graph as a string.
/// * *vertexExample* : An example for the desired
/// vertices (see [example](#short-explanation-of-the-example-parameter)).
/// * *options* : An object containing the following options:
/// * *direction* : The direction of the edges.
/// Possible values are *outbound*, *inbound* and *any* (default).
/// * *edgeCollectionRestriction* : One or multiple edge
/// collection names. Only edges from these collections will be considered for the path.
/// * *startVertexCollectionRestriction* : One or multiple vertex
/// collection names. Only vertices from these collections will be considered as
/// start vertex of a path.
/// * *endVertexCollectionRestriction* : One or multiple vertex
/// collection names. Only vertices from these collections will be considered as
/// end vertex of a path.
/// * *edgeExamples* : A filter example for the
/// edges in the shortest paths (
/// see [example](#short-explanation-of-the-example-parameter)).
/// * *algorithm* : The algorithm to calculate
/// the shortest paths. Possible values are
/// [Floyd-Warshall](http://en.wikipedia.org/wiki/Floyd%E2%80%93Warshall_algorithm) (default)
/// and [Dijkstra](http://en.wikipedia.org/wiki/Dijkstra's_algorithm).
/// * *weight* : The name of the attribute of
/// the edges containing the length.
/// * *defaultWeight* : Only used with the option *weight*.
/// If an edge does not have the attribute named as defined in option *weight* this default
/// is used as length.
/// If no default is supplied the default would be positive Infinity so the path and
/// hence the eccentricity can not be calculated.
///
/// @EXAMPLES
///
/// A route planner example, the absolute closeness of all locations.
///
/// @EXAMPLE_ARANGOSH_OUTPUT{generalGraphAbsCloseness1}
/// var examples = require("@arangodb/graph-examples/example-graph.js");
/// var g = examples.loadGraph("routeplanner");
/// db._query("RETURN GRAPH_ABSOLUTE_CLOSENESS('routeplanner', {})").toArray();
/// ~ examples.dropGraph("routeplanner");
/// @END_EXAMPLE_ARANGOSH_OUTPUT
///
/// A route planner example, the absolute closeness of all locations.
/// This considers the actual distances.
///
/// @EXAMPLE_ARANGOSH_OUTPUT{generalGraphAbsCloseness2}
/// var examples = require("@arangodb/graph-examples/example-graph.js");
/// var g = examples.loadGraph("routeplanner");
/// | db._query("RETURN GRAPH_ABSOLUTE_CLOSENESS("
/// +"'routeplanner', {}, {weight : 'distance'})").toArray();
/// ~ examples.dropGraph("routeplanner");
/// @END_EXAMPLE_ARANGOSH_OUTPUT
///
/// A route planner example, the absolute closeness of all German cities regarding only
/// outbound paths.
///
/// @EXAMPLE_ARANGOSH_OUTPUT{generalGraphAbsCloseness3}
/// var examples = require("@arangodb/graph-examples/example-graph.js");
/// var g = examples.loadGraph("routeplanner");
/// | db._query("RETURN GRAPH_ABSOLUTE_CLOSENESS("
/// | + "'routeplanner', {}, {startVertexCollectionRestriction : 'germanCity', " +
/// "direction : 'outbound', weight : 'distance'})").toArray();
/// ~ examples.dropGraph("routeplanner");
/// @END_EXAMPLE_ARANGOSH_OUTPUT
///
/// @endDocuBlock
////////////////////////////////////////////////////////////////////////////////
`GRAPH_ABSOLUTE_CLOSENESS (graphName, vertexExample, options)`
The GRAPH\_ABSOLUTE\_CLOSENESS function returns the
[closeness](http://en.wikipedia.org/wiki/Centrality#Closeness-centrality)
of the vertices defined by the examples.
The complexity of the function is described
[here](#the-complexity-of-the-shortest-path-algorithms).
*Parameters*
* *graphName* : The name of the graph as a string.
* *vertexExample* : An example for the desired
vertices (see [example](#short-explanation-of-the-example-parameter)).
* *options* : An object containing the following options:
* *direction* : The direction of the edges.
Possible values are *outbound*, *inbound* and *any* (default).
* *edgeCollectionRestriction* : One or multiple edge
collection names. Only edges from these collections will be considered for the path.
* *startVertexCollectionRestriction* : One or multiple vertex
collection names. Only vertices from these collections will be considered as
start vertex of a path.
* *endVertexCollectionRestriction* : One or multiple vertex
collection names. Only vertices from these collections will be considered as
end vertex of a path.
* *edgeExamples* : A filter example for the
edges in the shortest paths (
see [example](#short-explanation-of-the-example-parameter)).
* *algorithm* : The algorithm to calculate
the shortest paths. Possible values are
[Floyd-Warshall](http://en.wikipedia.org/wiki/Floyd%E2%80%93Warshall_algorithm) (default)
and [Dijkstra](http://en.wikipedia.org/wiki/Dijkstra's_algorithm).
* *weight* : The name of the attribute of
the edges containing the length.
* *defaultWeight* : Only used with the option *weight*.
If an edge does not have the attribute named as defined in option *weight* this default
is used as length.
If no default is supplied the default would be positive Infinity so the path and
hence the eccentricity can not be calculated.
@EXAMPLES
A route planner example, the absolute closeness of all locations.
@EXAMPLE_ARANGOSH_OUTPUT{generalGraphAbsCloseness1}
var examples = require("@arangodb/graph-examples/example-graph.js");
var g = examples.loadGraph("routeplanner");
db._query("RETURN GRAPH_ABSOLUTE_CLOSENESS('routeplanner', {})").toArray();
~ examples.dropGraph("routeplanner");
@END_EXAMPLE_ARANGOSH_OUTPUT
A route planner example, the absolute closeness of all locations.
This considers the actual distances.
@EXAMPLE_ARANGOSH_OUTPUT{generalGraphAbsCloseness2}
var examples = require("@arangodb/graph-examples/example-graph.js");
var g = examples.loadGraph("routeplanner");
| db._query("RETURN GRAPH_ABSOLUTE_CLOSENESS("
+"'routeplanner', {}, {weight : 'distance'})").toArray();
~ examples.dropGraph("routeplanner");
@END_EXAMPLE_ARANGOSH_OUTPUT
A route planner example, the absolute closeness of all German cities regarding only
outbound paths.
@EXAMPLE_ARANGOSH_OUTPUT{generalGraphAbsCloseness3}
var examples = require("@arangodb/graph-examples/example-graph.js");
var g = examples.loadGraph("routeplanner");
| db._query("RETURN GRAPH_ABSOLUTE_CLOSENESS("
| + "'routeplanner', {}, {startVertexCollectionRestriction : 'germanCity', " +
"direction : 'outbound', weight : 'distance'})").toArray();
~ examples.dropGraph("routeplanner");
@END_EXAMPLE_ARANGOSH_OUTPUT

157
Documentation/DocuBlocks/JSF_aql_general_graph_absolute_eccentricity.md
View File

@ -1,79 +1,78 @@
////////////////////////////////////////////////////////////////////////////////
/// @startDocuBlock JSF_aql_general_graph_absolute_eccentricity
///
/// `GRAPH_ABSOLUTE_ECCENTRICITY (graphName, vertexExample, options)`
///
/// The GRAPH\_ABSOLUTE\_ECCENTRICITY function returns the
/// [eccentricity](http://en.wikipedia.org/wiki/Distance_%28graph_theory%29)
/// of the vertices defined by the examples.
///
/// The complexity of the function is described
/// [here](#the-complexity-of-the-shortest-path-algorithms).
///
/// *Parameters*
///
/// * *graphName* : The name of the graph as a string.
/// * *vertexExample* : An example for the desired
/// vertices (see [example](#short-explanation-of-the-example-parameter)).
/// * *options* (optional) : An object containing the following options:
/// * *direction* : The direction of the edges as a string.
/// Possible values are *outbound*, *inbound* and *any* (default).
/// * *edgeCollectionRestriction* : One or multiple edge
/// collection names. Only edges from these collections will be considered for the path.
/// * *startVertexCollectionRestriction* : One or multiple vertex
/// collection names. Only vertices from these collections will be considered as
/// start vertex of a path.
/// * *endVertexCollectionRestriction* : One or multiple vertex
/// collection names. Only vertices from these collections will be considered as
/// end vertex of a path.
/// * *edgeExamples* : A filter example for the edges in the
/// shortest paths (see [example](#short-explanation-of-the-example-parameter)).
/// * *algorithm* : The algorithm to calculate
/// the shortest paths as a string. If vertex example is empty
/// [Floyd-Warshall](http://en.wikipedia.org/wiki/Floyd%E2%80%93Warshall_algorithm) is
/// used as default, otherwise the default is
/// [Dijkstra](http://en.wikipedia.org/wiki/Dijkstra's_algorithm)
/// * *weight* : The name of the attribute of
/// the edges containing the length as a string.
/// * *defaultWeight* : Only used with the option *weight*.
/// If an edge does not have the attribute named as defined in option *weight* this default
/// is used as length.
/// If no default is supplied the default would be positive Infinity so the path and
/// hence the eccentricity can not be calculated.
///
/// @EXAMPLES
///
/// A route planner example, the absolute eccentricity of all locations.
///
/// @EXAMPLE_ARANGOSH_OUTPUT{generalGraphAbsEccentricity1}
/// var examples = require("@arangodb/graph-examples/example-graph.js");
/// var g = examples.loadGraph("routeplanner");
/// db._query("RETURN GRAPH_ABSOLUTE_ECCENTRICITY('routeplanner', {})").toArray();
/// ~ examples.dropGraph("routeplanner");
/// @END_EXAMPLE_ARANGOSH_OUTPUT
///
/// A route planner example, the absolute eccentricity of all locations.
/// This considers the actual distances.
///
/// @EXAMPLE_ARANGOSH_OUTPUT{generalGraphAbsEccentricity2}
/// var examples = require("@arangodb/graph-examples/example-graph.js");
/// var g = examples.loadGraph("routeplanner");
/// | db._query("RETURN GRAPH_ABSOLUTE_ECCENTRICITY("
/// +"'routeplanner', {}, {weight : 'distance'})").toArray();
/// ~ examples.dropGraph("routeplanner");
/// @END_EXAMPLE_ARANGOSH_OUTPUT
///
/// A route planner example, the absolute eccentricity of all German cities regarding only
/// outbound paths.
///
/// @EXAMPLE_ARANGOSH_OUTPUT{generalGraphAbsEccentricity3}
/// var examples = require("@arangodb/graph-examples/example-graph.js");
/// var g = examples.loadGraph("routeplanner");
/// | db._query("RETURN GRAPH_ABSOLUTE_ECCENTRICITY("
/// | + "'routeplanner', {}, {startVertexCollectionRestriction : 'germanCity', " +
/// "direction : 'outbound', weight : 'distance'})").toArray();
/// ~ examples.dropGraph("routeplanner");
/// @END_EXAMPLE_ARANGOSH_OUTPUT
///
/// @endDocuBlock
////////////////////////////////////////////////////////////////////////////////
`GRAPH_ABSOLUTE_ECCENTRICITY (graphName, vertexExample, options)`
The GRAPH\_ABSOLUTE\_ECCENTRICITY function returns the
[eccentricity](http://en.wikipedia.org/wiki/Distance_%28graph_theory%29)
of the vertices defined by the examples.
The complexity of the function is described
[here](#the-complexity-of-the-shortest-path-algorithms).
*Parameters*
* *graphName* : The name of the graph as a string.
* *vertexExample* : An example for the desired
vertices (see [example](#short-explanation-of-the-example-parameter)).
* *options* (optional) : An object containing the following options:
* *direction* : The direction of the edges as a string.
Possible values are *outbound*, *inbound* and *any* (default).
* *edgeCollectionRestriction* : One or multiple edge
collection names. Only edges from these collections will be considered for the path.
* *startVertexCollectionRestriction* : One or multiple vertex
collection names. Only vertices from these collections will be considered as
start vertex of a path.
* *endVertexCollectionRestriction* : One or multiple vertex
collection names. Only vertices from these collections will be considered as
end vertex of a path.
* *edgeExamples* : A filter example for the edges in the
shortest paths (see [example](#short-explanation-of-the-example-parameter)).
* *algorithm* : The algorithm to calculate
the shortest paths as a string. If vertex example is empty
[Floyd-Warshall](http://en.wikipedia.org/wiki/Floyd%E2%80%93Warshall_algorithm) is
used as default, otherwise the default is
[Dijkstra](http://en.wikipedia.org/wiki/Dijkstra's_algorithm)
* *weight* : The name of the attribute of
the edges containing the length as a string.
* *defaultWeight* : Only used with the option *weight*.
If an edge does not have the attribute named as defined in option *weight* this default
is used as length.
If no default is supplied the default would be positive Infinity so the path and
hence the eccentricity can not be calculated.
@EXAMPLES
A route planner example, the absolute eccentricity of all locations.
@EXAMPLE_ARANGOSH_OUTPUT{generalGraphAbsEccentricity1}
var examples = require("@arangodb/graph-examples/example-graph.js");
var g = examples.loadGraph("routeplanner");
db._query("RETURN GRAPH_ABSOLUTE_ECCENTRICITY('routeplanner', {})").toArray();
~ examples.dropGraph("routeplanner");
@END_EXAMPLE_ARANGOSH_OUTPUT
A route planner example, the absolute eccentricity of all locations.
This considers the actual distances.
@EXAMPLE_ARANGOSH_OUTPUT{generalGraphAbsEccentricity2}
var examples = require("@arangodb/graph-examples/example-graph.js");
var g = examples.loadGraph("routeplanner");
| db._query("RETURN GRAPH_ABSOLUTE_ECCENTRICITY("
+"'routeplanner', {}, {weight : 'distance'})").toArray();
~ examples.dropGraph("routeplanner");
@END_EXAMPLE_ARANGOSH_OUTPUT
A route planner example, the absolute eccentricity of all German cities regarding only
outbound paths.
@EXAMPLE_ARANGOSH_OUTPUT{generalGraphAbsEccentricity3}
var examples = require("@arangodb/graph-examples/example-graph.js");
var g = examples.loadGraph("routeplanner");
| db._query("RETURN GRAPH_ABSOLUTE_ECCENTRICITY("
| + "'routeplanner', {}, {startVertexCollectionRestriction : 'germanCity', " +
"direction : 'outbound', weight : 'distance'})").toArray();
~ examples.dropGraph("routeplanner");
@END_EXAMPLE_ARANGOSH_OUTPUT

119
Documentation/DocuBlocks/JSF_aql_general_graph_betweenness.md
View File

@ -1,60 +1,59 @@
////////////////////////////////////////////////////////////////////////////////
/// @startDocuBlock JSF_aql_general_graph_betweenness
///
/// `GRAPH_BETWEENNESS (graphName, options)`
///
/// The GRAPH\_BETWEENNESS function returns the
/// [betweenness](http://en.wikipedia.org/wiki/Betweenness_centrality)
/// of graphs vertices.
///
/// The complexity of the function is described
/// [here](#the-complexity-of-the-shortest-path-algorithms).
///
/// *Parameters*
///
/// * *graphName* : The name of the graph as a string.
/// * *options* : An object containing the following options:
/// * *direction* : The direction of the edges.
/// Possible values are *outbound*, *inbound* and *any* (default).
/// * *weight* : The name of the attribute of
/// the edges containing the length.
/// * *defaultWeight* : Only used with the option *weight*.
/// If an edge does not have the attribute named as defined in option *weight* this default
/// is used as length.
/// If no default is supplied the default would be positive Infinity so the path and
/// hence the eccentricity can not be calculated.
///
/// @EXAMPLES
///
/// A route planner example, the betweenness of all locations.
///
/// @EXAMPLE_ARANGOSH_OUTPUT{generalGraphBetweenness1}
/// var examples = require("@arangodb/graph-examples/example-graph.js");
/// var g = examples.loadGraph("routeplanner");
/// db._query("RETURN GRAPH_BETWEENNESS('routeplanner')").toArray();
/// ~ examples.dropGraph("routeplanner");
/// @END_EXAMPLE_ARANGOSH_OUTPUT
///
/// A route planner example, the betweenness of all locations.
/// This considers the actual distances.
///
/// @EXAMPLE_ARANGOSH_OUTPUT{generalGraphBetweenness2}
/// var examples = require("@arangodb/graph-examples/example-graph.js");
/// var g = examples.loadGraph("routeplanner");
/// db._query("RETURN GRAPH_BETWEENNESS('routeplanner', {weight : 'distance'})").toArray();
/// ~ examples.dropGraph("routeplanner");
/// @END_EXAMPLE_ARANGOSH_OUTPUT
///
/// A route planner example, the betweenness regarding only
/// outbound paths.
///
/// @EXAMPLE_ARANGOSH_OUTPUT{generalGraphBetweenness3}
/// var examples = require("@arangodb/graph-examples/example-graph.js");
/// var g = examples.loadGraph("routeplanner");
/// | db._query("RETURN GRAPH_BETWEENNESS("
/// + "'routeplanner', {direction : 'outbound', weight : 'distance'})").toArray();
/// ~ examples.dropGraph("routeplanner");
/// @END_EXAMPLE_ARANGOSH_OUTPUT
///
/// @endDocuBlock
////////////////////////////////////////////////////////////////////////////////
`GRAPH_BETWEENNESS (graphName, options)`
The GRAPH\_BETWEENNESS function returns the
[betweenness](http://en.wikipedia.org/wiki/Betweenness_centrality)
of graphs vertices.
The complexity of the function is described
[here](#the-complexity-of-the-shortest-path-algorithms).
*Parameters*
* *graphName* : The name of the graph as a string.
* *options* : An object containing the following options:
* *direction* : The direction of the edges.
Possible values are *outbound*, *inbound* and *any* (default).
* *weight* : The name of the attribute of
the edges containing the length.
* *defaultWeight* : Only used with the option *weight*.
If an edge does not have the attribute named as defined in option *weight* this default
is used as length.
If no default is supplied the default would be positive Infinity so the path and
hence the eccentricity can not be calculated.
@EXAMPLES
A route planner example, the betweenness of all locations.
@EXAMPLE_ARANGOSH_OUTPUT{generalGraphBetweenness1}
var examples = require("@arangodb/graph-examples/example-graph.js");
var g = examples.loadGraph("routeplanner");
db._query("RETURN GRAPH_BETWEENNESS('routeplanner')").toArray();
~ examples.dropGraph("routeplanner");
@END_EXAMPLE_ARANGOSH_OUTPUT
A route planner example, the betweenness of all locations.
This considers the actual distances.
@EXAMPLE_ARANGOSH_OUTPUT{generalGraphBetweenness2}
var examples = require("@arangodb/graph-examples/example-graph.js");
var g = examples.loadGraph("routeplanner");
db._query("RETURN GRAPH_BETWEENNESS('routeplanner', {weight : 'distance'})").toArray();
~ examples.dropGraph("routeplanner");
@END_EXAMPLE_ARANGOSH_OUTPUT
A route planner example, the betweenness regarding only
outbound paths.
@EXAMPLE_ARANGOSH_OUTPUT{generalGraphBetweenness3}
var examples = require("@arangodb/graph-examples/example-graph.js");
var g = examples.loadGraph("routeplanner");
| db._query("RETURN GRAPH_BETWEENNESS("
+ "'routeplanner', {direction : 'outbound', weight : 'distance'})").toArray();
~ examples.dropGraph("routeplanner");
@END_EXAMPLE_ARANGOSH_OUTPUT

131
Documentation/DocuBlocks/JSF_aql_general_graph_closeness.md
View File

@ -1,66 +1,65 @@
////////////////////////////////////////////////////////////////////////////////
/// @startDocuBlock JSF_aql_general_graph_closeness
///
/// `GRAPH_CLOSENESS (graphName, options)`
///
/// The GRAPH\_CLOSENESS function returns the normalized
/// [closeness](http://en.wikipedia.org/wiki/Centrality#Closeness-centrality)
/// of graphs vertices.
///
/// The complexity of the function is described
/// [here](#the-complexity-of-the-shortest-path-algorithms).
///
/// *Parameters*
///
/// * *graphName* : The name of the graph as a string.
/// * *options* : An object containing the following options:
/// * *direction* : The direction of the edges.
/// Possible values are *outbound*, *inbound* and *any* (default).
/// * *algorithm* : The algorithm to calculate
/// the shortest paths. Possible values are
/// [Floyd-Warshall](http://en.wikipedia.org/wiki/Floyd%E2%80%93Warshall_algorithm) (default)
/// and [Dijkstra](http://en.wikipedia.org/wiki/Dijkstra's_algorithm).
/// * *weight* : The name of the attribute of
/// the edges containing the length.
/// * *defaultWeight* : Only used with the option *weight*.
/// If an edge does not have the attribute named as defined in option *weight* this default
/// is used as length.
/// If no default is supplied the default would be positive Infinity so the path and
/// hence the eccentricity can not be calculated.
///
/// @EXAMPLES
///
/// A route planner example, the closeness of all locations.
///
/// @EXAMPLE_ARANGOSH_OUTPUT{generalGraphCloseness1}
/// var examples = require("@arangodb/graph-examples/example-graph.js");
/// var g = examples.loadGraph("routeplanner");
/// db._query("RETURN GRAPH_CLOSENESS('routeplanner')").toArray();
/// ~ examples.dropGraph("routeplanner");
/// @END_EXAMPLE_ARANGOSH_OUTPUT
///
/// A route planner example, the closeness of all locations.
/// This considers the actual distances.
///
/// @EXAMPLE_ARANGOSH_OUTPUT{generalGraphCloseness2}
/// var examples = require("@arangodb/graph-examples/example-graph.js");
/// var g = examples.loadGraph("routeplanner");
/// | db._query("RETURN GRAPH_CLOSENESS("
/// +"'routeplanner', {weight : 'distance'})").toArray();
/// ~ examples.dropGraph("routeplanner");
/// @END_EXAMPLE_ARANGOSH_OUTPUT
///
/// A route planner example, the absolute closeness of all cities regarding only
/// outbound paths.
///
/// @EXAMPLE_ARANGOSH_OUTPUT{generalGraphCloseness3}
/// var examples = require("@arangodb/graph-examples/example-graph.js");
/// var g = examples.loadGraph("routeplanner");
/// | db._query("RETURN GRAPH_CLOSENESS("
/// | + "'routeplanner',{direction : 'outbound', weight : 'distance'})"
/// ).toArray();
/// ~ examples.dropGraph("routeplanner");
/// @END_EXAMPLE_ARANGOSH_OUTPUT
///
/// @endDocuBlock
////////////////////////////////////////////////////////////////////////////////
`GRAPH_CLOSENESS (graphName, options)`
The GRAPH\_CLOSENESS function returns the normalized
[closeness](http://en.wikipedia.org/wiki/Centrality#Closeness-centrality)
of graphs vertices.
The complexity of the function is described
[here](#the-complexity-of-the-shortest-path-algorithms).
*Parameters*
* *graphName* : The name of the graph as a string.
* *options* : An object containing the following options:
* *direction* : The direction of the edges.
Possible values are *outbound*, *inbound* and *any* (default).
* *algorithm* : The algorithm to calculate
the shortest paths. Possible values are
[Floyd-Warshall](http://en.wikipedia.org/wiki/Floyd%E2%80%93Warshall_algorithm) (default)
and [Dijkstra](http://en.wikipedia.org/wiki/Dijkstra's_algorithm).
* *weight* : The name of the attribute of
the edges containing the length.
* *defaultWeight* : Only used with the option *weight*.
If an edge does not have the attribute named as defined in option *weight* this default
is used as length.
If no default is supplied the default would be positive Infinity so the path and
hence the eccentricity can not be calculated.
@EXAMPLES
A route planner example, the closeness of all locations.
@EXAMPLE_ARANGOSH_OUTPUT{generalGraphCloseness1}
var examples = require("@arangodb/graph-examples/example-graph.js");
var g = examples.loadGraph("routeplanner");
db._query("RETURN GRAPH_CLOSENESS('routeplanner')").toArray();
~ examples.dropGraph("routeplanner");
@END_EXAMPLE_ARANGOSH_OUTPUT
A route planner example, the closeness of all locations.
This considers the actual distances.
@EXAMPLE_ARANGOSH_OUTPUT{generalGraphCloseness2}
var examples = require("@arangodb/graph-examples/example-graph.js");
var g = examples.loadGraph("routeplanner");
| db._query("RETURN GRAPH_CLOSENESS("
+"'routeplanner', {weight : 'distance'})").toArray();
~ examples.dropGraph("routeplanner");
@END_EXAMPLE_ARANGOSH_OUTPUT
A route planner example, the absolute closeness of all cities regarding only
outbound paths.
@EXAMPLE_ARANGOSH_OUTPUT{generalGraphCloseness3}
var examples = require("@arangodb/graph-examples/example-graph.js");
var g = examples.loadGraph("routeplanner");
| db._query("RETURN GRAPH_CLOSENESS("
| + "'routeplanner',{direction : 'outbound', weight : 'distance'})"
).toArray();
~ examples.dropGraph("routeplanner");
@END_EXAMPLE_ARANGOSH_OUTPUT

91
Documentation/DocuBlocks/JSF_aql_general_graph_common_neighbors.md
View File

@ -1,46 +1,45 @@
////////////////////////////////////////////////////////////////////////////////
/// @startDocuBlock JSF_aql_general_graph_common_neighbors
/// The GRAPH\_COMMON\_NEIGHBORS function returns all common neighbors of the vertices
/// defined by the examples.
///
/// `GRAPH_COMMON_NEIGHBORS (graphName, vertex1Example, vertex2Examples,
/// optionsVertex1, optionsVertex2)`
///
/// This function returns the intersection of *GRAPH_NEIGHBORS(vertex1Example, optionsVertex1)*
/// and *GRAPH_NEIGHBORS(vertex2Example, optionsVertex2)*.
/// The complexity of this method is **O(n\*m^x)** with *n* being the maximal amount of vertices
/// defined by the parameters vertexExamples, *m* the average amount of neighbors and *x* the
/// maximal depths.
/// Hence the default call would have a complexity of **O(n\*m)**;
///
/// For parameter documentation read the documentation of
/// [GRAPH_NEIGHBORS](#graphneighbors).
///
/// @EXAMPLES
///
/// A route planner example, all common neighbors of capitals.
///
/// @EXAMPLE_ARANGOSH_OUTPUT{generalGraphCommonNeighbors1}
/// var examples = require("@arangodb/graph-examples/example-graph.js");
/// var g = examples.loadGraph("routeplanner");
/// | db._query("FOR e IN GRAPH_COMMON_NEIGHBORS("
/// | +"'routeplanner', {isCapital : true}, {isCapital : true}) RETURN e"
/// ).toArray();
/// ~ examples.dropGraph("routeplanner");
/// @END_EXAMPLE_ARANGOSH_OUTPUT
///
/// A route planner example, all common outbound neighbors of Hamburg with any other location
/// which have a maximal depth of 2:
///
/// @EXAMPLE_ARANGOSH_OUTPUT{generalGraphCommonNeighbors2}
/// var examples = require("@arangodb/graph-examples/example-graph.js");
/// var g = examples.loadGraph("routeplanner");
/// | db._query("FOR e IN GRAPH_COMMON_NEIGHBORS("
/// | +"'routeplanner', 'germanCity/Hamburg', {}, {direction : 'outbound', maxDepth : 2}, "+
/// | "{direction : 'outbound', maxDepth : 2}) RETURN e"
/// ).toArray();
/// ~ examples.dropGraph("routeplanner");
/// @END_EXAMPLE_ARANGOSH_OUTPUT
///
/// @endDocuBlock
////////////////////////////////////////////////////////////////////////////////
The GRAPH\_COMMON\_NEIGHBORS function returns all common neighbors of the vertices
defined by the examples.
`GRAPH_COMMON_NEIGHBORS (graphName, vertex1Example, vertex2Examples,
optionsVertex1, optionsVertex2)`
This function returns the intersection of *GRAPH_NEIGHBORS(vertex1Example, optionsVertex1)*
and *GRAPH_NEIGHBORS(vertex2Example, optionsVertex2)*.
The complexity of this method is **O(n\*m^x)** with *n* being the maximal amount of vertices
defined by the parameters vertexExamples, *m* the average amount of neighbors and *x* the
maximal depths.
Hence the default call would have a complexity of **O(n\*m)**;
For parameter documentation read the documentation of
[GRAPH_NEIGHBORS](#graphneighbors).
@EXAMPLES
A route planner example, all common neighbors of capitals.
@EXAMPLE_ARANGOSH_OUTPUT{generalGraphCommonNeighbors1}
var examples = require("@arangodb/graph-examples/example-graph.js");
var g = examples.loadGraph("routeplanner");
| db._query("FOR e IN GRAPH_COMMON_NEIGHBORS("
| +"'routeplanner', {isCapital : true}, {isCapital : true}) RETURN e"
).toArray();
~ examples.dropGraph("routeplanner");
@END_EXAMPLE_ARANGOSH_OUTPUT
A route planner example, all common outbound neighbors of Hamburg with any other location
which have a maximal depth of 2:
@EXAMPLE_ARANGOSH_OUTPUT{generalGraphCommonNeighbors2}
var examples = require("@arangodb/graph-examples/example-graph.js");
var g = examples.loadGraph("routeplanner");
| db._query("FOR e IN GRAPH_COMMON_NEIGHBORS("
| +"'routeplanner', 'germanCity/Hamburg', {}, {direction : 'outbound', maxDepth : 2}, "+
| "{direction : 'outbound', maxDepth : 2}) RETURN e"
).toArray();
~ examples.dropGraph("routeplanner");
@END_EXAMPLE_ARANGOSH_OUTPUT

107
Documentation/DocuBlocks/JSF_aql_general_graph_common_properties.md
View File

@ -1,54 +1,53 @@
////////////////////////////////////////////////////////////////////////////////
/// @startDocuBlock JSF_aql_general_graph_common_properties
///
/// `GRAPH_COMMON_PROPERTIES (graphName, vertex1Example, vertex2Examples, options)`
///
/// The GRAPH\_COMMON\_PROPERTIES function returns a list of objects which have the id of
/// the vertices defined by *vertex1Example* as keys and a list of vertices defined by
/// *vertex21Example*, that share common properties as value. Notice that only the
/// vertex id and the matching attributes are returned in the result.
///
/// The complexity of this method is **O(n)** with *n* being the maximal amount of vertices
/// defined by the parameters vertexExamples.
///
/// *Parameters*
///
/// * *graphName* : The name of the graph as a string.
/// * *vertex1Example* : An example for the desired
/// vertices (see [example](#short-explanation-of-the-example-parameter)).
/// * *vertex2Example* : An example for the desired
/// vertices (see [example](#short-explanation-of-the-example-parameter)).
/// * *options* (optional) : An object containing the following options:
/// * *vertex1CollectionRestriction* : One or multiple vertex
/// collection names. Only vertices from these collections will be considered.
/// * *vertex2CollectionRestriction* : One or multiple vertex
/// collection names. Only vertices from these collections will be considered.
/// * *ignoreProperties* : One or multiple
/// attributes of a document that should be ignored, either a string or an array..
///
/// @EXAMPLES
///
/// A route planner example, all locations with the same properties:
///
/// @EXAMPLE_ARANGOSH_OUTPUT{generalGraphProperties1}
/// var examples = require("@arangodb/graph-examples/example-graph.js");
/// var g = examples.loadGraph("routeplanner");
/// | db._query("FOR e IN GRAPH_COMMON_PROPERTIES("
/// | +"'routeplanner', {}, {}) RETURN e"
/// ).toArray();
/// ~ examples.dropGraph("routeplanner");
/// @END_EXAMPLE_ARANGOSH_OUTPUT
///
/// A route planner example, all cities which share same properties except for population.
///
/// @EXAMPLE_ARANGOSH_OUTPUT{generalGraphProperties2}
/// var examples = require("@arangodb/graph-examples/example-graph.js");
/// var g = examples.loadGraph("routeplanner");
/// | db._query("FOR e IN GRAPH_COMMON_PROPERTIES("
/// | +"'routeplanner', {}, {}, {ignoreProperties: 'population'}) RETURN e"
/// ).toArray();
/// ~ examples.dropGraph("routeplanner");
/// @END_EXAMPLE_ARANGOSH_OUTPUT
///
/// @endDocuBlock
////////////////////////////////////////////////////////////////////////////////
`GRAPH_COMMON_PROPERTIES (graphName, vertex1Example, vertex2Examples, options)`
The GRAPH\_COMMON\_PROPERTIES function returns a list of objects which have the id of
the vertices defined by *vertex1Example* as keys and a list of vertices defined by
*vertex21Example*, that share common properties as value. Notice that only the
vertex id and the matching attributes are returned in the result.
The complexity of this method is **O(n)** with *n* being the maximal amount of vertices
defined by the parameters vertexExamples.
*Parameters*
* *graphName* : The name of the graph as a string.
* *vertex1Example* : An example for the desired
vertices (see [example](#short-explanation-of-the-example-parameter)).
* *vertex2Example* : An example for the desired
vertices (see [example](#short-explanation-of-the-example-parameter)).
* *options* (optional) : An object containing the following options:
* *vertex1CollectionRestriction* : One or multiple vertex
collection names. Only vertices from these collections will be considered.
* *vertex2CollectionRestriction* : One or multiple vertex
collection names. Only vertices from these collections will be considered.
* *ignoreProperties* : One or multiple
attributes of a document that should be ignored, either a string or an array..
@EXAMPLES
A route planner example, all locations with the same properties:
@EXAMPLE_ARANGOSH_OUTPUT{generalGraphProperties1}
var examples = require("@arangodb/graph-examples/example-graph.js");
var g = examples.loadGraph("routeplanner");
| db._query("FOR e IN GRAPH_COMMON_PROPERTIES("
| +"'routeplanner', {}, {}) RETURN e"
).toArray();
~ examples.dropGraph("routeplanner");
@END_EXAMPLE_ARANGOSH_OUTPUT
A route planner example, all cities which share same properties except for population.
@EXAMPLE_ARANGOSH_OUTPUT{generalGraphProperties2}
var examples = require("@arangodb/graph-examples/example-graph.js");
var g = examples.loadGraph("routeplanner");
| db._query("FOR e IN GRAPH_COMMON_PROPERTIES("
| +"'routeplanner', {}, {}, {ignoreProperties: 'population'}) RETURN e"
).toArray();
~ examples.dropGraph("routeplanner");
@END_EXAMPLE_ARANGOSH_OUTPUT

127
Documentation/DocuBlocks/JSF_aql_general_graph_diameter.md
View File

@ -1,64 +1,63 @@
////////////////////////////////////////////////////////////////////////////////
/// @startDocuBlock JSF_aql_general_graph_diameter
///
/// `GRAPH_DIAMETER (graphName, options)`
///
/// The GRAPH\_DIAMETER function returns the
/// [diameter](http://en.wikipedia.org/wiki/Eccentricity_%28graph_theory%29)
/// of a graph.
///
/// The complexity of the function is described
/// [here](#the-complexity-of-the-shortest-path-algorithms).
///
/// *Parameters*
///
/// * *graphName* : The name of the graph as a string.
/// * *options* : An object containing the following options:
/// * *direction* : The direction of the edges.
/// Possible values are *outbound*, *inbound* and *any* (default).
/// * *algorithm* : The algorithm to calculate the shortest paths as a string. Possible
/// values are [Floyd-Warshall](http://en.wikipedia.org/wiki/Floyd%E2%80%93Warshall_algorithm)
/// (default) and [Dijkstra](http://en.wikipedia.org/wiki/Dijkstra's_algorithm).
/// * *weight* : The name of the attribute of
/// the edges containing the length.
/// * *defaultWeight* : Only used with the option *weight*.
/// If an edge does not have the attribute named as defined in option *weight* this default
/// is used as length.
/// If no default is supplied the default would be positive Infinity so the path and
/// hence the eccentricity can not be calculated.
///
/// @EXAMPLES
///
/// A route planner example, the diameter of the graph.
///
/// @EXAMPLE_ARANGOSH_OUTPUT{generalGraphDiameter1}
/// var examples = require("@arangodb/graph-examples/example-graph.js");
/// var g = examples.loadGraph("routeplanner");
/// db._query("RETURN GRAPH_DIAMETER('routeplanner')").toArray();
/// ~ examples.dropGraph("routeplanner");
/// @END_EXAMPLE_ARANGOSH_OUTPUT
///
/// A route planner example, the diameter of the graph.
/// This considers the actual distances.
///
/// @EXAMPLE_ARANGOSH_OUTPUT{generalGraphDiameter2}
/// var examples = require("@arangodb/graph-examples/example-graph.js");
/// var g = examples.loadGraph("routeplanner");
/// db._query("RETURN GRAPH_DIAMETER('routeplanner', {weight : 'distance'})").toArray();
/// ~ examples.dropGraph("routeplanner");
/// @END_EXAMPLE_ARANGOSH_OUTPUT
///
/// A route planner example, the diameter of the graph regarding only
/// outbound paths.
///
/// @EXAMPLE_ARANGOSH_OUTPUT{generalGraphDiameter3}
/// var examples = require("@arangodb/graph-examples/example-graph.js");
/// var g = examples.loadGraph("routeplanner");
/// | db._query("RETURN GRAPH_DIAMETER("
/// | + "'routeplanner', {direction : 'outbound', weight : 'distance'})"
/// ).toArray();
/// ~ examples.dropGraph("routeplanner");
/// @END_EXAMPLE_ARANGOSH_OUTPUT
///
/// @endDocuBlock
////////////////////////////////////////////////////////////////////////////////
`GRAPH_DIAMETER (graphName, options)`
The GRAPH\_DIAMETER function returns the
[diameter](http://en.wikipedia.org/wiki/Eccentricity_%28graph_theory%29)
of a graph.
The complexity of the function is described
[here](#the-complexity-of-the-shortest-path-algorithms).
*Parameters*
* *graphName* : The name of the graph as a string.
* *options* : An object containing the following options:
* *direction* : The direction of the edges.
Possible values are *outbound*, *inbound* and *any* (default).
* *algorithm* : The algorithm to calculate the shortest paths as a string. Possible
values are [Floyd-Warshall](http://en.wikipedia.org/wiki/Floyd%E2%80%93Warshall_algorithm)
(default) and [Dijkstra](http://en.wikipedia.org/wiki/Dijkstra's_algorithm).
* *weight* : The name of the attribute of
the edges containing the length.
* *defaultWeight* : Only used with the option *weight*.
If an edge does not have the attribute named as defined in option *weight* this default
is used as length.
If no default is supplied the default would be positive Infinity so the path and
hence the eccentricity can not be calculated.
@EXAMPLES
A route planner example, the diameter of the graph.
@EXAMPLE_ARANGOSH_OUTPUT{generalGraphDiameter1}
var examples = require("@arangodb/graph-examples/example-graph.js");
var g = examples.loadGraph("routeplanner");
db._query("RETURN GRAPH_DIAMETER('routeplanner')").toArray();
~ examples.dropGraph("routeplanner");
@END_EXAMPLE_ARANGOSH_OUTPUT
A route planner example, the diameter of the graph.
This considers the actual distances.
@EXAMPLE_ARANGOSH_OUTPUT{generalGraphDiameter2}
var examples = require("@arangodb/graph-examples/example-graph.js");
var g = examples.loadGraph("routeplanner");
db._query("RETURN GRAPH_DIAMETER('routeplanner', {weight : 'distance'})").toArray();
~ examples.dropGraph("routeplanner");
@END_EXAMPLE_ARANGOSH_OUTPUT
A route planner example, the diameter of the graph regarding only
outbound paths.
@EXAMPLE_ARANGOSH_OUTPUT{generalGraphDiameter3}
var examples = require("@arangodb/graph-examples/example-graph.js");
var g = examples.loadGraph("routeplanner");
| db._query("RETURN GRAPH_DIAMETER("
| + "'routeplanner', {direction : 'outbound', weight : 'distance'})"
).toArray();
~ examples.dropGraph("routeplanner");
@END_EXAMPLE_ARANGOSH_OUTPUT

79
Documentation/DocuBlocks/JSF_aql_general_graph_distance.md
View File

@ -1,40 +1,39 @@
////////////////////////////////////////////////////////////////////////////////
/// @startDocuBlock JSF_aql_general_graph_distance
/// The GRAPH\_DISTANCE\_TO function returns all paths and there distance within a graph.
///
/// `GRAPH_DISTANCE_TO (graphName, startVertexExample, endVertexExample, options)`
///
/// This function is a wrapper of [GRAPH\_SHORTEST\_PATH](#graphshortestpath).
/// It does not return the actual path but only the distance between two vertices.
///
/// @EXAMPLES
///
/// A route planner example, distance from all french to all german cities:
///
/// @EXAMPLE_ARANGOSH_OUTPUT{generalGraphDistanceTo1}
/// var examples = require("@arangodb/graph-examples/example-graph.js");
/// var g = examples.loadGraph("routeplanner");
/// | db._query("FOR e IN GRAPH_DISTANCE_TO("
/// | +"'routeplanner', {}, {}, { " +
/// | " weight : 'distance', endVertexCollectionRestriction : 'germanCity', " +
/// | "startVertexCollectionRestriction : 'frenchCity'}) RETURN [e.startVertex, e.vertex, " +
/// | "e.distance]"
/// ).toArray();
/// ~ examples.dropGraph("routeplanner");
/// @END_EXAMPLE_ARANGOSH_OUTPUT
///
/// A route planner example, distance from Hamburg and Cologne to Lyon:
///
/// @EXAMPLE_ARANGOSH_OUTPUT{generalGraphDistanceTo2}
/// var examples = require("@arangodb/graph-examples/example-graph.js");
/// var g = examples.loadGraph("routeplanner");
/// | db._query("FOR e IN GRAPH_DISTANCE_TO("
/// | + "'routeplanner', [{_id: 'germanCity/Cologne'},{_id: 'germanCity/Hamburg'}], " +
/// | "'frenchCity/Lyon', " +
/// | "{weight : 'distance'}) RETURN [e.startVertex, e.vertex, e.distance]"
/// ).toArray();
/// ~ examples.dropGraph("routeplanner");
/// @END_EXAMPLE_ARANGOSH_OUTPUT
///
/// @endDocuBlock
////////////////////////////////////////////////////////////////////////////////
The GRAPH\_DISTANCE\_TO function returns all paths and there distance within a graph.
`GRAPH_DISTANCE_TO (graphName, startVertexExample, endVertexExample, options)`
This function is a wrapper of [GRAPH\_SHORTEST\_PATH](#graphshortestpath).
It does not return the actual path but only the distance between two vertices.
@EXAMPLES
A route planner example, distance from all french to all german cities:
@EXAMPLE_ARANGOSH_OUTPUT{generalGraphDistanceTo1}
var examples = require("@arangodb/graph-examples/example-graph.js");
var g = examples.loadGraph("routeplanner");
| db._query("FOR e IN GRAPH_DISTANCE_TO("
| +"'routeplanner', {}, {}, { " +
| " weight : 'distance', endVertexCollectionRestriction : 'germanCity', " +
| "startVertexCollectionRestriction : 'frenchCity'}) RETURN [e.startVertex, e.vertex, " +
| "e.distance]"
).toArray();
~ examples.dropGraph("routeplanner");
@END_EXAMPLE_ARANGOSH_OUTPUT
A route planner example, distance from Hamburg and Cologne to Lyon:
@EXAMPLE_ARANGOSH_OUTPUT{generalGraphDistanceTo2}
var examples = require("@arangodb/graph-examples/example-graph.js");
var g = examples.loadGraph("routeplanner");
| db._query("FOR e IN GRAPH_DISTANCE_TO("
| + "'routeplanner', [{_id: 'germanCity/Cologne'},{_id: 'germanCity/Hamburg'}], " +
| "'frenchCity/Lyon', " +
| "{weight : 'distance'}) RETURN [e.startVertex, e.vertex, e.distance]"
).toArray();
~ examples.dropGraph("routeplanner");
@END_EXAMPLE_ARANGOSH_OUTPUT

103
Documentation/DocuBlocks/JSF_aql_general_graph_eccentricity.md
View File

@ -1,52 +1,51 @@
////////////////////////////////////////////////////////////////////////////////
/// @startDocuBlock JSF_aql_general_graph_eccentricity
///
/// `GRAPH_ECCENTRICITY (graphName, options)`
///
/// The GRAPH\_ECCENTRICITY function returns the normalized
/// [eccentricity](http://en.wikipedia.org/wiki/Distance_%28graph_theory%29)
/// of the graphs vertices
///
/// The complexity of the function is described
/// [here](#the-complexity-of-the-shortest-path-algorithms).
///
/// *Parameters*
///
/// * *graphName* : The name of the graph as a string.
/// * *options* (optional) : An object containing the following options:
/// * *direction* : The direction of the edges as a string.
/// Possible values are *outbound*, *inbound* and *any* (default).
/// * *algorithm* : The algorithm to calculate the shortest paths as a string. Possible
/// values are [Floyd-Warshall](http://en.wikipedia.org/wiki/Floyd%E2%80%93Warshall_algorithm)
/// (default) and [Dijkstra](http://en.wikipedia.org/wiki/Dijkstra's_algorithm).
/// * *weight* : The name of the attribute of the edges containing the length as a string.
/// * *defaultWeight* : Only used with the option *weight*.
/// If an edge does not have the attribute named as defined in option *weight* this default
/// is used as length.
/// If no default is supplied the default would be positive Infinity so the path and
/// hence the eccentricity can not be calculated.
///
/// @EXAMPLES
///
/// A route planner example, the eccentricity of all locations.
///
/// @EXAMPLE_ARANGOSH_OUTPUT{generalGraphEccentricity1}
/// var examples = require("@arangodb/graph-examples/example-graph.js");
/// var g = examples.loadGraph("routeplanner");
/// db._query("RETURN GRAPH_ECCENTRICITY('routeplanner')").toArray();
/// ~ examples.dropGraph("routeplanner");
/// @END_EXAMPLE_ARANGOSH_OUTPUT
///
/// A route planner example, the eccentricity of all locations.
/// This considers the actual distances.
///
/// @EXAMPLE_ARANGOSH_OUTPUT{generalGraphEccentricity2}
/// var examples = require("@arangodb/graph-examples/example-graph.js");
/// var g = examples.loadGraph("routeplanner");
/// | db._query("RETURN GRAPH_ECCENTRICITY('routeplanner', {weight : 'distance'})"
/// ).toArray();
/// ~ examples.dropGraph("routeplanner");
/// @END_EXAMPLE_ARANGOSH_OUTPUT
///
/// @endDocuBlock
////////////////////////////////////////////////////////////////////////////////
`GRAPH_ECCENTRICITY (graphName, options)`
The GRAPH\_ECCENTRICITY function returns the normalized
[eccentricity](http://en.wikipedia.org/wiki/Distance_%28graph_theory%29)
of the graphs vertices
The complexity of the function is described
[here](#the-complexity-of-the-shortest-path-algorithms).
*Parameters*
* *graphName* : The name of the graph as a string.
* *options* (optional) : An object containing the following options:
* *direction* : The direction of the edges as a string.
Possible values are *outbound*, *inbound* and *any* (default).
* *algorithm* : The algorithm to calculate the shortest paths as a string. Possible
values are [Floyd-Warshall](http://en.wikipedia.org/wiki/Floyd%E2%80%93Warshall_algorithm)
(default) and [Dijkstra](http://en.wikipedia.org/wiki/Dijkstra's_algorithm).
* *weight* : The name of the attribute of the edges containing the length as a string.
* *defaultWeight* : Only used with the option *weight*.
If an edge does not have the attribute named as defined in option *weight* this default
is used as length.
If no default is supplied the default would be positive Infinity so the path and
hence the eccentricity can not be calculated.
@EXAMPLES
A route planner example, the eccentricity of all locations.
@EXAMPLE_ARANGOSH_OUTPUT{generalGraphEccentricity1}
var examples = require("@arangodb/graph-examples/example-graph.js");
var g = examples.loadGraph("routeplanner");
db._query("RETURN GRAPH_ECCENTRICITY('routeplanner')").toArray();
~ examples.dropGraph("routeplanner");
@END_EXAMPLE_ARANGOSH_OUTPUT
A route planner example, the eccentricity of all locations.
This considers the actual distances.
@EXAMPLE_ARANGOSH_OUTPUT{generalGraphEccentricity2}
var examples = require("@arangodb/graph-examples/example-graph.js");
var g = examples.loadGraph("routeplanner");
| db._query("RETURN GRAPH_ECCENTRICITY('routeplanner', {weight : 'distance'})"
).toArray();
~ examples.dropGraph("routeplanner");
@END_EXAMPLE_ARANGOSH_OUTPUT

161
Documentation/DocuBlocks/JSF_aql_general_graph_edges.md
View File

@ -1,81 +1,80 @@
////////////////////////////////////////////////////////////////////////////////
/// @startDocuBlock JSF_aql_general_graph_edges
///
/// `GRAPH_EDGES (graphName, vertexExample, options)`
///
/// The GRAPH\_EDGES function returns all edges of the graph connected to the vertices
/// defined by the example.
///
/// The complexity of this method is **O(n\*m^x)** with *n* being the vertices defined by the
/// parameter vertexExamplex, *m* the average amount of edges of a vertex and *x* the maximal
/// depths.
/// Hence the default call would have a complexity of **O(n\*m)**;
///
/// *Parameters*
///
/// * *graphName* : The name of the graph as a string.
/// * *vertexExample* : An example for the desired
/// vertices (see [example](#short-explanation-of-the-example-parameter)).
/// * *options* (optional) : An object containing the following options:
/// * *direction* : The direction
/// of the edges as a string. Possible values are *outbound*, *inbound* and *any* (default).
/// * *edgeCollectionRestriction* : One or multiple edge
/// collection names. Only edges from these collections will be considered for the path.
/// * *startVertexCollectionRestriction* : One or multiple vertex
/// collection names. Only vertices from these collections will be considered as
/// start vertex of a path.
/// * *endVertexCollectionRestriction* : One or multiple vertex
/// collection names. Only vertices from these collections will be considered as
/// end vertex of a path.
/// * *edgeExamples* : A filter example
/// for the edges (see [example](#short-explanation-of-the-example-parameter)).
/// * *minDepth* : Defines the minimal length of a path from an edge
/// to a vertex (default is 1, which means only the edges directly connected to a vertex would
/// be returned).
/// * *maxDepth* : Defines the maximal length of a path from an edge
/// to a vertex (default is 1, which means only the edges directly connected to a vertex would
/// be returned).
/// * *maxIterations*: the maximum number of iterations that the traversal is
/// allowed to perform. It is sensible to set this number so unbounded traversals
/// will terminate.
/// * *includeData*: Defines if the result should contain only ids (false) or if all documents
/// should be fully extracted (true). By default this parameter is set to false, so only ids
/// will be returned.
///
/// @EXAMPLES
///
/// A route planner example, all edges to locations with a distance of either 700 or 600.:
///
/// @EXAMPLE_ARANGOSH_OUTPUT{generalGraphEdges1}
/// var examples = require("@arangodb/graph-examples/example-graph.js");
/// var g = examples.loadGraph("routeplanner");
/// | db._query("FOR e IN GRAPH_EDGES("
/// | +"'routeplanner', {}, {edgeExamples : [{distance: 600}, {distance: 700}]}) RETURN e"
/// ).toArray();
/// ~ examples.dropGraph("routeplanner");
/// @END_EXAMPLE_ARANGOSH_OUTPUT
///
/// A route planner example, all outbound edges of Hamburg with a maximal depth of 2 :
///
/// @EXAMPLE_ARANGOSH_OUTPUT{generalGraphEdges2}
/// var examples = require("@arangodb/graph-examples/example-graph.js");
/// var g = examples.loadGraph("routeplanner");
/// | db._query("FOR e IN GRAPH_EDGES("
/// | +"'routeplanner', 'germanCity/Hamburg', {direction : 'outbound', maxDepth : 2}) RETURN e"
/// ).toArray();
/// ~ examples.dropGraph("routeplanner");
/// @END_EXAMPLE_ARANGOSH_OUTPUT
///
/// Including the data:
///
/// @EXAMPLE_ARANGOSH_OUTPUT{generalGraphEdges3}
/// var examples = require("@arangodb/graph-examples/example-graph.js");
/// var g = examples.loadGraph("routeplanner");
/// | db._query("FOR e IN GRAPH_EDGES("
/// | + "'routeplanner', 'germanCity/Hamburg', {direction : 'outbound',"
/// | + "maxDepth : 2, includeData: true}) RETURN e"
/// ).toArray();
/// ~ examples.dropGraph("routeplanner");
/// @END_EXAMPLE_ARANGOSH_OUTPUT
/// @endDocuBlock
////////////////////////////////////////////////////////////////////////////////
`GRAPH_EDGES (graphName, vertexExample, options)`
The GRAPH\_EDGES function returns all edges of the graph connected to the vertices
defined by the example.
The complexity of this method is **O(n\*m^x)** with *n* being the vertices defined by the
parameter vertexExamplex, *m* the average amount of edges of a vertex and *x* the maximal
depths.
Hence the default call would have a complexity of **O(n\*m)**;
*Parameters*
* *graphName* : The name of the graph as a string.
* *vertexExample* : An example for the desired
vertices (see [example](#short-explanation-of-the-example-parameter)).
* *options* (optional) : An object containing the following options:
* *direction* : The direction
of the edges as a string. Possible values are *outbound*, *inbound* and *any* (default).
* *edgeCollectionRestriction* : One or multiple edge
collection names. Only edges from these collections will be considered for the path.
* *startVertexCollectionRestriction* : One or multiple vertex
collection names. Only vertices from these collections will be considered as
start vertex of a path.
* *endVertexCollectionRestriction* : One or multiple vertex
collection names. Only vertices from these collections will be considered as
end vertex of a path.
* *edgeExamples* : A filter example
for the edges (see [example](#short-explanation-of-the-example-parameter)).
* *minDepth* : Defines the minimal length of a path from an edge
to a vertex (default is 1, which means only the edges directly connected to a vertex would
be returned).
* *maxDepth* : Defines the maximal length of a path from an edge
to a vertex (default is 1, which means only the edges directly connected to a vertex would
be returned).
* *maxIterations*: the maximum number of iterations that the traversal is
allowed to perform. It is sensible to set this number so unbounded traversals
will terminate.
* *includeData*: Defines if the result should contain only ids (false) or if all documents
should be fully extracted (true). By default this parameter is set to false, so only ids
will be returned.
@EXAMPLES
A route planner example, all edges to locations with a distance of either 700 or 600.:
@EXAMPLE_ARANGOSH_OUTPUT{generalGraphEdges1}
var examples = require("@arangodb/graph-examples/example-graph.js");
var g = examples.loadGraph("routeplanner");
| db._query("FOR e IN GRAPH_EDGES("
| +"'routeplanner', {}, {edgeExamples : [{distance: 600}, {distance: 700}]}) RETURN e"
).toArray();
~ examples.dropGraph("routeplanner");
@END_EXAMPLE_ARANGOSH_OUTPUT
A route planner example, all outbound edges of Hamburg with a maximal depth of 2 :
@EXAMPLE_ARANGOSH_OUTPUT{generalGraphEdges2}
var examples = require("@arangodb/graph-examples/example-graph.js");
var g = examples.loadGraph("routeplanner");
| db._query("FOR e IN GRAPH_EDGES("
| +"'routeplanner', 'germanCity/Hamburg', {direction : 'outbound', maxDepth : 2}) RETURN e"
).toArray();
~ examples.dropGraph("routeplanner");
@END_EXAMPLE_ARANGOSH_OUTPUT
Including the data:
@EXAMPLE_ARANGOSH_OUTPUT{generalGraphEdges3}
var examples = require("@arangodb/graph-examples/example-graph.js");
var g = examples.loadGraph("routeplanner");
| db._query("FOR e IN GRAPH_EDGES("
| + "'routeplanner', 'germanCity/Hamburg', {direction : 'outbound',"
| + "maxDepth : 2, includeData: true}) RETURN e"
).toArray();
~ examples.dropGraph("routeplanner");
@END_EXAMPLE_ARANGOSH_OUTPUT

139
Documentation/DocuBlocks/JSF_aql_general_graph_neighbors.md
View File

@ -1,70 +1,69 @@
////////////////////////////////////////////////////////////////////////////////
/// @startDocuBlock JSF_aql_general_graph_neighbors
/// The GRAPH\_NEIGHBORS function returns all neighbors of vertices.
///
/// `GRAPH_NEIGHBORS (graphName, vertexExample, options)`
///
/// By default only the direct neighbors (path length equals 1) are returned, but one can define
/// the range of the path length to the neighbors with the options *minDepth* and *maxDepth*.
/// The complexity of this method is **O(n\*m^x)** with *n* being the vertices defined by the
/// parameter vertexExamplex, *m* the average amount of neighbors and *x* the maximal depths.
/// Hence the default call would have a complexity of **O(n\*m)**;
///
/// *Parameters*
///
/// * *graphName* : The name of the graph as a string.
/// * *vertexExample* : An example for the desired
/// vertices (see [example](#short-explanation-of-the-example-parameter)).
/// * *options* : An object containing the following options:
/// * *direction* : The direction
/// of the edges. Possible values are *outbound*, *inbound* and *any* (default).
/// * *edgeExamples* : A filter example for the edges to
/// the neighbors (see [example](#short-explanation-of-the-example-parameter)).
/// * *neighborExamples* : An example for the desired neighbors
/// (see [example](#short-explanation-of-the-example-parameter)).
/// * *edgeCollectionRestriction* : One or multiple edge
/// collection names. Only edges from these collections will be considered for the path.
/// * *vertexCollectionRestriction* : One or multiple vertex
/// collection names. Only vertices from these collections will be contained in the
/// result. This does not effect vertices on the path.
/// * *minDepth* : Defines the minimal
/// depth a path to a neighbor must have to be returned (default is 1).
/// * *maxDepth* : Defines the maximal
/// depth a path to a neighbor must have to be returned (default is 1).
/// * *maxIterations*: the maximum number of iterations that the traversal is
/// allowed to perform. It is sensible to set this number so unbounded traversals
/// will terminate at some point.
/// * *includeData* is a boolean value to define if the returned documents should be extracted
/// instead of returning their ids only. The default is *false*.
///
/// Note: in ArangoDB versions prior to 2.6 *NEIGHBORS* returned the array of neighbor vertices with
/// all attributes and not just the vertex ids. To return to the same behavior, set the *includeData*
/// option to *true* in 2.6 and above.
///
/// @EXAMPLES
///
/// A route planner example, all neighbors of locations with a distance of either
/// 700 or 600.:
///
/// @EXAMPLE_ARANGOSH_OUTPUT{generalGraphNeighbors1}
/// var examples = require("@arangodb/graph-examples/example-graph.js");
/// var g = examples.loadGraph("routeplanner");
/// | db._query("FOR e IN GRAPH_NEIGHBORS("
/// | +"'routeplanner', {}, {edgeExamples : [{distance: 600}, {distance: 700}]}) RETURN e"
/// ).toArray();
/// ~ examples.dropGraph("routeplanner");
/// @END_EXAMPLE_ARANGOSH_OUTPUT
///
/// A route planner example, all outbound neighbors of Hamburg with a maximal depth of 2 :
///
/// @EXAMPLE_ARANGOSH_OUTPUT{generalGraphNeighbors2}
/// var examples = require("@arangodb/graph-examples/example-graph.js");
/// var g = examples.loadGraph("routeplanner");
/// | db._query("FOR e IN GRAPH_NEIGHBORS("
/// | +"'routeplanner', 'germanCity/Hamburg', {direction : 'outbound', maxDepth : 2}) RETURN e"
/// ).toArray();
/// ~ examples.dropGraph("routeplanner");
/// @END_EXAMPLE_ARANGOSH_OUTPUT
///
/// @endDocuBlock
////////////////////////////////////////////////////////////////////////////////
The GRAPH\_NEIGHBORS function returns all neighbors of vertices.
`GRAPH_NEIGHBORS (graphName, vertexExample, options)`
By default only the direct neighbors (path length equals 1) are returned, but one can define
the range of the path length to the neighbors with the options *minDepth* and *maxDepth*.
The complexity of this method is **O(n\*m^x)** with *n* being the vertices defined by the
parameter vertexExamplex, *m* the average amount of neighbors and *x* the maximal depths.
Hence the default call would have a complexity of **O(n\*m)**;
*Parameters*
* *graphName* : The name of the graph as a string.
* *vertexExample* : An example for the desired
vertices (see [example](#short-explanation-of-the-example-parameter)).
* *options* : An object containing the following options:
* *direction* : The direction
of the edges. Possible values are *outbound*, *inbound* and *any* (default).
* *edgeExamples* : A filter example for the edges to
the neighbors (see [example](#short-explanation-of-the-example-parameter)).
* *neighborExamples* : An example for the desired neighbors
(see [example](#short-explanation-of-the-example-parameter)).
* *edgeCollectionRestriction* : One or multiple edge
collection names. Only edges from these collections will be considered for the path.
* *vertexCollectionRestriction* : One or multiple vertex
collection names. Only vertices from these collections will be contained in the
result. This does not effect vertices on the path.
* *minDepth* : Defines the minimal
depth a path to a neighbor must have to be returned (default is 1).
* *maxDepth* : Defines the maximal
depth a path to a neighbor must have to be returned (default is 1).
* *maxIterations*: the maximum number of iterations that the traversal is
allowed to perform. It is sensible to set this number so unbounded traversals
will terminate at some point.
* *includeData* is a boolean value to define if the returned documents should be extracted
instead of returning their ids only. The default is *false*.
Note: in ArangoDB versions prior to 2.6 *NEIGHBORS* returned the array of neighbor vertices with
all attributes and not just the vertex ids. To return to the same behavior, set the *includeData*
option to *true* in 2.6 and above.
@EXAMPLES
A route planner example, all neighbors of locations with a distance of either
700 or 600.:
@EXAMPLE_ARANGOSH_OUTPUT{generalGraphNeighbors1}
var examples = require("@arangodb/graph-examples/example-graph.js");
var g = examples.loadGraph("routeplanner");
| db._query("FOR e IN GRAPH_NEIGHBORS("
| +"'routeplanner', {}, {edgeExamples : [{distance: 600}, {distance: 700}]}) RETURN e"
).toArray();
~ examples.dropGraph("routeplanner");
@END_EXAMPLE_ARANGOSH_OUTPUT
A route planner example, all outbound neighbors of Hamburg with a maximal depth of 2 :
@EXAMPLE_ARANGOSH_OUTPUT{generalGraphNeighbors2}
var examples = require("@arangodb/graph-examples/example-graph.js");
var g = examples.loadGraph("routeplanner");
| db._query("FOR e IN GRAPH_NEIGHBORS("
| +"'routeplanner', 'germanCity/Hamburg', {direction : 'outbound', maxDepth : 2}) RETURN e"
).toArray();
~ examples.dropGraph("routeplanner");
@END_EXAMPLE_ARANGOSH_OUTPUT

91
Documentation/DocuBlocks/JSF_aql_general_graph_paths.md
View File

@ -1,46 +1,45 @@
////////////////////////////////////////////////////////////////////////////////
/// @startDocuBlock JSF_aql_general_graph_paths
/// The GRAPH\_PATHS function returns all paths of a graph.
///
/// `GRAPH_PATHS (graphName, options)`
///
/// The complexity of this method is **O(n\*n\*m)** with *n* being the amount of vertices in
/// the graph and *m* the average amount of connected edges;
///
/// *Parameters*
///
/// * *graphName* : The name of the graph as a string.
/// * *options* : An object containing the following options:
/// * *direction* : The direction of the edges. Possible values are *any*,
/// *inbound* and *outbound* (default).
/// * *followCycles* (optional) : If set to *true* the query follows cycles in the graph,
/// default is false.
/// * *minLength* (optional) : Defines the minimal length a path must
/// have to be returned (default is 0).
/// * *maxLength* (optional) : Defines the maximal length a path must
/// have to be returned (default is 10).
///
/// @EXAMPLES
///
/// Return all paths of the graph "social":
///
/// @EXAMPLE_ARANGOSH_OUTPUT{generalGraphPaths}
/// var examples = require("@arangodb/graph-examples/example-graph.js");
/// var g = examples.loadGraph("social");
/// db._query("RETURN GRAPH_PATHS('social')").toArray();
/// ~ examples.dropGraph("social");
/// @END_EXAMPLE_ARANGOSH_OUTPUT
///
/// Return all inbound paths of the graph "social" with a maximal
/// length of 1 and a minimal length of 2:
///
/// @EXAMPLE_ARANGOSH_OUTPUT{generalGraphPaths2}
/// var examples = require("@arangodb/graph-examples/example-graph.js");
/// var g = examples.loadGraph("social");
/// | db._query(
/// | "RETURN GRAPH_PATHS('social', {direction : 'inbound', minLength : 1, maxLength : 2})"
/// ).toArray();
/// ~ examples.dropGraph("social");
/// @END_EXAMPLE_ARANGOSH_OUTPUT
/// @endDocuBlock
////////////////////////////////////////////////////////////////////////////////
The GRAPH\_PATHS function returns all paths of a graph.
`GRAPH_PATHS (graphName, options)`
The complexity of this method is **O(n\*n\*m)** with *n* being the amount of vertices in
the graph and *m* the average amount of connected edges;
*Parameters*
* *graphName* : The name of the graph as a string.
* *options* : An object containing the following options:
* *direction* : The direction of the edges. Possible values are *any*,
*inbound* and *outbound* (default).
* *followCycles* (optional) : If set to *true* the query follows cycles in the graph,
default is false.
* *minLength* (optional) : Defines the minimal length a path must
have to be returned (default is 0).
* *maxLength* (optional) : Defines the maximal length a path must
have to be returned (default is 10).
@EXAMPLES
Return all paths of the graph "social":
@EXAMPLE_ARANGOSH_OUTPUT{generalGraphPaths}
var examples = require("@arangodb/graph-examples/example-graph.js");
var g = examples.loadGraph("social");
db._query("RETURN GRAPH_PATHS('social')").toArray();
~ examples.dropGraph("social");
@END_EXAMPLE_ARANGOSH_OUTPUT
Return all inbound paths of the graph "social" with a maximal
length of 1 and a minimal length of 2:
@EXAMPLE_ARANGOSH_OUTPUT{generalGraphPaths2}
var examples = require("@arangodb/graph-examples/example-graph.js");
var g = examples.loadGraph("social");
| db._query(
| "RETURN GRAPH_PATHS('social', {direction : 'inbound', minLength : 1, maxLength : 2})"
).toArray();
~ examples.dropGraph("social");
@END_EXAMPLE_ARANGOSH_OUTPUT

123
Documentation/DocuBlocks/JSF_aql_general_graph_radius.md
View File

@ -1,62 +1,61 @@
////////////////////////////////////////////////////////////////////////////////
/// @startDocuBlock JSF_aql_general_graph_radius
///
/// `GRAPH_RADIUS (graphName, options)`
///
/// *The GRAPH\_RADIUS function returns the
/// [radius](http://en.wikipedia.org/wiki/Eccentricity_%28graph_theory%29)
/// of a graph.*
///
/// The complexity of the function is described
/// [here](#the-complexity-of-the-shortest-path-algorithms).
///
/// * *graphName* : The name of the graph as a string.
/// * *options* : An object containing the following options:
/// * *direction* : The direction of the edges.
/// Possible values are *outbound*, *inbound* and *any* (default).
/// * *algorithm* : The algorithm to calculate the shortest paths as a string. Possible
/// values are [Floyd-Warshall](http://en.wikipedia.org/wiki/Floyd%E2%80%93Warshall_algorithm)
/// (default) and [Dijkstra](http://en.wikipedia.org/wiki/Dijkstra's_algorithm).
/// * *weight* : The name of the attribute of
/// the edges containing the length.
/// * *defaultWeight* : Only used with the option *weight*.
/// If an edge does not have the attribute named as defined in option *weight* this default
/// is used as length.
/// If no default is supplied the default would be positive Infinity so the path and
/// hence the eccentricity can not be calculated.
///
/// @EXAMPLES
///
/// A route planner example, the radius of the graph.
///
/// @EXAMPLE_ARANGOSH_OUTPUT{generalGraphRadius1}
/// var examples = require("@arangodb/graph-examples/example-graph.js");
/// var g = examples.loadGraph("routeplanner");
/// db._query("RETURN GRAPH_RADIUS('routeplanner')").toArray();
/// ~ examples.dropGraph("routeplanner");
/// @END_EXAMPLE_ARANGOSH_OUTPUT
///
/// A route planner example, the radius of the graph.
/// This considers the actual distances.
///
/// @EXAMPLE_ARANGOSH_OUTPUT{generalGraphRadius2}
/// var examples = require("@arangodb/graph-examples/example-graph.js");
/// var g = examples.loadGraph("routeplanner");
/// db._query("RETURN GRAPH_RADIUS('routeplanner', {weight : 'distance'})").toArray();
/// ~ examples.dropGraph("routeplanner");
/// @END_EXAMPLE_ARANGOSH_OUTPUT
///
/// A route planner example, the radius of the graph regarding only
/// outbound paths.
///
/// @EXAMPLE_ARANGOSH_OUTPUT{generalGraphRadius3}
/// var examples = require("@arangodb/graph-examples/example-graph.js");
/// var g = examples.loadGraph("routeplanner");
/// | db._query("RETURN GRAPH_RADIUS("
/// | + "'routeplanner', {direction : 'outbound', weight : 'distance'})"
/// ).toArray();
/// ~ examples.dropGraph("routeplanner");
/// @END_EXAMPLE_ARANGOSH_OUTPUT
///
/// @endDocuBlock
////////////////////////////////////////////////////////////////////////////////
`GRAPH_RADIUS (graphName, options)`
*The GRAPH\_RADIUS function returns the
[radius](http://en.wikipedia.org/wiki/Eccentricity_%28graph_theory%29)
of a graph.*
The complexity of the function is described
[here](#the-complexity-of-the-shortest-path-algorithms).
* *graphName* : The name of the graph as a string.
* *options* : An object containing the following options:
* *direction* : The direction of the edges.
Possible values are *outbound*, *inbound* and *any* (default).
* *algorithm* : The algorithm to calculate the shortest paths as a string. Possible
values are [Floyd-Warshall](http://en.wikipedia.org/wiki/Floyd%E2%80%93Warshall_algorithm)
(default) and [Dijkstra](http://en.wikipedia.org/wiki/Dijkstra's_algorithm).
* *weight* : The name of the attribute of
the edges containing the length.
* *defaultWeight* : Only used with the option *weight*.
If an edge does not have the attribute named as defined in option *weight* this default
is used as length.
If no default is supplied the default would be positive Infinity so the path and
hence the eccentricity can not be calculated.
@EXAMPLES
A route planner example, the radius of the graph.
@EXAMPLE_ARANGOSH_OUTPUT{generalGraphRadius1}
var examples = require("@arangodb/graph-examples/example-graph.js");
var g = examples.loadGraph("routeplanner");
db._query("RETURN GRAPH_RADIUS('routeplanner')").toArray();
~ examples.dropGraph("routeplanner");
@END_EXAMPLE_ARANGOSH_OUTPUT
A route planner example, the radius of the graph.
This considers the actual distances.
@EXAMPLE_ARANGOSH_OUTPUT{generalGraphRadius2}
var examples = require("@arangodb/graph-examples/example-graph.js");
var g = examples.loadGraph("routeplanner");
db._query("RETURN GRAPH_RADIUS('routeplanner', {weight : 'distance'})").toArray();
~ examples.dropGraph("routeplanner");
@END_EXAMPLE_ARANGOSH_OUTPUT
A route planner example, the radius of the graph regarding only
outbound paths.
@EXAMPLE_ARANGOSH_OUTPUT{generalGraphRadius3}
var examples = require("@arangodb/graph-examples/example-graph.js");
var g = examples.loadGraph("routeplanner");
| db._query("RETURN GRAPH_RADIUS("
| + "'routeplanner', {direction : 'outbound', weight : 'distance'})"
).toArray();
~ examples.dropGraph("routeplanner");
@END_EXAMPLE_ARANGOSH_OUTPUT

199
Documentation/DocuBlocks/JSF_aql_general_graph_shortest_paths.md
View File

@ -1,100 +1,99 @@
////////////////////////////////////////////////////////////////////////////////
/// @startDocuBlock JSF_aql_general_graph_shortest_paths
/// The GRAPH\_SHORTEST\_PATH function returns all shortest paths of a graph.
///
/// `GRAPH_SHORTEST_PATH (graphName, startVertexExample, endVertexExample, options)`
///
/// This function determines all shortest paths in a graph identified by *graphName*.
/// If one wants to call this function to receive nearly all shortest paths for a
/// graph the option *algorithm* should be set to
/// [Floyd-Warshall](http://en.wikipedia.org/wiki/Floyd%E2%80%93Warshall_algorithm) to
/// increase performance.
/// If no algorithm is provided in the options the function chooses the appropriate
/// one (either [Floyd-Warshall](http://en.wikipedia.org/wiki/Floyd%E2%80%93Warshall_algorithm)
/// or [Dijkstra](http://en.wikipedia.org/wiki/Dijkstra's_algorithm)) according to its parameters.
/// The length of a path is by default the amount of edges from one start vertex to
/// an end vertex. The option weight allows the user to define an edge attribute
/// representing the length.
///
/// The complexity of the function is described
/// [here](#the-complexity-of-the-shortest-path-algorithms).
///
/// *Parameters*
///
/// * *graphName* : The name of the graph as a string.
/// * *startVertexExample* : An example for the desired start Vertices
/// (see [example](#short-explanation-of-the-example-parameter)).
/// * *endVertexExample* : An example for the desired
/// end Vertices (see [example](#short-explanation-of-the-example-parameter)).
/// * *options* (optional) : An object containing the following options:
/// * *direction* : The direction of the edges as a string.
/// Possible values are *outbound*, *inbound* and *any* (default).
/// * *edgeCollectionRestriction* : One or multiple edge
/// collection names. Only edges from these collections will be considered for the path.
/// * *startVertexCollectionRestriction* : One or multiple vertex
/// collection names. Only vertices from these collections will be considered as
/// start vertex of a path.
/// * *endVertexCollectionRestriction* : One or multiple vertex
/// collection names. Only vertices from these collections will be considered as
/// end vertex of a path.
/// * *edgeExamples* : A filter example for the
/// edges in the shortest paths
/// (see [example](#short-explanation-of-the-example-parameter)).
/// * *algorithm* : The algorithm to calculate
/// the shortest paths. If both start and end vertex examples are empty
/// [Floyd-Warshall](http://en.wikipedia.org/wiki/Floyd%E2%80%93Warshall_algorithm) is
/// used, otherwise the default is [Dijkstra](http://en.wikipedia.org/wiki/Dijkstra's_algorithm).
/// * *weight* : The name of the attribute of
/// the edges containing the length as a string.
/// * *defaultWeight* : Only used with the option *weight*.
/// If an edge does not have the attribute named as defined in option *weight* this default
/// is used as length.
/// If no default is supplied the default would be positive Infinity so the path could
/// not be calculated.
/// * *stopAtFirstMatch* : Only useful if targetVertices is an example that matches
/// to more than one vertex. If so only the shortest path to
/// the closest of these target vertices is returned.
/// This flag is of special use if you have target pattern and
/// you want to know which vertex with this pattern is matched first.
/// * *includeData* : Triggers if only *_id*'s are returned (*false*, default)
/// or if data is included for all objects as well (*true*)
/// This will modify the content of *vertex*, *path.vertices*
/// and *path.edges*.
///
/// NOTE: Since version 2.6 we have included a new optional parameter *includeData*.
/// This parameter triggers if the result contains the real data object *true* or
/// it just includes the *_id* values *false*.
/// The default value is *false* as it yields performance benefits.
///
/// @EXAMPLES
///
/// A route planner example, shortest distance from all german to all french cities:
///
/// @EXAMPLE_ARANGOSH_OUTPUT{generalGraphShortestPaths1}
/// var examples = require("@arangodb/graph-examples/example-graph.js");
/// var g = examples.loadGraph("routeplanner");
/// | db._query("FOR e IN GRAPH_SHORTEST_PATH("
/// | + "'routeplanner', {}, {}, {" +
/// | "weight : 'distance', endVertexCollectionRestriction : 'frenchCity', " +
/// | "includeData: true, " +
/// | "startVertexCollectionRestriction : 'germanCity'}) RETURN [e.startVertex, e.vertex._id, " +
/// | "e.distance, LENGTH(e.paths)]"
/// ).toArray();
/// ~ examples.dropGraph("routeplanner");
/// @END_EXAMPLE_ARANGOSH_OUTPUT
///
/// A route planner example, shortest distance from Hamburg and Cologne to Lyon:
///
/// @EXAMPLE_ARANGOSH_OUTPUT{generalGraphShortestPaths2}
/// var examples = require("@arangodb/graph-examples/example-graph.js");
/// var g = examples.loadGraph("routeplanner");
/// | db._query("FOR e IN GRAPH_SHORTEST_PATH("
/// | +"'routeplanner', [{_id: 'germanCity/Cologne'},{_id: 'germanCity/Munich'}], " +
/// | "'frenchCity/Lyon', " +
/// | "{weight : 'distance'}) RETURN [e.startVertex, e.vertex, e.distance, LENGTH(e.paths)]"
/// ).toArray();
/// ~ examples.dropGraph("routeplanner");
/// @END_EXAMPLE_ARANGOSH_OUTPUT
///
/// @endDocuBlock
////////////////////////////////////////////////////////////////////////////////
The GRAPH\_SHORTEST\_PATH function returns all shortest paths of a graph.
`GRAPH_SHORTEST_PATH (graphName, startVertexExample, endVertexExample, options)`
This function determines all shortest paths in a graph identified by *graphName*.
If one wants to call this function to receive nearly all shortest paths for a
graph the option *algorithm* should be set to
[Floyd-Warshall](http://en.wikipedia.org/wiki/Floyd%E2%80%93Warshall_algorithm) to
increase performance.
If no algorithm is provided in the options the function chooses the appropriate
one (either [Floyd-Warshall](http://en.wikipedia.org/wiki/Floyd%E2%80%93Warshall_algorithm)
or [Dijkstra](http://en.wikipedia.org/wiki/Dijkstra's_algorithm)) according to its parameters.
The length of a path is by default the amount of edges from one start vertex to
an end vertex. The option weight allows the user to define an edge attribute
representing the length.
The complexity of the function is described
[here](#the-complexity-of-the-shortest-path-algorithms).
*Parameters*
* *graphName* : The name of the graph as a string.
* *startVertexExample* : An example for the desired start Vertices
(see [example](#short-explanation-of-the-example-parameter)).
* *endVertexExample* : An example for the desired
end Vertices (see [example](#short-explanation-of-the-example-parameter)).
* *options* (optional) : An object containing the following options:
* *direction* : The direction of the edges as a string.
Possible values are *outbound*, *inbound* and *any* (default).
* *edgeCollectionRestriction* : One or multiple edge
collection names. Only edges from these collections will be considered for the path.
* *startVertexCollectionRestriction* : One or multiple vertex
collection names. Only vertices from these collections will be considered as
start vertex of a path.
* *endVertexCollectionRestriction* : One or multiple vertex
collection names. Only vertices from these collections will be considered as
end vertex of a path.
* *edgeExamples* : A filter example for the
edges in the shortest paths
(see [example](#short-explanation-of-the-example-parameter)).
* *algorithm* : The algorithm to calculate
the shortest paths. If both start and end vertex examples are empty
[Floyd-Warshall](http://en.wikipedia.org/wiki/Floyd%E2%80%93Warshall_algorithm) is
used, otherwise the default is [Dijkstra](http://en.wikipedia.org/wiki/Dijkstra's_algorithm).
* *weight* : The name of the attribute of
the edges containing the length as a string.
* *defaultWeight* : Only used with the option *weight*.
If an edge does not have the attribute named as defined in option *weight* this default
is used as length.
If no default is supplied the default would be positive Infinity so the path could
not be calculated.
* *stopAtFirstMatch* : Only useful if targetVertices is an example that matches
to more than one vertex. If so only the shortest path to
the closest of these target vertices is returned.
This flag is of special use if you have target pattern and
you want to know which vertex with this pattern is matched first.
* *includeData* : Triggers if only *_id*'s are returned (*false*, default)
or if data is included for all objects as well (*true*)
This will modify the content of *vertex*, *path.vertices*
and *path.edges*.
NOTE: Since version 2.6 we have included a new optional parameter *includeData*.
This parameter triggers if the result contains the real data object *true* or
it just includes the *_id* values *false*.
The default value is *false* as it yields performance benefits.
@EXAMPLES
A route planner example, shortest distance from all german to all french cities:
@EXAMPLE_ARANGOSH_OUTPUT{generalGraphShortestPaths1}
var examples = require("@arangodb/graph-examples/example-graph.js");
var g = examples.loadGraph("routeplanner");
| db._query("FOR e IN GRAPH_SHORTEST_PATH("
| + "'routeplanner', {}, {}, {" +
| "weight : 'distance', endVertexCollectionRestriction : 'frenchCity', " +
| "includeData: true, " +
| "startVertexCollectionRestriction : 'germanCity'}) RETURN [e.startVertex, e.vertex._id, " +
| "e.distance, LENGTH(e.paths)]"
).toArray();
~ examples.dropGraph("routeplanner");
@END_EXAMPLE_ARANGOSH_OUTPUT
A route planner example, shortest distance from Hamburg and Cologne to Lyon:
@EXAMPLE_ARANGOSH_OUTPUT{generalGraphShortestPaths2}
var examples = require("@arangodb/graph-examples/example-graph.js");
var g = examples.loadGraph("routeplanner");
| db._query("FOR e IN GRAPH_SHORTEST_PATH("
| +"'routeplanner', [{_id: 'germanCity/Cologne'},{_id: 'germanCity/Munich'}], " +
| "'frenchCity/Lyon', " +
| "{weight : 'distance'}) RETURN [e.startVertex, e.vertex, e.distance, LENGTH(e.paths)]"
).toArray();
~ examples.dropGraph("routeplanner");
@END_EXAMPLE_ARANGOSH_OUTPUT

181
Documentation/DocuBlocks/JSF_aql_general_graph_traversal.md
View File

@ -1,91 +1,90 @@
////////////////////////////////////////////////////////////////////////////////
/// @startDocuBlock JSF_aql_general_graph_traversal
/// The GRAPH\_TRAVERSAL function traverses through the graph.
///
/// `GRAPH_TRAVERSAL (graphName, startVertexExample, direction, options)`
///
/// This function performs traversals on the given graph.
///
/// The complexity of this function strongly depends on the usage.
///
/// *Parameters*
/// * *graphName* : The name of the graph as a string.
/// * *startVertexExample* : An example for the desired
/// vertices (see [example](#short-explanation-of-the-example-parameter)).
/// * *direction* : The direction of the edges as a string. Possible values
/// are *outbound*, *inbound* and *any* (default).
/// * *options*: Object containing optional options.
///
/// *Options*:
///
/// * *strategy*: determines the visitation strategy. Possible values are
/// *depthfirst* and *breadthfirst*. Default is *breadthfirst*.
/// * *order*: determines the visitation order. Possible values are
/// *preorder* and *postorder*.
/// * *itemOrder*: determines the order in which connections returned by the
/// expander will be processed. Possible values are *forward* and *backward*.
/// * *maxDepth*: if set to a value greater than *0*, this will limit the
/// traversal to this maximum depth.
/// * *minDepth*: if set to a value greater than *0*, all vertices found on
/// a level below the *minDepth* level will not be included in the result.
/// * *maxIterations*: the maximum number of iterations that the traversal is
/// allowed to perform. It is sensible to set this number so unbounded traversals
/// will terminate at some point.
/// * *uniqueness*: an object that defines how repeated visitations of vertices should
/// be handled. The *uniqueness* object can have a sub-attribute *vertices*, and a
/// sub-attribute *edges*. Each sub-attribute can have one of the following values:
/// * *"none"*: no uniqueness constraints
/// * *"path"*: element is excluded if it is already contained in the current path.
/// This setting may be sensible for graphs that contain cycles (e.g. A -> B -> C -> A).
/// * *"global"*: element is excluded if it was already found/visited at any
/// point during the traversal.
/// * *filterVertices* An optional array of example vertex documents that the traversal will treat specially.
/// If no examples are given, the traversal will handle all encountered vertices equally.
/// If one or many vertex examples are given, the traversal will exclude any non-matching vertex from the
/// result and/or not descend into it. Optionally, filterVertices can contain a string containing the name
/// of a user-defined AQL function that should be responsible for filtering.
/// If so, the AQL function is expected to have the following signature:
///
/// `function (config, vertex, path)`
///
/// If a custom AQL function is used for filterVertices, it is expected to return one of the following values:
///
/// * [ ]: Include the vertex in the result and descend into its connected edges
/// * [ "prune" ]: Will include the vertex in the result but not descend into its connected edges
/// * [ "exclude" ]: Will not include the vertex in the result but descend into its connected edges
/// * [ "prune", "exclude" ]: Will completely ignore the vertex and its connected edges
///
/// * *vertexFilterMethod:* Only useful in conjunction with filterVertices and if no user-defined AQL function is used.
/// If specified, it will influence how vertices are handled that don't match the examples in filterVertices:
///
/// * [ "prune" ]: Will include non-matching vertices in the result but not descend into them
/// * [ "exclude" ]: Will not include non-matching vertices in the result but descend into them
/// * [ "prune", "exclude" ]: Will completely ignore the vertex and its connected edges
///
/// @EXAMPLES
///
/// A route planner example, start a traversal from Hamburg :
///
/// @EXAMPLE_ARANGOSH_OUTPUT{generalGraphTraversal1}
/// var examples = require("@arangodb/graph-examples/example-graph.js");
/// var g = examples.loadGraph("routeplanner");
/// | db._query("FOR e IN GRAPH_TRAVERSAL('routeplanner', 'germanCity/Hamburg'," +
/// | " 'outbound') RETURN e"
/// ).toArray();
/// ~ examples.dropGraph("routeplanner");
/// @END_EXAMPLE_ARANGOSH_OUTPUT
///
/// A route planner example, start a traversal from Hamburg with a max depth of 1
/// so only the direct neighbors of Hamburg are returned:
///
/// @EXAMPLE_ARANGOSH_OUTPUT{generalGraphTraversal2}
/// var examples = require("@arangodb/graph-examples/example-graph.js");
/// var g = examples.loadGraph("routeplanner");
/// | db._query("FOR e IN GRAPH_TRAVERSAL('routeplanner', 'germanCity/Hamburg'," +
/// | " 'outbound', {maxDepth : 1}) RETURN e"
/// ).toArray();
/// ~ examples.dropGraph("routeplanner");
/// @END_EXAMPLE_ARANGOSH_OUTPUT
///
/// @endDocuBlock
////////////////////////////////////////////////////////////////////////////////
The GRAPH\_TRAVERSAL function traverses through the graph.
`GRAPH_TRAVERSAL (graphName, startVertexExample, direction, options)`
This function performs traversals on the given graph.
The complexity of this function strongly depends on the usage.
*Parameters*
* *graphName* : The name of the graph as a string.
* *startVertexExample* : An example for the desired
vertices (see [example](#short-explanation-of-the-example-parameter)).
* *direction* : The direction of the edges as a string. Possible values
are *outbound*, *inbound* and *any* (default).
* *options*: Object containing optional options.
*Options*:
* *strategy*: determines the visitation strategy. Possible values are
*depthfirst* and *breadthfirst*. Default is *breadthfirst*.
* *order*: determines the visitation order. Possible values are
*preorder* and *postorder*.
* *itemOrder*: determines the order in which connections returned by the
expander will be processed. Possible values are *forward* and *backward*.
* *maxDepth*: if set to a value greater than *0*, this will limit the
traversal to this maximum depth.
* *minDepth*: if set to a value greater than *0*, all vertices found on
a level below the *minDepth* level will not be included in the result.
* *maxIterations*: the maximum number of iterations that the traversal is
allowed to perform. It is sensible to set this number so unbounded traversals
will terminate at some point.
* *uniqueness*: an object that defines how repeated visitations of vertices should
be handled. The *uniqueness* object can have a sub-attribute *vertices*, and a
sub-attribute *edges*. Each sub-attribute can have one of the following values:
* *"none"*: no uniqueness constraints
* *"path"*: element is excluded if it is already contained in the current path.
This setting may be sensible for graphs that contain cycles (e.g. A -> B -> C -> A).
* *"global"*: element is excluded if it was already found/visited at any
point during the traversal.
* *filterVertices* An optional array of example vertex documents that the traversal will treat specially.
If no examples are given, the traversal will handle all encountered vertices equally.
If one or many vertex examples are given, the traversal will exclude any non-matching vertex from the
result and/or not descend into it. Optionally, filterVertices can contain a string containing the name
of a user-defined AQL function that should be responsible for filtering.
If so, the AQL function is expected to have the following signature:
`function (config, vertex, path)`
If a custom AQL function is used for filterVertices, it is expected to return one of the following values:
* [ ]: Include the vertex in the result and descend into its connected edges
* [ "prune" ]: Will include the vertex in the result but not descend into its connected edges
* [ "exclude" ]: Will not include the vertex in the result but descend into its connected edges
* [ "prune", "exclude" ]: Will completely ignore the vertex and its connected edges
* *vertexFilterMethod:* Only useful in conjunction with filterVertices and if no user-defined AQL function is used.
If specified, it will influence how vertices are handled that don't match the examples in filterVertices:
* [ "prune" ]: Will include non-matching vertices in the result but not descend into them
* [ "exclude" ]: Will not include non-matching vertices in the result but descend into them
* [ "prune", "exclude" ]: Will completely ignore the vertex and its connected edges
@EXAMPLES
A route planner example, start a traversal from Hamburg :
@EXAMPLE_ARANGOSH_OUTPUT{generalGraphTraversal1}
var examples = require("@arangodb/graph-examples/example-graph.js");
var g = examples.loadGraph("routeplanner");
| db._query("FOR e IN GRAPH_TRAVERSAL('routeplanner', 'germanCity/Hamburg'," +
| " 'outbound') RETURN e"
).toArray();
~ examples.dropGraph("routeplanner");
@END_EXAMPLE_ARANGOSH_OUTPUT
A route planner example, start a traversal from Hamburg with a max depth of 1
so only the direct neighbors of Hamburg are returned:
@EXAMPLE_ARANGOSH_OUTPUT{generalGraphTraversal2}
var examples = require("@arangodb/graph-examples/example-graph.js");
var g = examples.loadGraph("routeplanner");
| db._query("FOR e IN GRAPH_TRAVERSAL('routeplanner', 'germanCity/Hamburg'," +
| " 'outbound', {maxDepth : 1}) RETURN e"
).toArray();
~ examples.dropGraph("routeplanner");
@END_EXAMPLE_ARANGOSH_OUTPUT

99
Documentation/DocuBlocks/JSF_aql_general_graph_traversal_tree.md
View File

@ -1,50 +1,49 @@
////////////////////////////////////////////////////////////////////////////////
/// @startDocuBlock JSF_aql_general_graph_traversal_tree
/// The GRAPH\_TRAVERSAL\_TREE function traverses through the graph.
///
/// `GRAPH_TRAVERSAL_TREE (graphName, startVertexExample, direction, connectName, options)`
/// This function creates a tree format from the result for a better visualization of
/// the path.
/// This function performs traversals on the given graph.
///
/// The complexity of this function strongly depends on the usage.
///
/// *Parameters*
///
/// * *graphName* : The name of the graph as a string.
/// * *startVertexExample* : An example for the desired
/// vertices (see [example](#short-explanation-of-the-example-parameter)).
/// * *direction* : The direction of the edges as a string.
/// Possible values are *outbound*, *inbound* and *any* (default).
/// * *connectName* : The result attribute which
/// contains the connection.
/// * *options* (optional) : An object containing options, see
/// [Graph Traversals](../Aql/GraphOperations.md#graphtraversal):
///
/// @EXAMPLES
///
/// A route planner example, start a traversal from Hamburg :
///
/// @EXAMPLE_ARANGOSH_OUTPUT{generalGraphTraversalTree1}
/// var examples = require("@arangodb/graph-examples/example-graph.js");
/// var g = examples.loadGraph("routeplanner");
/// | db._query("FOR e IN GRAPH_TRAVERSAL_TREE('routeplanner', 'germanCity/Hamburg'," +
/// | " 'outbound', 'connnection') RETURN e"
/// ).toArray();
/// ~ examples.dropGraph("routeplanner");
/// @END_EXAMPLE_ARANGOSH_OUTPUT
///
/// A route planner example, start a traversal from Hamburg with a max depth of 1 so
/// only the direct neighbors of Hamburg are returned:
///
/// @EXAMPLE_ARANGOSH_OUTPUT{generalGraphTraversalTree2}
/// var examples = require("@arangodb/graph-examples/example-graph.js");
/// var g = examples.loadGraph("routeplanner");
/// | db._query("FOR e IN GRAPH_TRAVERSAL_TREE('routeplanner', 'germanCity/Hamburg',"+
/// | " 'outbound', 'connnection', {maxDepth : 1}) RETURN e"
/// ).toArray();
/// ~ examples.dropGraph("routeplanner");
/// @END_EXAMPLE_ARANGOSH_OUTPUT
///
/// @endDocuBlock
////////////////////////////////////////////////////////////////////////////////
The GRAPH\_TRAVERSAL\_TREE function traverses through the graph.
`GRAPH_TRAVERSAL_TREE (graphName, startVertexExample, direction, connectName, options)`
This function creates a tree format from the result for a better visualization of
the path.
This function performs traversals on the given graph.
The complexity of this function strongly depends on the usage.
*Parameters*
* *graphName* : The name of the graph as a string.
* *startVertexExample* : An example for the desired
vertices (see [example](#short-explanation-of-the-example-parameter)).
* *direction* : The direction of the edges as a string.
Possible values are *outbound*, *inbound* and *any* (default).
* *connectName* : The result attribute which
contains the connection.
* *options* (optional) : An object containing options, see
[Graph Traversals](../Aql/GraphOperations.md#graphtraversal):
@EXAMPLES
A route planner example, start a traversal from Hamburg :
@EXAMPLE_ARANGOSH_OUTPUT{generalGraphTraversalTree1}
var examples = require("@arangodb/graph-examples/example-graph.js");
var g = examples.loadGraph("routeplanner");
| db._query("FOR e IN GRAPH_TRAVERSAL_TREE('routeplanner', 'germanCity/Hamburg'," +
| " 'outbound', 'connnection') RETURN e"
).toArray();
~ examples.dropGraph("routeplanner");
@END_EXAMPLE_ARANGOSH_OUTPUT
A route planner example, start a traversal from Hamburg with a max depth of 1 so
only the direct neighbors of Hamburg are returned:
@EXAMPLE_ARANGOSH_OUTPUT{generalGraphTraversalTree2}
var examples = require("@arangodb/graph-examples/example-graph.js");
var g = examples.loadGraph("routeplanner");
| db._query("FOR e IN GRAPH_TRAVERSAL_TREE('routeplanner', 'germanCity/Hamburg',"+
| " 'outbound', 'connnection', {maxDepth : 1}) RETURN e"
).toArray();
~ examples.dropGraph("routeplanner");
@END_EXAMPLE_ARANGOSH_OUTPUT

89
Documentation/DocuBlocks/JSF_aql_general_graph_vertices.md
View File

@ -1,45 +1,44 @@
////////////////////////////////////////////////////////////////////////////////
/// @startDocuBlock JSF_aql_general_graph_vertices
/// The GRAPH\_VERTICES function returns all vertices.
///
/// `GRAPH_VERTICES (graphName, vertexExample, options)`
///
/// According to the optional filters it will only return vertices that have
/// outbound, inbound or any (default) edges.
///
/// *Parameters*
///
/// * *graphName* : The name of the graph as a string.
/// * *vertexExample* : An example for the desired
/// vertices (see [example](#short-explanation-of-the-example-parameter)).
/// * *options* (optional) : An object containing the following options:
/// * *direction* : The direction of the edges as a string. Possible values are
/// *outbound*, *inbound* and *any* (default).
/// * *vertexCollectionRestriction* : One or multiple
/// vertex collections that should be considered.
///
/// @EXAMPLES
///
/// A route planner example, all vertices of the graph
///
/// @EXAMPLE_ARANGOSH_OUTPUT{generalGraphVertices1}
/// var examples = require("@arangodb/graph-examples/example-graph.js");
/// var g = examples.loadGraph("routeplanner");
/// | db._query("FOR e IN GRAPH_VERTICES("
/// +"'routeplanner', {}) RETURN e").toArray();
/// ~ examples.dropGraph("routeplanner");
/// @END_EXAMPLE_ARANGOSH_OUTPUT
///
/// A route planner example, all vertices from collection *germanCity*.
///
/// @EXAMPLE_ARANGOSH_OUTPUT{generalGraphVertices2}
/// var examples = require("@arangodb/graph-examples/example-graph.js");
/// var g = examples.loadGraph("routeplanner");
/// | db._query("FOR e IN GRAPH_VERTICES("
/// | +"'routeplanner', {}, {direction : 'any', vertexCollectionRestriction" +
/// " : 'germanCity'}) RETURN e").toArray();
/// ~ examples.dropGraph("routeplanner");
/// @END_EXAMPLE_ARANGOSH_OUTPUT
///
/// @endDocuBlock
////////////////////////////////////////////////////////////////////////////////
The GRAPH\_VERTICES function returns all vertices.
`GRAPH_VERTICES (graphName, vertexExample, options)`
According to the optional filters it will only return vertices that have
outbound, inbound or any (default) edges.
*Parameters*
* *graphName* : The name of the graph as a string.
* *vertexExample* : An example for the desired
vertices (see [example](#short-explanation-of-the-example-parameter)).
* *options* (optional) : An object containing the following options:
* *direction* : The direction of the edges as a string. Possible values are
*outbound*, *inbound* and *any* (default).
* *vertexCollectionRestriction* : One or multiple
vertex collections that should be considered.
@EXAMPLES
A route planner example, all vertices of the graph
@EXAMPLE_ARANGOSH_OUTPUT{generalGraphVertices1}
var examples = require("@arangodb/graph-examples/example-graph.js");
var g = examples.loadGraph("routeplanner");
| db._query("FOR e IN GRAPH_VERTICES("
+"'routeplanner', {}) RETURN e").toArray();
~ examples.dropGraph("routeplanner");
@END_EXAMPLE_ARANGOSH_OUTPUT
A route planner example, all vertices from collection *germanCity*.
@EXAMPLE_ARANGOSH_OUTPUT{generalGraphVertices2}
var examples = require("@arangodb/graph-examples/example-graph.js");
var g = examples.loadGraph("routeplanner");
| db._query("FOR e IN GRAPH_VERTICES("
| +"'routeplanner', {}, {direction : 'any', vertexCollectionRestriction" +
" : 'germanCity'}) RETURN e").toArray();
~ examples.dropGraph("routeplanner");
@END_EXAMPLE_ARANGOSH_OUTPUT

17
Documentation/DocuBlocks/JSF_foxx_BaseMiddleware_request_body.md
View File

@ -1,9 +1,8 @@
////////////////////////////////////////////////////////////////////////////////
/// @startDocuBlock JSF_foxx_BaseMiddleware_request_body
///
/// `request.body()`
///
/// Get the JSON parsed body of the request. If you need the raw version, please
/// refer to the *rawBody* function.
/// @endDocuBlock
////////////////////////////////////////////////////////////////////////////////
`request.body()`
Get the JSON parsed body of the request. If you need the raw version, please
refer to the *rawBody* function.

57
Documentation/DocuBlocks/JSF_foxx_BaseMiddleware_request_cookie.md
View File

@ -1,29 +1,28 @@
////////////////////////////////////////////////////////////////////////////////
/// @startDocuBlock JSF_foxx_BaseMiddleware_request_cookie
///
/// `request.cookie(name, cfg)`
///
/// Read a cookie from the request. Optionally the cookie's signature can be verified.
///
/// *Parameter*
///
/// * *name*: the name of the cookie to read from the request.
/// * *cfg* (optional): an object with any of the following properties:
/// * *signed* (optional): an object with any of the following properties:
/// * *secret*: a secret string that was used to sign the cookie.
/// * *algorithm*: hashing algorithm that was used to sign the cookie. Default: *"sha256"*.
///
/// If *signed* is a string, it will be used as the *secret* instead.
///
/// If a *secret* is provided, a second cookie with the name *name + ".sig"* will
/// be read and its value will be verified as the cookie value's signature.
///
/// If the cookie is not set or its signature is invalid, "undefined" will be returned instead.
///
/// @EXAMPLES
///
/// ```
/// var sid = request.cookie("sid", {signed: "keyboardcat"});
/// ```
/// @endDocuBlock
////////////////////////////////////////////////////////////////////////////////
`request.cookie(name, cfg)`
Read a cookie from the request. Optionally the cookie's signature can be verified.
*Parameter*
* *name*: the name of the cookie to read from the request.
* *cfg* (optional): an object with any of the following properties:
* *signed* (optional): an object with any of the following properties:
* *secret*: a secret string that was used to sign the cookie.
* *algorithm*: hashing algorithm that was used to sign the cookie. Default: *"sha256"*.
If *signed* is a string, it will be used as the *secret* instead.
If a *secret* is provided, a second cookie with the name *name + ".sig"* will
be read and its value will be verified as the cookie value's signature.
If the cookie is not set or its signature is invalid, "undefined" will be returned instead.
@EXAMPLES
```
var sid = request.cookie("sid", {signed: "keyboardcat"});
```

27
Documentation/DocuBlocks/JSF_foxx_BaseMiddleware_request_params.md
View File

@ -1,14 +1,13 @@
////////////////////////////////////////////////////////////////////////////////
/// @startDocuBlock JSF_foxx_BaseMiddleware_request_params
///
/// `request.params(key)`
///
/// Get the parameters of the request. This process is two-fold:
///
/// * If you have defined an URL like */test/:id* and the user requested
/// */test/1*, the call *params("id")* will return *1*.
/// * If you have defined an URL like */test* and the user gives a query
/// component, the query parameters will also be returned. So for example if
/// the user requested */test?a=2*, the call *params("a")* will return *2*.
/// @endDocuBlock
////////////////////////////////////////////////////////////////////////////////
`request.params(key)`
Get the parameters of the request. This process is two-fold:
* If you have defined an URL like */test/:id* and the user requested
*/test/1*, the call *params("id")* will return *1*.
* If you have defined an URL like */test* and the user gives a query
component, the query parameters will also be returned. So for example if
the user requested */test?a=2*, the call *params("a")* will return *2*.

21
Documentation/DocuBlocks/JSF_foxx_BaseMiddleware_request_rawBody.md
View File

@ -1,11 +1,10 @@
////////////////////////////////////////////////////////////////////////////////
/// @startDocuBlock JSF_foxx_BaseMiddleware_request_rawBody
///
/// `request.rawBody()`
///
/// The raw request body, not parsed. The body is returned as a UTF-8 string.
/// Note that this can only be used sensibly if the request body contains
/// valid UTF-8. If the request body is known to contain non-UTF-8 data, the
/// request body can be accessed by using `request.rawBodyBuffer`.
/// @endDocuBlock
////////////////////////////////////////////////////////////////////////////////
`request.rawBody()`
The raw request body, not parsed. The body is returned as a UTF-8 string.
Note that this can only be used sensibly if the request body contains
valid UTF-8. If the request body is known to contain non-UTF-8 data, the
request body can be accessed by using `request.rawBodyBuffer`.

15
Documentation/DocuBlocks/JSF_foxx_BaseMiddleware_request_rawBodyBuffer.md
View File

@ -1,8 +1,7 @@
////////////////////////////////////////////////////////////////////////////////
/// @startDocuBlock JSF_foxx_BaseMiddleware_request_rawBodyBuffer
///
/// `request.rawBodyBuffer()`
///
/// The raw request body, returned as a Buffer object.
/// @endDocuBlock
////////////////////////////////////////////////////////////////////////////////
`request.rawBodyBuffer()`
The raw request body, returned as a Buffer object.

23
Documentation/DocuBlocks/JSF_foxx_BaseMiddleware_request_requestParts.md
View File

@ -1,12 +1,11 @@
////////////////////////////////////////////////////////////////////////////////
/// @startDocuBlock JSF_foxx_BaseMiddleware_request_requestParts
///
/// `request.requestParts()`
///
/// Returns an array containing the individual parts of a multi-part request.
/// Each part contains a `headers` attribute with all headers of the part,
/// and a `data` attribute with the content of the part in a Buffer object.
/// If the request is not a multi-part request, this function will throw an
/// error.
/// @endDocuBlock
////////////////////////////////////////////////////////////////////////////////
`request.requestParts()`
Returns an array containing the individual parts of a multi-part request.
Each part contains a `headers` attribute with all headers of the part,
and a `data` attribute with the content of the part in a Buffer object.
If the request is not a multi-part request, this function will throw an
error.

65
Documentation/DocuBlocks/JSF_foxx_BaseMiddleware_response_cookie.md
View File

@ -1,33 +1,32 @@
////////////////////////////////////////////////////////////////////////////////
/// @startDocuBlock JSF_foxx_BaseMiddleware_response_cookie
///
/// `response.cookie(name, value, cfg)`
///
/// Add a cookie to the response. Optionally the cookie can be signed.
///
/// *Parameter*
///
/// * *name*: the name of the cookie to add to the response.
/// * *value*: the value of the cookie to add to the response.
/// * *cfg* (optional): an object with any of the following properties:
/// * *ttl* (optional): the number of seconds until this cookie expires.
/// * *path* (optional): the cookie path.
/// * *domain* (optional): the cookie domain.
/// * *secure* (optional): mark the cookie as safe transport (HTTPS) only.
/// * *httpOnly* (optional): mark the cookie as HTTP(S) only.
/// * *signed* (optional): an object with any of the following properties:
/// * *secret*: a secret string to sign the cookie with.
/// * *algorithm*: hashing algorithm to sign the cookie with. Default: *"sha256"*.
///
/// If *signed* is a string, it will be used as the *secret* instead.
///
/// If a *secret* is provided, a second cookie with the name *name + ".sig"* will
/// be added to the response, containing the cookie's HMAC signature.
///
/// @EXAMPLES
///
/// ```
/// response.cookie("sid", "abcdef", {signed: "keyboardcat"});
/// ```
/// @endDocuBlock
////////////////////////////////////////////////////////////////////////////////
`response.cookie(name, value, cfg)`
Add a cookie to the response. Optionally the cookie can be signed.
*Parameter*
* *name*: the name of the cookie to add to the response.
* *value*: the value of the cookie to add to the response.
* *cfg* (optional): an object with any of the following properties:
* *ttl* (optional): the number of seconds until this cookie expires.
* *path* (optional): the cookie path.
* *domain* (optional): the cookie domain.
* *secure* (optional): mark the cookie as safe transport (HTTPS) only.
* *httpOnly* (optional): mark the cookie as HTTP(S) only.
* *signed* (optional): an object with any of the following properties:
* *secret*: a secret string to sign the cookie with.
* *algorithm*: hashing algorithm to sign the cookie with. Default: *"sha256"*.
If *signed* is a string, it will be used as the *secret* instead.
If a *secret* is provided, a second cookie with the name *name + ".sig"* will
be added to the response, containing the cookie's HMAC signature.
@EXAMPLES
```
response.cookie("sid", "abcdef", {signed: "keyboardcat"});
```

29
Documentation/DocuBlocks/JSF_foxx_BaseMiddleware_response_json.md
View File

@ -1,15 +1,14 @@
////////////////////////////////////////////////////////////////////////////////
/// @startDocuBlock JSF_foxx_BaseMiddleware_response_json
///
/// `response.json(object)`
///
/// Set the content type to JSON and the body to the JSON encoded *object*
/// you provided.
///
/// @EXAMPLES
///
/// ```js
/// response.json({'born': 'December 12, 1915'});
/// ```
/// @endDocuBlock
////////////////////////////////////////////////////////////////////////////////
`response.json(object)`
Set the content type to JSON and the body to the JSON encoded *object*
you provided.
@EXAMPLES
```js
response.json({'born': 'December 12, 1915'});
```

37
Documentation/DocuBlocks/JSF_foxx_BaseMiddleware_response_send.md
View File

@ -1,19 +1,18 @@
////////////////////////////////////////////////////////////////////////////////
/// @startDocuBlock JSF_foxx_BaseMiddleware_response_send
///
/// `response.send(value)`
///
/// Sets the response body to the specified *value*. If *value* is a Buffer
/// object, the content type will be set to `application/octet-stream` if not
/// yet set. If *value* is a string, the content type will be set to `text/html`
/// if not yet set. If *value* is an object, it will be treated as in `res.json`.
///
/// @EXAMPLES
///
/// ```js
/// response.send({"born": "December 12, 1915"});
/// response.send(new Buffer("some binary data"));
/// response.send("<html><head><title>Hello World</title></head><body></body></html>");
/// ```
/// @endDocuBlock
////////////////////////////////////////////////////////////////////////////////
`response.send(value)`
Sets the response body to the specified *value*. If *value* is a Buffer
object, the content type will be set to `application/octet-stream` if not
yet set. If *value* is a string, the content type will be set to `text/html`
if not yet set. If *value* is an object, it will be treated as in `res.json`.
@EXAMPLES
```js
response.send({"born": "December 12, 1915"});
response.send(new Buffer("some binary data"));
response.send("<html><head><title>Hello World</title></head><body></body></html>");
```

47
Documentation/DocuBlocks/JSF_foxx_BaseMiddleware_response_sendFile.md
View File

@ -1,24 +1,23 @@
////////////////////////////////////////////////////////////////////////////////
/// @startDocuBlock JSF_foxx_BaseMiddleware_response_sendFile
///
/// `response.sendFile(filename, options)`
///
/// Sets the content of the specified file as the response body. The filename
/// must be absolute. If no content type is yet set for the response, the
/// response's content type will be determined automatically based
/// on the filename extension. If no content type is known for the extension,
/// the content type will default to `application/octet-stream`.
///
/// The `options` array can be used to control the behavior of sendFile.
/// Currently only the following option exists:
/// - `lastModified`: if set to true, the last modification date and time
/// of the file will be returned in the `Last-Modified` HTTP header
///
/// @EXAMPLES
///
/// ```js
/// response.sendFile('/tmp/results.json');
/// response.sendFile(applicationContext.fileName('image.png'), { lastModified: true });
/// ```
/// @endDocuBlock
////////////////////////////////////////////////////////////////////////////////
`response.sendFile(filename, options)`
Sets the content of the specified file as the response body. The filename
must be absolute. If no content type is yet set for the response, the
response's content type will be determined automatically based
on the filename extension. If no content type is known for the extension,
the content type will default to `application/octet-stream`.
The `options` array can be used to control the behavior of sendFile.
Currently only the following option exists:
- `lastModified`: if set to true, the last modification date and time
of the file will be returned in the `Last-Modified` HTTP header
@EXAMPLES
```js
response.sendFile('/tmp/results.json');
response.sendFile(applicationContext.fileName('image.png'), { lastModified: true });
```

47
Documentation/DocuBlocks/JSF_foxx_BaseMiddleware_response_set.md
View File

@ -1,24 +1,23 @@
////////////////////////////////////////////////////////////////////////////////
/// @startDocuBlock JSF_foxx_BaseMiddleware_response_set
///
/// `response.set(key, value)`
///
/// Set a header attribute, for example:
///
/// @EXAMPLES
///
/// ```js
/// response.set("Content-Length", 123);
/// response.set("Content-Type", "text/plain");
/// ```
///
/// or alternatively:
///
/// ```js
/// response.set({
/// "Content-Length": "123",
/// "Content-Type": "text/plain"
/// });
/// ```
/// @endDocuBlock
////////////////////////////////////////////////////////////////////////////////
`response.set(key, value)`
Set a header attribute, for example:
@EXAMPLES
```js
response.set("Content-Length", 123);
response.set("Content-Type", "text/plain");
```
or alternatively:
```js
response.set({
"Content-Length": "123",
"Content-Type": "text/plain"
});
```

27
Documentation/DocuBlocks/JSF_foxx_BaseMiddleware_response_status.md
View File

@ -1,14 +1,13 @@
////////////////////////////////////////////////////////////////////////////////
/// @startDocuBlock JSF_foxx_BaseMiddleware_response_status
///
/// `response.status(code)`
///
/// Set the status *code* of your response, for example:
///
/// @EXAMPLES
///
/// ```
/// response.status(404);
/// ```
/// @endDocuBlock
////////////////////////////////////////////////////////////////////////////////
`response.status(code)`
Set the status *code* of your response, for example:
@EXAMPLES
```
response.status(404);
```

35
Documentation/DocuBlocks/JSF_foxx_RequestContextBuffer_errorResponse.md
View File

@ -1,18 +1,17 @@
////////////////////////////////////////////////////////////////////////////////
/// @startDocuBlock JSF_foxx_RequestContextBuffer_errorResponse
///
/// `Controller.allRoutes.errorResponse(errorClass, code, description)`
///
/// This is equal to invoking `Route.errorResponse` on all routes bound to this controller.
///
/// *Examples*
///
/// ```js
/// app.allRoutes.errorResponse(FoxxyError, 303, "This went completely wrong. Sorry!");
///
/// app.get("/foxx", function {
/// // Do something
/// });
/// ```
/// @endDocuBlock
////////////////////////////////////////////////////////////////////////////////
`Controller.allRoutes.errorResponse(errorClass, code, description)`
This is equal to invoking `Route.errorResponse` on all routes bound to this controller.
*Examples*
```js
app.allRoutes.errorResponse(FoxxyError, 303, "This went completely wrong. Sorry!");
app.get("/foxx", function {
// Do something
});
```

35
Documentation/DocuBlocks/JSF_foxx_RequestContextBuffer_onlyIf.md
View File

@ -1,18 +1,17 @@
////////////////////////////////////////////////////////////////////////////////
/// @startDocuBlock JSF_foxx_RequestContextBuffer_onlyIf
///
/// `Controller.allRoutes.onlyIf(code, reason)`
///
/// This is equal to invoking `Route.onlyIf` on all routes bound to this controller.
///
/// *Examples*
///
/// ```js
/// app.allRoutes.onlyIf(myPersonalCheck);
///
/// app.get("/foxx", function {
/// // Do something
/// });
/// ```
/// @endDocuBlock
////////////////////////////////////////////////////////////////////////////////
`Controller.allRoutes.onlyIf(code, reason)`
This is equal to invoking `Route.onlyIf` on all routes bound to this controller.
*Examples*
```js
app.allRoutes.onlyIf(myPersonalCheck);
app.get("/foxx", function {
// Do something
});
```

35
Documentation/DocuBlocks/JSF_foxx_RequestContextBuffer_onlyIfAuthenticated.md
View File

@ -1,18 +1,17 @@
////////////////////////////////////////////////////////////////////////////////
/// @startDocuBlock JSF_foxx_RequestContextBuffer_onlyIfAuthenticated
///
/// `Controller.allRoutes.onlyIfAuthenticated(code, description)`
///
/// This is equal to invoking `Route.onlyIfAuthenticated` on all routes bound to this controller.
///
/// *Examples*
///
/// ```js
/// app.allRoutes.onlyIfAuthenticated(401, "You need to be authenticated");
///
/// app.get("/foxx", function {
/// // Do something
/// });
/// ```
/// @endDocuBlock
////////////////////////////////////////////////////////////////////////////////
`Controller.allRoutes.onlyIfAuthenticated(code, description)`
This is equal to invoking `Route.onlyIfAuthenticated` on all routes bound to this controller.
*Examples*
```js
app.allRoutes.onlyIfAuthenticated(401, "You need to be authenticated");
app.get("/foxx", function {
// Do something
});
```

63
Documentation/DocuBlocks/JSF_foxx_RequestContextBuffer_pathParam.md
View File

@ -1,32 +1,31 @@
////////////////////////////////////////////////////////////////////////////////
/// @startDocuBlock JSF_foxx_RequestContextBuffer_pathParam
///
/// `Controller.allRoutes.pathParam(id, options)`
///
/// This is equal to invoking `Route.pathParam` on all routes bound to this controller.
///
/// *Examples*
///
/// ```js
/// app.allRoutes.pathParam("id", joi.string().required().description("Id of the Foxx"));
///
/// app.get("/foxx/:id", function {
/// // Secured by pathParam
/// });
/// ```
///
/// You can also pass in a configuration object instead:
///
/// ```js
/// app.allRoutes.pathParam("id", {
/// type: joi.string(),
/// required: true,
/// description: "Id of the Foxx"
/// });
///
/// app.get("/foxx/:id", function {
/// // Secured by pathParam
/// });
/// ```
/// @endDocuBlock
////////////////////////////////////////////////////////////////////////////////
`Controller.allRoutes.pathParam(id, options)`
This is equal to invoking `Route.pathParam` on all routes bound to this controller.
*Examples*
```js
app.allRoutes.pathParam("id", joi.string().required().description("Id of the Foxx"));
app.get("/foxx/:id", function {
// Secured by pathParam
});
```
You can also pass in a configuration object instead:
```js
app.allRoutes.pathParam("id", {
type: joi.string(),
required: true,
description: "Id of the Foxx"
});
app.get("/foxx/:id", function {
// Secured by pathParam
});
```

71
Documentation/DocuBlocks/JSF_foxx_RequestContextBuffer_queryParam.md
View File

@ -1,36 +1,35 @@
////////////////////////////////////////////////////////////////////////////////
/// @startDocuBlock JSF_foxx_RequestContextBuffer_queryParam
///
/// `Controller.allRoutes.queryParam(id, options)`
///
/// This is equal to invoking `Route.queryParam` on all routes bound to this controller.
///
/// *Examples*
///
/// ```js
/// app.allroutes.queryParam("id",
/// joi.string()
/// .required()
/// .description("Id of the Foxx")
/// .meta({allowMultiple: false})
/// });
///
/// app.get("/foxx", function {
/// // Do something
/// });
/// ```
///
/// You can also pass in a configuration object instead:
///
/// ```js
/// app.allroutes.queryParam("id", {
/// type: joi.string().required().description("Id of the Foxx"),
/// allowMultiple: false
/// });
///
/// app.get("/foxx", function {
/// // Do something
/// });
/// ```
/// @endDocuBlock
////////////////////////////////////////////////////////////////////////////////
`Controller.allRoutes.queryParam(id, options)`
This is equal to invoking `Route.queryParam` on all routes bound to this controller.
*Examples*
```js
app.allroutes.queryParam("id",
joi.string()
.required()
.description("Id of the Foxx")
.meta({allowMultiple: false})
});
app.get("/foxx", function {
// Do something
});
```
You can also pass in a configuration object instead:
```js
app.allroutes.queryParam("id", {
type: joi.string().required().description("Id of the Foxx"),
allowMultiple: false
});
app.get("/foxx", function {
// Do something
});
```

153
Documentation/DocuBlocks/JSF_foxx_RequestContext_bodyParam.md
View File

@ -1,77 +1,76 @@
////////////////////////////////////////////////////////////////////////////////
/// @startDocuBlock JSF_foxx_RequestContext_bodyParam
///
/// `Route.bodyParam(paramName, options)`
///
/// Defines that this route expects a JSON body when requested and binds it to
/// a pseudo parameter with the name `paramName`.
/// The body can than be read in the the handler using `req.params(paramName)` on the request object.
/// In the `options` parameter you can define how a valid request body should look like.
/// This definition can be done in two ways, either using *joi* directly.
/// Accessing the body in this case will give you a JSON object.
/// The other way is to use a Foxx *Model*.
/// Accessing the body in this case will give you an instance of this Model.
/// For both ways an entry for the body will be added in the Documentation in ArangoDBs WebInterface.
/// For information about how to annotate your models, see the Model section.
/// All requests sending a body that does not match the validation given this way
/// will automatically be rejected.
///
/// You can also wrap the definition into an array, in this case this route
/// expects a body of type array containing arbitrary many valid objects.
/// Accessing the body parameter will then of course return an array of objects.
///
/// Note: The behavior of `bodyParam` changes depending on the `rootElement` option
/// set in the [manifest](../Develop/Manifest.md). If it is set to `true`, it is
/// expected that the body is an
/// object with a key of the same name as the `paramName` argument.
/// The value of this object is either a single object or in the case of a multi
/// element an array of objects.
///
/// *Parameter*
///
/// * *paramName*: name of the body parameter in `req.parameters`.
/// * *options*: a joi schema or an object with the following properties:
/// * *description*: the documentation description of the request body.
/// * *type*: the Foxx model or joi schema to use.
/// * *allowInvalid* (optional): `true` if validation should be skipped. (Default: `false`)
///
/// *Examples*
///
/// ```js
/// app.post("/foxx", function (req, res) {
/// var foxxBody = req.parameters.foxxBody;
/// // Do something with foxxBody
/// }).bodyParam("foxxBody", {
/// description: "Body of the Foxx",
/// type: FoxxBodyModel
/// });
/// ```
///
/// Using a joi schema:
///
/// ```js
/// app.post("/foxx", function (req, res) {
/// var joiBody = req.parameters.joiBody;
/// // Do something with the number
/// }).bodyParam("joiBody", {
/// type: joi.number().integer().min(5),
/// description: "A number greater than five",
/// allowInvalid: false // default
/// });
/// ```
///
/// Shorthand version:
///
/// ```js
/// app.post("/foxx", function (req, res) {
/// var joiBody = req.parameters.joiBody;
/// // Do something with the number
/// }).bodyParam(
/// "joiBody",
/// joi.number().integer().min(5)
/// .description("A number greater than five")
/// .meta({allowInvalid: false}) // default
/// );
/// ```
/// @endDocuBlock
////////////////////////////////////////////////////////////////////////////////
`Route.bodyParam(paramName, options)`
Defines that this route expects a JSON body when requested and binds it to
a pseudo parameter with the name `paramName`.
The body can than be read in the the handler using `req.params(paramName)` on the request object.
In the `options` parameter you can define how a valid request body should look like.
This definition can be done in two ways, either using *joi* directly.
Accessing the body in this case will give you a JSON object.
The other way is to use a Foxx *Model*.
Accessing the body in this case will give you an instance of this Model.
For both ways an entry for the body will be added in the Documentation in ArangoDBs WebInterface.
For information about how to annotate your models, see the Model section.
All requests sending a body that does not match the validation given this way
will automatically be rejected.
You can also wrap the definition into an array, in this case this route
expects a body of type array containing arbitrary many valid objects.
Accessing the body parameter will then of course return an array of objects.
Note: The behavior of `bodyParam` changes depending on the `rootElement` option
set in the [manifest](../Develop/Manifest.md). If it is set to `true`, it is
expected that the body is an
object with a key of the same name as the `paramName` argument.
The value of this object is either a single object or in the case of a multi
element an array of objects.
*Parameter*
* *paramName*: name of the body parameter in `req.parameters`.
* *options*: a joi schema or an object with the following properties:
* *description*: the documentation description of the request body.
* *type*: the Foxx model or joi schema to use.
* *allowInvalid* (optional): `true` if validation should be skipped. (Default: `false`)
*Examples*
```js
app.post("/foxx", function (req, res) {
var foxxBody = req.parameters.foxxBody;
// Do something with foxxBody
}).bodyParam("foxxBody", {
description: "Body of the Foxx",
type: FoxxBodyModel
});
```
Using a joi schema:
```js
app.post("/foxx", function (req, res) {
var joiBody = req.parameters.joiBody;
// Do something with the number
}).bodyParam("joiBody", {
type: joi.number().integer().min(5),
description: "A number greater than five",
allowInvalid: false // default
});
```
Shorthand version:
```js
app.post("/foxx", function (req, res) {
var joiBody = req.parameters.joiBody;
// Do something with the number
}).bodyParam(
"joiBody",
joi.number().integer().min(5)
.description("A number greater than five")
.meta({allowInvalid: false}) // default
);
```

87
Documentation/DocuBlocks/JSF_foxx_RequestContext_errorResponse.md
View File

@ -1,44 +1,43 @@
////////////////////////////////////////////////////////////////////////////////
/// @startDocuBlock JSF_foxx_RequestContext_errorResponse
///
/// `Route.errorResponse(errorClassOrName, code, description, [callback])`
///
/// Define a reaction to a thrown error for this route: If your handler throws an error
/// of the errorClass defined in `errorClassOrName` or the error has an attribute `name` equal to `errorClassOrName`,
/// it will be caught and the response object will be filled with the given
/// status code and a JSON with error set to your description as the body.
///
/// If you want more control over the returned JSON, you can give an optional fourth
/// parameter in form of a function. It gets the error as an argument, the return
/// value will be transformed into JSON and then be used as the body.
/// The status code will be used as described above. The description will be used for
/// the documentation.
///
/// It also adds documentation for this error response to the generated documentation.
///
/// *Examples*
///
/// ```js
/// /* define our own error type, FoxxyError */
/// var FoxxyError = function (message) {
/// this.name = "FError";
/// this.message = "the following FoxxyError occurred: " + message;
/// };
/// FoxxyError.prototype = new Error();
///
/// app.get("/foxx", function {
/// /* throws a FoxxyError */
/// throw new FoxxyError();
/// }).errorResponse(FoxxyError, 303, "This went completely wrong. Sorry!");
///
/// app.get("/foxx", function {
/// throw new FoxxyError("oops!");
/// }).errorResponse("FError", 303, "This went completely wrong. Sorry!", function (e) {
/// return {
/// code: 123,
/// desc: e.message
/// };
/// });
/// ```
/// @endDocuBlock
////////////////////////////////////////////////////////////////////////////////
`Route.errorResponse(errorClassOrName, code, description, [callback])`
Define a reaction to a thrown error for this route: If your handler throws an error
of the errorClass defined in `errorClassOrName` or the error has an attribute `name` equal to `errorClassOrName`,
it will be caught and the response object will be filled with the given
status code and a JSON with error set to your description as the body.
If you want more control over the returned JSON, you can give an optional fourth
parameter in form of a function. It gets the error as an argument, the return
value will be transformed into JSON and then be used as the body.
The status code will be used as described above. The description will be used for
the documentation.
It also adds documentation for this error response to the generated documentation.
*Examples*
```js
/* define our own error type, FoxxyError */
var FoxxyError = function (message) {
this.name = "FError";
this.message = "the following FoxxyError occurred: " + message;
};
FoxxyError.prototype = new Error();
app.get("/foxx", function {
/* throws a FoxxyError */
throw new FoxxyError();
}).errorResponse(FoxxyError, 303, "This went completely wrong. Sorry!");
app.get("/foxx", function {
throw new FoxxyError("oops!");
}).errorResponse("FError", 303, "This went completely wrong. Sorry!", function (e) {
return {
code: 123,
desc: e.message
};
});
```

63
Documentation/DocuBlocks/JSF_foxx_RequestContext_notes.md
View File

@ -1,32 +1,31 @@
////////////////////////////////////////////////////////////////////////////////
/// @startDocuBlock JSF_foxx_RequestContext_notes
///
/// `Route.notes(...description)`
///
/// Set the long description for this route in the documentation
//
/// *Examples*
///
/// Version with comment:
///
/// ```js
/// /** Short description
/// *
/// * Longer description
/// * with multiple lines
/// */
/// app.get("/foxx", function() {
/// });
/// ```
///
/// is identical to:
///
/// ```js
/// app.get("/foxx", function() {
/// })
/// .summary("Short description")
/// .notes(["Longer description", "with multiple lines"]);
/// ```
///
/// @endDocuBlock
////////////////////////////////////////////////////////////////////////////////
`Route.notes(...description)`
Set the long description for this route in the documentation
*Examples*
Version with comment:
```js
/** Short description
*
* Longer description
* with multiple lines
*/
app.get("/foxx", function() {
});
```
is identical to:
```js
app.get("/foxx", function() {
})
.summary("Short description")
.notes(["Longer description", "with multiple lines"]);
```

41
Documentation/DocuBlocks/JSF_foxx_RequestContext_onlyIf.md
View File

@ -1,21 +1,20 @@
////////////////////////////////////////////////////////////////////////////////
/// @startDocuBlock JSF_foxx_RequestContext_onlyIf
///
/// `Route.onlyIf(check)`
///
/// This functionality is used to secure a route by applying a checking function
/// on the request beforehand, for example the check authorization.
/// It expects `check` to be a function that takes the request object as first parameter.
/// This function is executed before the actual handler is invoked.
/// If `check` throws an error the actual handler will not be invoked.
/// Remember to provide an `errorResponse` on the route as well to define the behavior in this case.
///
/// *Examples*
///
/// ```js
/// app.get("/foxx", function {
/// // Do something
/// }).onlyIf(aFunction).errorResponse(ErrorClass, 303, "This went completely wrong. Sorry!");
/// ```
/// @endDocuBlock
////////////////////////////////////////////////////////////////////////////////
`Route.onlyIf(check)`
This functionality is used to secure a route by applying a checking function
on the request beforehand, for example the check authorization.
It expects `check` to be a function that takes the request object as first parameter.
This function is executed before the actual handler is invoked.
If `check` throws an error the actual handler will not be invoked.
Remember to provide an `errorResponse` on the route as well to define the behavior in this case.
*Examples*
```js
app.get("/foxx", function {
// Do something
}).onlyIf(aFunction).errorResponse(ErrorClass, 303, "This went completely wrong. Sorry!");
```

39
Documentation/DocuBlocks/JSF_foxx_RequestContext_onlyIfAuthenticated.md
View File

@ -1,20 +1,19 @@
////////////////////////////////////////////////////////////////////////////////
/// @startDocuBlock JSF_foxx_RequestContext_onlyIfAuthenticated
///
/// `FoxxController#onlyIfAuthenticated(code, reason)`
///
/// Please activate sessions for this app if you want to use this function.
/// Or activate authentication (deprecated).
/// If the user is logged in, it will do nothing. Otherwise it will respond with
/// the status code and the reason you provided (the route handler won't be called).
/// This will also add the according documentation for this route.
///
/// *Examples*
///
/// ```js
/// app.get("/foxx", function {
/// // Do something
/// }).onlyIfAuthenticated(401, "You need to be authenticated");
/// ```
/// @endDocuBlock
////////////////////////////////////////////////////////////////////////////////
`FoxxController#onlyIfAuthenticated(code, reason)`
Please activate sessions for this app if you want to use this function.
Or activate authentication (deprecated).
If the user is logged in, it will do nothing. Otherwise it will respond with
the status code and the reason you provided (the route handler won't be called).
This will also add the according documentation for this route.
*Examples*
```js
app.get("/foxx", function {
// Do something
}).onlyIfAuthenticated(401, "You need to be authenticated");
```

87
Documentation/DocuBlocks/JSF_foxx_RequestContext_pathParam.md
View File

@ -1,44 +1,43 @@
////////////////////////////////////////////////////////////////////////////////
/// @startDocuBlock JSF_foxx_RequestContext_pathParam
///
/// `Route.pathParam(id, options)`
///
/// If you defined a route "/foxx/:name", containing a parameter called `name` you can
/// constrain which format this parameter is allowed to have.
/// This format is defined using *joi* in the `options` parameter.
/// Using this function will at first allow you to access this parameter in your
/// route handler using `req.params(id)`, will reject any request having a paramter
/// that does not match the *joi* definition and creates a documentation for this
/// parameter in ArangoDBs WebInterface.
///
/// For more information on *joi* see [the official Joi documentation](https://github.com/spumko/joi).
///
/// *Parameter*
///
/// * *id*: name of the param.
/// * *options*: a joi schema or an object with the following properties:
/// * *type*: a joi schema.
/// * *description*: documentation description for the parameter.
/// * *required* (optional): whether the parameter is required. Default: determined by *type*.
///
/// *Examples*
///
/// ```js
/// app.get("/foxx/:name", function {
/// // Do something
/// }).pathParam("name", joi.string().required().description("Name of the Foxx"));
/// ```
///
/// You can also pass in a configuration object instead:
///
/// ```js
/// app.get("/foxx/:name", function {
/// // Do something
/// }).pathParam("name", {
/// type: joi.string(),
/// required: true,
/// description: "Name of the Foxx"
/// });
/// ```
/// @endDocuBlock
////////////////////////////////////////////////////////////////////////////////
`Route.pathParam(id, options)`
If you defined a route "/foxx/:name", containing a parameter called `name` you can
constrain which format this parameter is allowed to have.
This format is defined using *joi* in the `options` parameter.
Using this function will at first allow you to access this parameter in your
route handler using `req.params(id)`, will reject any request having a paramter
that does not match the *joi* definition and creates a documentation for this
parameter in ArangoDBs WebInterface.
For more information on *joi* see [the official Joi documentation](https://github.com/spumko/joi).
*Parameter*
* *id*: name of the param.
* *options*: a joi schema or an object with the following properties:
* *type*: a joi schema.
* *description*: documentation description for the parameter.
* *required* (optional): whether the parameter is required. Default: determined by *type*.
*Examples*
```js
app.get("/foxx/:name", function {
// Do something
}).pathParam("name", joi.string().required().description("Name of the Foxx"));
```
You can also pass in a configuration object instead:
```js
app.get("/foxx/:name", function {
// Do something
}).pathParam("name", {
type: joi.string(),
required: true,
description: "Name of the Foxx"
});
```

105
Documentation/DocuBlocks/JSF_foxx_RequestContext_queryParam.md
View File

@ -1,53 +1,52 @@
////////////////////////////////////////////////////////////////////////////////
/// @startDocuBlock JSF_foxx_RequestContext_queryParam
///
/// `Route.queryParam(id, options)`
///
/// Describe a query parameter:
///
/// If you defined a route "/foxx", you can allow a query paramter with the
/// name `id` on it and constrain the format of this parameter by giving it a *joi* type in the `options` parameter.
/// Using this function will at first allow you to access this parameter in your
/// route handler using `req.params(id)`, will reject any request having a paramter
/// that does not match the *joi* definition and creates a documentation for this
/// parameter in ArangoDBs WebInterface.
///
/// For more information on *joi* see [the official Joi documentation](https://github.com/spumko/joi).
///
/// You can also provide a description of this parameter and
/// whether you can provide the parameter multiple times.
///
/// *Parameter*
///
/// * *id*: name of the parameter
/// * *options*: a joi schema or an object with the following properties:
/// * *type*: a joi schema
/// * *description*: documentation description for this param.
/// * *required* (optional): whether the param is required. Default: determined by *type*.
/// * *allowMultiple* (optional): whether the param can be specified more than once. Default: `false`.
///
/// *Examples*
///
/// ```js
/// app.get("/foxx", function {
/// // Do something
/// }).queryParam("id",
/// joi.string()
/// .required()
/// .description("Id of the Foxx")
/// .meta({allowMultiple: false})
/// });
/// ```
///
/// You can also pass in a configuration object instead:
///
/// ```js
/// app.get("/foxx", function {
/// // Do something
/// }).queryParam("id", {
/// type: joi.string().required().description("Id of the Foxx"),
/// allowMultiple: false
/// });
/// ```
/// @endDocuBlock
////////////////////////////////////////////////////////////////////////////////
`Route.queryParam(id, options)`
Describe a query parameter:
If you defined a route "/foxx", you can allow a query paramter with the
name `id` on it and constrain the format of this parameter by giving it a *joi* type in the `options` parameter.
Using this function will at first allow you to access this parameter in your
route handler using `req.params(id)`, will reject any request having a paramter
that does not match the *joi* definition and creates a documentation for this
parameter in ArangoDBs WebInterface.
For more information on *joi* see [the official Joi documentation](https://github.com/spumko/joi).
You can also provide a description of this parameter and
whether you can provide the parameter multiple times.
*Parameter*
* *id*: name of the parameter
* *options*: a joi schema or an object with the following properties:
* *type*: a joi schema
* *description*: documentation description for this param.
* *required* (optional): whether the param is required. Default: determined by *type*.
* *allowMultiple* (optional): whether the param can be specified more than once. Default: `false`.
*Examples*
```js
app.get("/foxx", function {
// Do something
}).queryParam("id",
joi.string()
.required()
.description("Id of the Foxx")
.meta({allowMultiple: false})
});
```
You can also pass in a configuration object instead:
```js
app.get("/foxx", function {
// Do something
}).queryParam("id", {
type: joi.string().required().description("Id of the Foxx"),
allowMultiple: false
});
```

71
Documentation/DocuBlocks/JSF_foxx_RequestContext_summary.md
View File

@ -1,36 +1,35 @@
////////////////////////////////////////////////////////////////////////////////
/// @startDocuBlock JSF_foxx_RequestContext_summary
///
/// `Route.summary(description)`
///
/// Set the summary for this route in the documentation.
/// Can't be longer than 8192 characters.
/// This is equal to using JavaDoc style comments right above your function.
/// If you provide both comment and `summary()` the call to `summary()` wins
/// and will be used.
///
/// *Examples*
///
/// Version with comment:
///
/// ```js
/// /** Short description
/// *
/// * Longer description
/// * with multiple lines
/// */
/// app.get("/foxx", function() {
/// });
/// ```
///
/// is identical to:
///
/// ```js
/// app.get("/foxx", function() {
/// })
/// .summary("Short description")
/// .notes(["Longer description", "with multiple lines"]);
/// ```
///
/// @endDocuBlock
////////////////////////////////////////////////////////////////////////////////
`Route.summary(description)`
Set the summary for this route in the documentation.
Can't be longer than 8192 characters.
This is equal to using JavaDoc style comments right above your function.
If you provide both comment and `summary()` the call to `summary()` wins
and will be used.
*Examples*
Version with comment:
```js
/** Short description
*
* Longer description
* with multiple lines
*/
app.get("/foxx", function() {
});
```
is identical to:
```js
app.get("/foxx", function() {
})
.summary("Short description")
.notes(["Longer description", "with multiple lines"]);
```

51
Documentation/DocuBlocks/JSF_foxx_controller_activateAuthentication.md
View File

@ -1,26 +1,25 @@
////////////////////////////////////////////////////////////////////////////////
/// @startDocuBlock JSF_foxx_controller_activateAuthentication
///
/// `Controller.activateAuthentication(opts)`
///
/// To activate authentication for this controller, call this function before defining any routes.
/// In the `opts` object you can set the following keys:
///
/// * *type*: Currently we only support *cookie*, but this will change in the future
/// * *cookieLifetime*: An integer. Lifetime of cookies in seconds
/// * *cookieName*: A string used as the name of the cookie
/// * *sessionLifetime*: An integer. Lifetime of sessions in seconds
///
/// @EXAMPLES
///
/// ```js
/// app.activateAuthentication({
/// type: "cookie",
/// cookieLifetime: 360000,
/// cookieName: "my_cookie",
/// sessionLifetime: 400,
/// });
/// ```
///
/// @endDocuBlock
////////////////////////////////////////////////////////////////////////////////
`Controller.activateAuthentication(opts)`
To activate authentication for this controller, call this function before defining any routes.
In the `opts` object you can set the following keys:
* *type*: Currently we only support *cookie*, but this will change in the future
* *cookieLifetime*: An integer. Lifetime of cookies in seconds
* *cookieName*: A string used as the name of the cookie
* *sessionLifetime*: An integer. Lifetime of sessions in seconds
@EXAMPLES
```js
app.activateAuthentication({
type: "cookie",
cookieLifetime: 360000,
cookieName: "my_cookie",
sessionLifetime: 400,
});
```

35
Documentation/DocuBlocks/JSF_foxx_controller_after.md
View File

@ -1,18 +1,17 @@
////////////////////////////////////////////////////////////////////////////////
/// @startDocuBlock JSF_foxx_controller_after
///
/// `Controller.after(path, callback)`
///
/// Similar to `Controller.before(path, callback)` but `callback` will be invoked
/// after the request is handled in the specific route.
///
/// @EXAMPLES
///
/// ```js
/// app.after('/high/way', function(req, res) {
/// //Do some crazy response logging
/// });
/// ```
///
/// @endDocuBlock
////////////////////////////////////////////////////////////////////////////////
`Controller.after(path, callback)`
Similar to `Controller.before(path, callback)` but `callback` will be invoked
after the request is handled in the specific route.
@EXAMPLES
```js
app.after('/high/way', function(req, res) {
//Do some crazy response logging
});
```

125
Documentation/DocuBlocks/JSF_foxx_controller_apiDocumentation.md
View File

@ -1,63 +1,62 @@
////////////////////////////////////////////////////////////////////////////////
/// @startDocuBlock JSF_foxx_controller_apiDocumentation
///
/// `Controller.apiDocumentation(path, [opts])`
///
/// Mounts the API documentation (Swagger) at the given `path`.
///
/// Note that the `path` can use path parameters as usual but must not use any
/// wildcard (`*`) or optional (`:name?`) parameters.
///
/// The optional **opts** can be an object with any of the following properties:
///
/// * **before**: a function that will be executed before a request to
/// this endpoint is processed further.
/// * **appPath**: the mount point of the app for which documentation will be
/// shown. Default: the mount point of the active app.
/// * **indexFile**: file path or file name of the Swagger HTML file.
/// Default: `"index.html"`.
/// * **swaggerJson**: file path or file name of the Swagger API description JSON
/// file or a function `swaggerJson(req, res, opts)` that sends a Swagger API
/// description in JSON. Default: the built-in Swagger description generator.
/// * **swaggerRoot**: absolute path that will be used as the path path for any
/// relative paths of the documentation assets, **swaggerJson** file and
/// the **indexFile**. Default: the built-in Swagger distribution.
///
/// If **opts** is a function, it will be used as the value of **opts.before**.
///
/// If **opts.before** returns `false`, the request will not be processed
/// further.
///
/// If **opts.before** returns an object, any properties will override the
/// equivalent properties of **opts** for the current request.
///
/// Of course all **before**, **after** or **around** functions defined on the
/// controller will also be executed as usual.
///
/// **Examples**
///
/// ```js
/// controller.apiDocumentation('/my/dox');
///
/// ```
///
/// A request to `/my/dox` will be redirect to `/my/dox/index.html`,
/// which will show the API documentation of the active app.
///
/// ```js
/// controller.apiDocumentation('/my/dox', function (req, res) {
/// if (!req.session.get('uid')) {
/// res.status(403);
/// res.json({error: 'only logged in users may see the API'});
/// return false;
/// }
/// return {appPath: req.parameters.mount};
/// });
/// ```
///
/// A request to `/my/dox/index.html?mount=/_admin/aardvark` will show the
/// API documentation of the admin frontend (mounted at `/_admin/aardvark`).
/// If the user is not logged in, the error message will be shown instead.
///
/// @endDocuBlock
////////////////////////////////////////////////////////////////////////////////
`Controller.apiDocumentation(path, [opts])`
Mounts the API documentation (Swagger) at the given `path`.
Note that the `path` can use path parameters as usual but must not use any
wildcard (`*`) or optional (`:name?`) parameters.
The optional **opts** can be an object with any of the following properties:
* **before**: a function that will be executed before a request to
this endpoint is processed further.
* **appPath**: the mount point of the app for which documentation will be
shown. Default: the mount point of the active app.
* **indexFile**: file path or file name of the Swagger HTML file.
Default: `"index.html"`.
* **swaggerJson**: file path or file name of the Swagger API description JSON
file or a function `swaggerJson(req, res, opts)` that sends a Swagger API
description in JSON. Default: the built-in Swagger description generator.
* **swaggerRoot**: absolute path that will be used as the path path for any
relative paths of the documentation assets, **swaggerJson** file and
the **indexFile**. Default: the built-in Swagger distribution.
If **opts** is a function, it will be used as the value of **opts.before**.
If **opts.before** returns `false`, the request will not be processed
further.
If **opts.before** returns an object, any properties will override the
equivalent properties of **opts** for the current request.
Of course all **before**, **after** or **around** functions defined on the
controller will also be executed as usual.
**Examples**
```js
controller.apiDocumentation('/my/dox');
```
A request to `/my/dox` will be redirect to `/my/dox/index.html`,
which will show the API documentation of the active app.
```js
controller.apiDocumentation('/my/dox', function (req, res) {
if (!req.session.get('uid')) {
res.status(403);
res.json({error: 'only logged in users may see the API'});
return false;
}
return {appPath: req.parameters.mount};
});
```
A request to `/my/dox/index.html?mount=/_admin/aardvark` will show the
API documentation of the admin frontend (mounted at `/_admin/aardvark`).
If the user is not logged in, the error message will be shown instead.

51
Documentation/DocuBlocks/JSF_foxx_controller_around.md
View File

@ -1,26 +1,25 @@
////////////////////////////////////////////////////////////////////////////////
/// @startDocuBlock JSF_foxx_controller_around
///
/// `Controller.around(path, callback)`
///
/// Similar to `Controller.before(path, callback)` `callback` will be invoked
/// instead of the specific handler.
/// `callback` takes two additional paramaters `opts` and `next` where
/// `opts` contains options assigned to the route and `next` is a function.
/// Whenever you call `next` in `callback` the specific handler is invoked,
/// if you do not call `next` the specific handler will not be invoked at all.
/// So using around you can execute code before and after a specific handler
/// and even call the handler only under certain circumstances.
/// If you omit `path` `callback` will be called on every request.
///
/// @EXAMPLES
///
/// ```js
/// app.around('/high/way', function(req, res, opts, next) {
/// //Do some crazy request logging
/// next();
/// //Do some more crazy request logging
/// });
/// ```
/// @endDocuBlock
////////////////////////////////////////////////////////////////////////////////
`Controller.around(path, callback)`
Similar to `Controller.before(path, callback)` `callback` will be invoked
instead of the specific handler.
`callback` takes two additional paramaters `opts` and `next` where
`opts` contains options assigned to the route and `next` is a function.
Whenever you call `next` in `callback` the specific handler is invoked,
if you do not call `next` the specific handler will not be invoked at all.
So using around you can execute code before and after a specific handler
and even call the handler only under certain circumstances.
If you omit `path` `callback` will be called on every request.
@EXAMPLES
```js
app.around('/high/way', function(req, res, opts, next) {
//Do some crazy request logging
next();
//Do some more crazy request logging
});
```

51
Documentation/DocuBlocks/JSF_foxx_controller_before.md
View File

@ -1,26 +1,25 @@
////////////////////////////////////////////////////////////////////////////////
/// @startDocuBlock JSF_foxx_controller_before
///
/// `Controller.before(path, callback)`
///
/// Defines an additional function on the route `path` which will be executed
/// before the callback defined for a specific HTTP verb is executed.
/// The `callback` function has the same signature as the `callback` in the
/// specific route.
/// You can also omit the `path`, in this case `callback` will be executed
/// before handleing any request in this Controller.
///
/// If `callback` returns the Boolean value `false`, the route handling
/// will not proceed. You can use this to intercept invalid or unauthorized
/// requests and prevent them from being passed to the matching routes.
///
/// @EXAMPLES
///
/// ```js
/// app.before('/high/way', function(req, res) {
/// //Do some crazy request logging
/// });
/// ```
///
/// @endDocuBlock
////////////////////////////////////////////////////////////////////////////////
`Controller.before(path, callback)`
Defines an additional function on the route `path` which will be executed
before the callback defined for a specific HTTP verb is executed.
The `callback` function has the same signature as the `callback` in the
specific route.
You can also omit the `path`, in this case `callback` will be executed
before handleing any request in this Controller.
If `callback` returns the Boolean value `false`, the route handling
will not proceed. You can use this to intercept invalid or unauthorized
requests and prevent them from being passed to the matching routes.
@EXAMPLES
```js
app.before('/high/way', function(req, res) {
//Do some crazy request logging
});
```

65
Documentation/DocuBlocks/JSF_foxx_controller_changePassword.md
View File

@ -1,33 +1,32 @@
////////////////////////////////////////////////////////////////////////////////
/// @startDocuBlock JSF_foxx_controller_changePassword
///
/// FoxxController#changePassword(route, opts)`
///
/// Add a route for the logged in user to change the password.
/// You can provide further customizations via the
/// the options:
///
/// * *passwordField* can be used to adjust the expected attribute
/// in the *post* request. It defaults to *password*.
/// * *onSuccess* is a function that you can define to do something if the change was
/// successful. This includes sending a response to the user. This defaults to a
/// function that returns a JSON with *notice* set to "Changed password!".
/// * *onError* is a function that you can define to do something if the login did not
/// work. This includes sending a response to the user. This defaults to a function
/// that sets the response to 401 and returns a JSON with *error* set to
/// "No session was found".
///
/// Both *onSuccess* and *onError* should take request and result as arguments.
///
/// @EXAMPLES
///
/// ```js
/// app.changePassword('/changePassword', {
/// onSuccess(req, res) {
/// res.json({"success": true});
/// }
/// });
/// ```
///
/// @endDocuBlock
////////////////////////////////////////////////////////////////////////////////
FoxxController#changePassword(route, opts)`
Add a route for the logged in user to change the password.
You can provide further customizations via the
the options:
* *passwordField* can be used to adjust the expected attribute
in the *post* request. It defaults to *password*.
* *onSuccess* is a function that you can define to do something if the change was
successful. This includes sending a response to the user. This defaults to a
function that returns a JSON with *notice* set to "Changed password!".
* *onError* is a function that you can define to do something if the login did not
work. This includes sending a response to the user. This defaults to a function
that sets the response to 401 and returns a JSON with *error* set to
"No session was found".
Both *onSuccess* and *onError* should take request and result as arguments.
@EXAMPLES
```js
app.changePassword('/changePassword', {
onSuccess(req, res) {
res.json({"success": true});
}
});
```

47
Documentation/DocuBlocks/JSF_foxx_controller_delete.md
View File

@ -1,24 +1,23 @@
////////////////////////////////////////////////////////////////////////////////
/// @startDocuBlock JSF_foxx_controller_delete
///
/// `Controller.delete(path, callback)`
///
/// Defines a new route on `path` that handles requests from the HTTP verb `delete`.
/// This route can also be 'parameterized' like `/goose/:barn`.
/// In this case you can later get the value the user provided for `barn`
/// via the `params` function in the `request`.
/// The function defined in `callback` will be invoked whenever this type of
/// request is recieved.
/// `callback` get's two arguments `request` and `response`, see below for further
/// information about these objects.
///
/// @EXAMPLES
///
/// ```js
/// app.delete('/goose/barn', function (req, res) {
/// // Take this request and deal with it!
/// });
/// ```
///
/// @endDocuBlock
////////////////////////////////////////////////////////////////////////////////
`Controller.delete(path, callback)`
Defines a new route on `path` that handles requests from the HTTP verb `delete`.
This route can also be 'parameterized' like `/goose/:barn`.
In this case you can later get the value the user provided for `barn`
via the `params` function in the `request`.
The function defined in `callback` will be invoked whenever this type of
request is recieved.
`callback` get's two arguments `request` and `response`, see below for further
information about these objects.
@EXAMPLES
```js
app.delete('/goose/barn', function (req, res) {
// Take this request and deal with it!
});
```

89
Documentation/DocuBlocks/JSF_foxx_controller_extend.md
View File

@ -1,45 +1,44 @@
////////////////////////////////////////////////////////////////////////////////
/// @startDocuBlock JSF_foxx_controller_extend
///
/// `Controller.extend(extensions)`
///
/// Extends all functions to define routes in this controller.
/// This allows to combine several route extensions with the invocation
/// of a single function.
/// This is especially useful if you use the same input parameter in several routes of
/// your controller and want to apply the same validation, documentation and error handling
/// for it.
///
/// The `extensions` parameter is a JSON object with arbitrary keys.
/// Each key is used as the name of the function you want to define (you cannot overwrite
/// internal functions like `pathParam`) and the value is a function that will be invoked.
/// This function can get arbitrary many arguments and the `this` of the function is bound
/// to the route definition object (e.g. you can use `this.pathParam()`).
/// Your newly defined function is chainable similar to the internal functions.
///
/// **Examples**
///
/// Define a validator for a queryParameter, including documentation and errorResponses
/// in a single command:
///
/// ```js
/// controller.extend({
/// myParam: function (maxValue) {
/// this.queryParam("value", {type: joi.number().required()});
/// this.onlyIf(function(req) {
/// var v = req.param("value");
/// if (v > maxValue) {
/// throw new NumberTooLargeError();
/// }
/// });
/// this.errorResponse(NumberTooLargeError, 400, "The given value is too large");
/// }
/// });
///
/// controller.get("/goose/barn", function(req, res) {
/// // Will only be invoked if the request has parameter value and it is less or equal 5.
/// }).myParam(5);
/// ```
///
/// @endDocuBlock
////////////////////////////////////////////////////////////////////////////////
`Controller.extend(extensions)`
Extends all functions to define routes in this controller.
This allows to combine several route extensions with the invocation
of a single function.
This is especially useful if you use the same input parameter in several routes of
your controller and want to apply the same validation, documentation and error handling
for it.
The `extensions` parameter is a JSON object with arbitrary keys.
Each key is used as the name of the function you want to define (you cannot overwrite
internal functions like `pathParam`) and the value is a function that will be invoked.
This function can get arbitrary many arguments and the `this` of the function is bound
to the route definition object (e.g. you can use `this.pathParam()`).
Your newly defined function is chainable similar to the internal functions.
**Examples**
Define a validator for a queryParameter, including documentation and errorResponses
in a single command:
```js
controller.extend({
myParam: function (maxValue) {
this.queryParam("value", {type: joi.number().required()});
this.onlyIf(function(req) {
var v = req.param("value");
if (v > maxValue) {
throw new NumberTooLargeError();
}
});
this.errorResponse(NumberTooLargeError, 400, "The given value is too large");
}
});
controller.get("/goose/barn", function(req, res) {
// Will only be invoked if the request has parameter value and it is less or equal 5.
}).myParam(5);
```

47
Documentation/DocuBlocks/JSF_foxx_controller_get.md
View File

@ -1,24 +1,23 @@
////////////////////////////////////////////////////////////////////////////////
/// @startDocuBlock JSF_foxx_controller_get
///
/// `Controller.get(path, callback)`
///
/// Defines a new route on `path` that handles requests from the HTTP verb `get`.
/// This route can also be 'parameterized' like `/goose/:barn`.
/// In this case you can later get the value the user provided for `barn`
/// via the `params` function in the `request`.
/// The function defined in `callback` will be invoked whenever this type of
/// request is recieved.
/// `callback` get's two arguments `request` and `response`, see below for further
/// information about these objects.
///
/// @EXAMPLES
///
/// ```js
/// app.get('/goose/barn', function (req, res) {
/// // Take this request and deal with it!
/// });
/// ```
///
/// @endDocuBlock
////////////////////////////////////////////////////////////////////////////////
`Controller.get(path, callback)`
Defines a new route on `path` that handles requests from the HTTP verb `get`.
This route can also be 'parameterized' like `/goose/:barn`.
In this case you can later get the value the user provided for `barn`
via the `params` function in the `request`.
The function defined in `callback` will be invoked whenever this type of
request is recieved.
`callback` get's two arguments `request` and `response`, see below for further
information about these objects.
@EXAMPLES
```js
app.get('/goose/barn', function (req, res) {
// Take this request and deal with it!
});
```

47
Documentation/DocuBlocks/JSF_foxx_controller_head.md
View File

@ -1,24 +1,23 @@
////////////////////////////////////////////////////////////////////////////////
/// @startDocuBlock JSF_foxx_controller_head
///
/// `Controller.head(path, callback)`
///
/// Defines a new route on `path` that handles requests from the HTTP verb `head`.
/// This route can also be 'parameterized' like `/goose/:barn`.
/// In this case you can later get the value the user provided for `barn`
/// via the `params` function in the `request`.
/// The function defined in `callback` will be invoked whenever this type of
/// request is recieved.
/// `callback` get's two arguments `request` and `response`, see below for further
/// information about these objects.
///
/// @EXAMPLES
///
/// ```js
/// app.head('/goose/barn', function (req, res) {
/// // Take this request and deal with it!
/// });
/// ```
///
/// @endDocuBlock
////////////////////////////////////////////////////////////////////////////////
`Controller.head(path, callback)`
Defines a new route on `path` that handles requests from the HTTP verb `head`.
This route can also be 'parameterized' like `/goose/:barn`.
In this case you can later get the value the user provided for `barn`
via the `params` function in the `request`.
The function defined in `callback` will be invoked whenever this type of
request is recieved.
`callback` get's two arguments `request` and `response`, see below for further
information about these objects.
@EXAMPLES
```js
app.head('/goose/barn', function (req, res) {
// Take this request and deal with it!
});
```

41
Documentation/DocuBlocks/JSF_foxx_controller_initializer.md
View File

@ -1,21 +1,20 @@
////////////////////////////////////////////////////////////////////////////////
/// @startDocuBlock JSF_foxx_controller_initializer
///
/// `new Controller(applicationContext, options)`
///
/// This creates a new Controller. The first argument is the controller
/// context available in the variable *applicationContext*. The second one is an
/// options array with the following attributes:
///
/// * *urlPrefix*: All routes you define within will be prefixed with it.
///
/// @EXAMPLES
///
/// ```js
/// app = new Controller(applicationContext, {
/// urlPrefix: "/meadow"
/// });
/// ```
///
/// @endDocuBlock
////////////////////////////////////////////////////////////////////////////////
`new Controller(applicationContext, options)`
This creates a new Controller. The first argument is the controller
context available in the variable *applicationContext*. The second one is an
options array with the following attributes:
* *urlPrefix*: All routes you define within will be prefixed with it.
@EXAMPLES
```js
app = new Controller(applicationContext, {
urlPrefix: "/meadow"
});
```

65
Documentation/DocuBlocks/JSF_foxx_controller_login.md
View File

@ -1,33 +1,32 @@
////////////////////////////////////////////////////////////////////////////////
/// @startDocuBlock JSF_foxx_controller_login
///
/// `FoxxController#login(path, opts)`
///
/// Add a route for the login. You can provide further customizations via the
/// the options:
///
/// * *usernameField* and *passwordField* can be used to adjust the expected attributes
/// in the *post* request. They default to *username* and *password*.
/// * *onSuccess* is a function that you can define to do something if the login was
/// successful. This includes sending a response to the user. This defaults to a
/// function that returns a JSON with *user* set to the identifier of the user and
/// * *key* set to the session key.
/// * *onError* is a function that you can define to do something if the login did not
/// work. This includes sending a response to the user. This defaults to a function
/// that sets the response to 401 and returns a JSON with *error* set to
/// "Username or Password was wrong".
///
/// Both *onSuccess* and *onError* should take request and result as arguments.
///
/// @EXAMPLES
///
/// ```js
/// app.login('/login', {
/// onSuccess(req, res) {
/// res.json({"success": true});
/// }
/// });
/// ```
///
/// @endDocuBlock
////////////////////////////////////////////////////////////////////////////////
`FoxxController#login(path, opts)`
Add a route for the login. You can provide further customizations via the
the options:
* *usernameField* and *passwordField* can be used to adjust the expected attributes
in the *post* request. They default to *username* and *password*.
* *onSuccess* is a function that you can define to do something if the login was
successful. This includes sending a response to the user. This defaults to a
function that returns a JSON with *user* set to the identifier of the user and
* *key* set to the session key.
* *onError* is a function that you can define to do something if the login did not
work. This includes sending a response to the user. This defaults to a function
that sets the response to 401 and returns a JSON with *error* set to
"Username or Password was wrong".
Both *onSuccess* and *onError* should take request and result as arguments.
@EXAMPLES
```js
app.login('/login', {
onSuccess(req, res) {
res.json({"success": true});
}
});
```

63
Documentation/DocuBlocks/JSF_foxx_controller_logout.md
View File

@ -1,32 +1,31 @@
////////////////////////////////////////////////////////////////////////////////
/// @startDocuBlock JSF_foxx_controller_logout
///
/// `FoxxController#logout(path, opts)`
///
/// This works pretty similar to the logout function and adds a path to your
/// app for the logout functionality. You can customize it with a custom *onSuccess*
/// and *onError* function:
///
/// * *onSuccess* is a function that you can define to do something if the logout was
/// successful. This includes sending a response to the user. This defaults to a
/// function that returns a JSON with *message* set to "logged out".
/// * *onError* is a function that you can define to do something if the logout did not
/// work. This includes sending a response to the user. This defaults to a function
/// that sets the response to 401 and returns a JSON with *error* set to
/// "No session was found".
///
/// Both *onSuccess* and *onError* should take request and result as arguments.
///
///
/// @EXAMPLES
///
/// ```js
/// app.logout('/logout', {
/// onSuccess(req, res) {
/// res.json({"message": "Bye, Bye"});
/// }
/// });
/// ```
///
/// @endDocuBlock
////////////////////////////////////////////////////////////////////////////////
`FoxxController#logout(path, opts)`
This works pretty similar to the logout function and adds a path to your
app for the logout functionality. You can customize it with a custom *onSuccess*
and *onError* function:
* *onSuccess* is a function that you can define to do something if the logout was
successful. This includes sending a response to the user. This defaults to a
function that returns a JSON with *message* set to "logged out".
* *onError* is a function that you can define to do something if the logout did not
work. This includes sending a response to the user. This defaults to a function
that sets the response to 401 and returns a JSON with *error* set to
"No session was found".
Both *onSuccess* and *onError* should take request and result as arguments.
@EXAMPLES
```js
app.logout('/logout', {
onSuccess(req, res) {
res.json({"message": "Bye, Bye"});
}
});
```

47
Documentation/DocuBlocks/JSF_foxx_controller_patch.md
View File

@ -1,24 +1,23 @@
////////////////////////////////////////////////////////////////////////////////
/// @startDocuBlock JSF_foxx_controller_patch
///
/// `Controller.patch(path, callback)`
///
/// Defines a new route on `path` that handles requests from the HTTP verb `patch`.
/// This route can also be 'parameterized' like `/goose/:barn`.
/// In this case you can later get the value the user provided for `barn`
/// via the `params` function in the `request`.
/// The function defined in `callback` will be invoked whenever this type of
/// request is recieved.
/// `callback` get's two arguments `request` and `response`, see below for further
/// information about these objects.
///
/// @EXAMPLES
///
/// ```js
/// app.patch('/goose/barn', function (req, res) {
/// // Take this request and deal with it!
/// });
/// ```
///
/// @endDocuBlock
////////////////////////////////////////////////////////////////////////////////
`Controller.patch(path, callback)`
Defines a new route on `path` that handles requests from the HTTP verb `patch`.
This route can also be 'parameterized' like `/goose/:barn`.
In this case you can later get the value the user provided for `barn`
via the `params` function in the `request`.
The function defined in `callback` will be invoked whenever this type of
request is recieved.
`callback` get's two arguments `request` and `response`, see below for further
information about these objects.
@EXAMPLES
```js
app.patch('/goose/barn', function (req, res) {
// Take this request and deal with it!
});
```

47
Documentation/DocuBlocks/JSF_foxx_controller_post.md
View File

@ -1,24 +1,23 @@
////////////////////////////////////////////////////////////////////////////////
/// @startDocuBlock JSF_foxx_controller_post
///
/// `Controller.post(path, callback)`
///
/// Defines a new route on `path` that handles requests from the HTTP verb `post`.
/// This route can also be 'parameterized' like `/goose/:barn`.
/// In this case you can later get the value the user provided for `barn`
/// via the `params` function in the `request`.
/// The function defined in `callback` will be invoked whenever this type of
/// request is recieved.
/// `callback` get's two arguments `request` and `response`, see below for further
/// information about these objects.
///
/// @EXAMPLES
///
/// ```js
/// app.post('/goose/barn', function (req, res) {
/// // Take this request and deal with it!
/// });
/// ```
///
/// @endDocuBlock
////////////////////////////////////////////////////////////////////////////////
`Controller.post(path, callback)`
Defines a new route on `path` that handles requests from the HTTP verb `post`.
This route can also be 'parameterized' like `/goose/:barn`.
In this case you can later get the value the user provided for `barn`
via the `params` function in the `request`.
The function defined in `callback` will be invoked whenever this type of
request is recieved.
`callback` get's two arguments `request` and `response`, see below for further
information about these objects.
@EXAMPLES
```js
app.post('/goose/barn', function (req, res) {
// Take this request and deal with it!
});
```

47
Documentation/DocuBlocks/JSF_foxx_controller_put.md
View File

@ -1,24 +1,23 @@
////////////////////////////////////////////////////////////////////////////////
/// @startDocuBlock JSF_foxx_controller_put
///
/// `Controller.put(path, callback)`
///
/// Defines a new route on `path` that handles requests from the HTTP verb `put`.
/// This route can also be 'parameterized' like `/goose/:barn`.
/// In this case you can later get the value the user provided for `barn`
/// via the `params` function in the `request`.
/// The function defined in `callback` will be invoked whenever this type of
/// request is recieved.
/// `callback` get's two arguments `request` and `response`, see below for further
/// information about these objects.
///
/// @EXAMPLES
///
/// ```js
/// app.put('/goose/barn', function (req, res) {
/// // Take this request and deal with it!
/// });
/// ```
///
/// @endDocuBlock
////////////////////////////////////////////////////////////////////////////////
`Controller.put(path, callback)`
Defines a new route on `path` that handles requests from the HTTP verb `put`.
This route can also be 'parameterized' like `/goose/:barn`.
In this case you can later get the value the user provided for `barn`
via the `params` function in the `request`.
The function defined in `callback` will be invoked whenever this type of
request is recieved.
`callback` get's two arguments `request` and `response`, see below for further
information about these objects.
@EXAMPLES
```js
app.put('/goose/barn', function (req, res) {
// Take this request and deal with it!
});
```

85
Documentation/DocuBlocks/JSF_foxx_controller_register.md
View File

@ -1,43 +1,42 @@
////////////////////////////////////////////////////////////////////////////////
/// @startDocuBlock JSF_foxx_controller_register
///
/// `FoxxController#register(path, opts)`
///
/// This works pretty similar to the logout function and adds a path to your
/// app for the register functionality. You can customize it with a custom *onSuccess*
/// and *onError* function:
///
/// * *onSuccess* is a function that you can define to do something if the registration was
/// successful. This includes sending a response to the user. This defaults to a
/// function that returns a JSON with *user* set to the created user document.
/// * *onError* is a function that you can define to do something if the registration did not
/// work. This includes sending a response to the user. This defaults to a function
/// that sets the response to 401 and returns a JSON with *error* set to
/// "Registration failed".
///
/// Both *onSuccess* and *onError* should take request and result as arguments.
///
/// You can also set the fields containing the username and password via *usernameField*
/// (defaults to *username*) and *passwordField* (defaults to *password*).
/// If you want to accept additional attributes for the user document, use the option
/// *acceptedAttributes* and set it to an array containing strings with the names of
/// the additional attributes you want to accept. All other attributes in the request
/// will be ignored.
///
/// If you want default attributes for the accepted attributes or set additional fields
/// (for example *admin*) use the option *defaultAttributes* which should be a hash
/// mapping attribute names to default values.
///
/// @EXAMPLES
///
/// ```js
/// app.register('/logout', {
/// acceptedAttributes: ['name'],
/// defaultAttributes: {
/// admin: false
/// }
/// });
/// ```
///
/// @endDocuBlock
////////////////////////////////////////////////////////////////////////////////
`FoxxController#register(path, opts)`
This works pretty similar to the logout function and adds a path to your
app for the register functionality. You can customize it with a custom *onSuccess*
and *onError* function:
* *onSuccess* is a function that you can define to do something if the registration was
successful. This includes sending a response to the user. This defaults to a
function that returns a JSON with *user* set to the created user document.
* *onError* is a function that you can define to do something if the registration did not
work. This includes sending a response to the user. This defaults to a function
that sets the response to 401 and returns a JSON with *error* set to
"Registration failed".
Both *onSuccess* and *onError* should take request and result as arguments.
You can also set the fields containing the username and password via *usernameField*
(defaults to *username*) and *passwordField* (defaults to *password*).
If you want to accept additional attributes for the user document, use the option
*acceptedAttributes* and set it to an array containing strings with the names of
the additional attributes you want to accept. All other attributes in the request
will be ignored.
If you want default attributes for the accepted attributes or set additional fields
(for example *admin*) use the option *defaultAttributes* which should be a hash
mapping attribute names to default values.
@EXAMPLES
```js
app.register('/logout', {
acceptedAttributes: ['name'],
defaultAttributes: {
admin: false
}
});
```

15
Documentation/DocuBlocks/JSF_foxx_model_attributes.md
View File

@ -1,8 +1,7 @@
////////////////////////////////////////////////////////////////////////////////
/// @startDocuBlock JSF_foxx_model_attributes
///
/// `model.attributes`
///
/// The *attributes* property is the internal hash containing the model's state.
/// @endDocuBlock
////////////////////////////////////////////////////////////////////////////////
`model.attributes`
The *attributes* property is the internal hash containing the model's state.

17
Documentation/DocuBlocks/JSF_foxx_model_errors.md
View File

@ -1,9 +1,8 @@
////////////////////////////////////////////////////////////////////////////////
/// @startDocuBlock JSF_foxx_model_errors
///
/// `model.errors`
///
/// The *errors* property maps the names of any invalid attributes to their
/// corresponding validation error.
/// @endDocuBlock
////////////////////////////////////////////////////////////////////////////////
`model.errors`
The *errors* property maps the names of any invalid attributes to their
corresponding validation error.

19
Documentation/DocuBlocks/JSF_foxx_model_extend.md
View File

@ -1,10 +1,9 @@
////////////////////////////////////////////////////////////////////////////////
/// @startDocuBlock JSF_foxx_model_extend
///
/// `FoxxModel#extend(instanceProperties, classProperties)`
///
/// Extend the Model prototype to add or overwrite methods.
/// The first object contains the properties to be defined on the instance,
/// the second object those to be defined on the prototype.
/// @endDocuBlock
////////////////////////////////////////////////////////////////////////////////
`FoxxModel#extend(instanceProperties, classProperties)`
Extend the Model prototype to add or overwrite methods.
The first object contains the properties to be defined on the instance,
the second object those to be defined on the prototype.

15
Documentation/DocuBlocks/JSF_foxx_model_forClient.md
View File

@ -1,8 +1,7 @@
////////////////////////////////////////////////////////////////////////////////
/// @startDocuBlock JSF_foxx_model_forClient
///
/// `FoxxModel#forClient()`
///
/// Return a copy of the model which you can send to the client.
/// @endDocuBlock
////////////////////////////////////////////////////////////////////////////////
`FoxxModel#forClient()`
Return a copy of the model which you can send to the client.

15
Documentation/DocuBlocks/JSF_foxx_model_forDB.md
View File

@ -1,8 +1,7 @@
////////////////////////////////////////////////////////////////////////////////
/// @startDocuBlock JSF_foxx_model_forDB
///
/// `FoxxModel#forDB()`
///
/// Return a copy of the model which can be saved into ArangoDB
/// @endDocuBlock
////////////////////////////////////////////////////////////////////////////////
`FoxxModel#forDB()`
Return a copy of the model which can be saved into ArangoDB

35
Documentation/DocuBlocks/JSF_foxx_model_get.md
View File

@ -1,18 +1,17 @@
////////////////////////////////////////////////////////////////////////////////
/// @startDocuBlock JSF_foxx_model_get
///
/// `FoxxModel#get(name)`
///
/// Get the value of an attribute
///
/// @EXAMPLES
///
/// ```js
/// instance = new Model({
/// a: 1
/// });
///
/// instance.get("a");
/// ```
/// @endDocuBlock
////////////////////////////////////////////////////////////////////////////////
`FoxxModel#get(name)`
Get the value of an attribute
@EXAMPLES
```js
instance = new Model({
a: 1
});
instance.get("a");
```

37
Documentation/DocuBlocks/JSF_foxx_model_has.md
View File

@ -1,19 +1,18 @@
////////////////////////////////////////////////////////////////////////////////
/// @startDocuBlock JSF_foxx_model_has
///
/// `FoxxModel#has(name)`
///
/// Returns true if the attribute is set to a non-null or non-undefined value.
///
/// @EXAMPLES
///
/// ```js
/// instance = new Model({
/// a: 1
/// });
///
/// instance.has("a"); //=> true
/// instance.has("b"); //=> false
/// ```
/// @endDocuBlock
////////////////////////////////////////////////////////////////////////////////
`FoxxModel#has(name)`
Returns true if the attribute is set to a non-null or non-undefined value.
@EXAMPLES
```js
instance = new Model({
a: 1
});
instance.has("a"); //=> true
instance.has("b"); //=> false
```

31
Documentation/DocuBlocks/JSF_foxx_model_initializer.md
View File

@ -1,16 +1,15 @@
////////////////////////////////////////////////////////////////////////////////
/// @startDocuBlock JSF_foxx_model_initializer
///
/// `new FoxxModel(data)`
///
/// If you initialize a model, you can give it initial *data* as an object.
///
/// @EXAMPLES
///
/// ```js
/// instance = new Model({
/// a: 1
/// });
/// ```
/// @endDocuBlock
////////////////////////////////////////////////////////////////////////////////
`new FoxxModel(data)`
If you initialize a model, you can give it initial *data* as an object.
@EXAMPLES
```js
instance = new Model({
a: 1
});
```

17
Documentation/DocuBlocks/JSF_foxx_model_isvalid.md
View File

@ -1,9 +1,8 @@
////////////////////////////////////////////////////////////////////////////////
/// @startDocuBlock JSF_foxx_model_isvalid
///
/// `model.isValid`
///
/// The *isValid* flag indicates whether the model's state is currently valid.
/// If the model does not have a schema, it will always be considered valid.
/// @endDocuBlock
////////////////////////////////////////////////////////////////////////////////
`model.isValid`
The *isValid* flag indicates whether the model's state is currently valid.
If the model does not have a schema, it will always be considered valid.

41
Documentation/DocuBlocks/JSF_foxx_model_set.md
View File

@ -1,21 +1,20 @@
////////////////////////////////////////////////////////////////////////////////
/// @startDocuBlock JSF_foxx_model_set
///
/// `FoxxModel#set(name, value)`
///
/// Set the value of an attribute or multiple attributes at once
///
/// @EXAMPLES
///
/// ```js
/// instance = new Model({
/// a: 1
/// });
///
/// instance.set("a", 2);
/// instance.set({
/// b: 2
/// });
/// ```
/// @endDocuBlock
////////////////////////////////////////////////////////////////////////////////
`FoxxModel#set(name, value)`
Set the value of an attribute or multiple attributes at once
@EXAMPLES
```js
instance = new Model({
a: 1
});
instance.set("a", 2);
instance.set({
b: 2
});
```

47
Documentation/DocuBlocks/JSF_foxx_repository_all.md
View File

@ -1,24 +1,23 @@
////////////////////////////////////////////////////////////////////////////////
/// @startDocuBlock JSF_foxx_repository_all
/// `FoxxRepository#all()`
///
/// Returns an array of models that matches the given example. You can provide
/// both a skip and a limit value.
///
/// **Warning:** ArangoDB doesn't guarantee a specific order in this case, to make
/// this really useful we have to explicitly provide something to order by.
///
/// *Parameter*
///
/// * *options* (optional):
/// * *skip* (optional): skips the first given number of models.
/// * *limit* (optional): only returns at most the given number of models.
///
/// @EXAMPLES
///
/// ```javascript
/// var myModel = repository.all({ skip: 4, limit: 2 });
/// myModel[0].get('name');
/// ```
/// @endDocuBlock
////////////////////////////////////////////////////////////////////////////////
`FoxxRepository#all()`
Returns an array of models that matches the given example. You can provide
both a skip and a limit value.
**Warning:** ArangoDB doesn't guarantee a specific order in this case, to make
this really useful we have to explicitly provide something to order by.
*Parameter*
* *options* (optional):
* *skip* (optional): skips the first given number of models.
* *limit* (optional): only returns at most the given number of models.
@EXAMPLES
```javascript
var myModel = repository.all({ skip: 4, limit: 2 });
myModel[0].get('name');
```

25
Documentation/DocuBlocks/JSF_foxx_repository_any.md
View File

@ -1,13 +1,12 @@
////////////////////////////////////////////////////////////////////////////////
/// @startDocuBlock JSF_foxx_repository_any
/// `FoxxRepository#any()`
///
/// Returns a random model from this repository (or null if there is none).
///
/// @EXAMPLES
///
/// ```javascript
/// repository.any();
/// ```
/// @endDocuBlock
////////////////////////////////////////////////////////////////////////////////
`FoxxRepository#any()`
Returns a random model from this repository (or null if there is none).
@EXAMPLES
```javascript
repository.any();
```

27
Documentation/DocuBlocks/JSF_foxx_repository_byExample.md
View File

@ -1,14 +1,13 @@
////////////////////////////////////////////////////////////////////////////////
/// @startDocuBlock JSF_foxx_repository_byExample
/// `FoxxRepository#byExample(example)`
///
/// Returns an array of models for the given ID.
///
/// @EXAMPLES
///
/// ```javascript
/// var myModel = repository.byExample({ amazing: true });
/// myModel[0].get('name');
/// ```
/// @endDocuBlock
////////////////////////////////////////////////////////////////////////////////
`FoxxRepository#byExample(example)`
Returns an array of models for the given ID.
@EXAMPLES
```javascript
var myModel = repository.byExample({ amazing: true });
myModel[0].get('name');
```

33
Documentation/DocuBlocks/JSF_foxx_repository_byId.md
View File

@ -1,17 +1,16 @@
////////////////////////////////////////////////////////////////////////////////
/// @startDocuBlock JSF_foxx_repository_byId
/// `FoxxRepository#byId(id)`
///
/// Returns the model for the given ID ("collection/key") or "key".
///
/// @EXAMPLES
///
/// ```javascript
/// var byIdModel = repository.byId('test/12411');
/// byIdModel.get('name');
///
/// var byKeyModel = repository.byId('12412');
/// byKeyModel.get('name');
/// ```
/// @endDocuBlock
////////////////////////////////////////////////////////////////////////////////
`FoxxRepository#byId(id)`
Returns the model for the given ID ("collection/key") or "key".
@EXAMPLES
```javascript
var byIdModel = repository.byId('test/12411');
byIdModel.get('name');
var byKeyModel = repository.byId('12412');
byKeyModel.get('name');
```

9
Documentation/DocuBlocks/JSF_foxx_repository_collection.md
View File

@ -1,5 +1,4 @@
////////////////////////////////////////////////////////////////////////////////
/// @startDocuBlock JSF_foxx_repository_collection
/// The wrapped ArangoDB collection object.
/// @endDocuBlock
////////////////////////////////////////////////////////////////////////////////
The wrapped ArangoDB collection object.

25
Documentation/DocuBlocks/JSF_foxx_repository_count.md
View File

@ -1,13 +1,12 @@
////////////////////////////////////////////////////////////////////////////////
/// @startDocuBlock JSF_foxx_repository_count
/// `FoxxRepository#count()`
///
/// Returns the number of entries in this collection.
///
/// @EXAMPLES
///
/// ```javascript
/// repository.count();
/// ```
/// @endDocuBlock
////////////////////////////////////////////////////////////////////////////////
`FoxxRepository#count()`
Returns the number of entries in this collection.
@EXAMPLES
```javascript
repository.count();
```

25
Documentation/DocuBlocks/JSF_foxx_repository_exists.md
View File

@ -1,13 +1,12 @@
////////////////////////////////////////////////////////////////////////////////
/// @startDocuBlock JSF_foxx_repository_exists
/// `FoxxRepository#exists(id)`
///
/// Checks whether a model with the given ID or key exists.
///
/// @EXAMPLES
///
/// ```javascript
/// repository.exists(model.get('_id'));
/// ```
/// @endDocuBlock
////////////////////////////////////////////////////////////////////////////////
`FoxxRepository#exists(id)`
Checks whether a model with the given ID or key exists.
@EXAMPLES
```javascript
repository.exists(model.get('_id'));
```

27
Documentation/DocuBlocks/JSF_foxx_repository_firstExample.md
View File

@ -1,14 +1,13 @@
////////////////////////////////////////////////////////////////////////////////
/// @startDocuBlock JSF_foxx_repository_firstExample
/// `FoxxRepository#firstExample(example)`
///
/// Returns the first model that matches the given example.
///
/// @EXAMPLES
///
/// ```javascript
/// var myModel = repository.firstExample({ amazing: true });
/// myModel.get('name');
/// ```
/// @endDocuBlock
////////////////////////////////////////////////////////////////////////////////
`FoxxRepository#firstExample(example)`
Returns the first model that matches the given example.
@EXAMPLES
```javascript
var myModel = repository.firstExample({ amazing: true });
myModel.get('name');
```

51
Documentation/DocuBlocks/JSF_foxx_repository_fulltext.md
View File

@ -1,26 +1,25 @@
////////////////////////////////////////////////////////////////////////////////
/// @startDocuBlock JSF_foxx_repository_fulltext
/// `FoxxRepository#fulltext(attribute, query, options)`
///
/// Returns all models whose attribute *attribute* matches the search query
/// *query*.
///
/// In order to use the fulltext method, a fulltext index must be defined on
/// the repository. If multiple fulltext indexes are defined on the repository
/// for the attribute, the most capable one will be selected.
/// If no fulltext index is present, the method will not be available.
///
/// *Parameter*
///
/// * *attribute*: model attribute to perform a search on.
/// * *query*: query to match the attribute against.
/// * *options* (optional):
/// * *limit* (optional): number of models to return. Defaults to all.
///
/// @EXAMPLES
///
/// ```javascript
/// repository.fulltext("text", "word", {limit: 1});
/// ```
/// @endDocuBlock
////////////////////////////////////////////////////////////////////////////////
`FoxxRepository#fulltext(attribute, query, options)`
Returns all models whose attribute *attribute* matches the search query
*query*.
In order to use the fulltext method, a fulltext index must be defined on
the repository. If multiple fulltext indexes are defined on the repository
for the attribute, the most capable one will be selected.
If no fulltext index is present, the method will not be available.
*Parameter*
* *attribute*: model attribute to perform a search on.
* *query*: query to match the attribute against.
* *options* (optional):
* *limit* (optional): number of models to return. Defaults to all.
@EXAMPLES
```javascript
repository.fulltext("text", "word", {limit: 1});
```

91
Documentation/DocuBlocks/JSF_foxx_repository_initializer.md
View File

@ -1,46 +1,45 @@
////////////////////////////////////////////////////////////////////////////////
/// @startDocuBlock JSF_foxx_repository_initializer
/// `new FoxxRepository(collection, opts)`
///
/// Create a new instance of Repository.
///
/// A Foxx Repository is always initialized with a collection object. You can get
/// your collection object by asking your Foxx.Controller for it: the
/// *collection* method takes the name of the collection (and will prepend
/// the prefix of your application). It also takes two optional arguments:
///
/// 1. Model: The prototype of a model. If you do not provide it, it will default
/// to Foxx.Model
/// 2. Prefix: You can provide the prefix of the application if you need it in
/// your Repository (for some AQL queries probably)
///
/// If the Model has any static methods named after the lifecycle events, they
/// will automatically be registered as listeners to the events emitted by this
/// repository.
///
/// **Examples**
///
/// ```js
/// instance = new Repository(appContext.collection("my_collection"));
/// // or:
/// instance = new Repository(appContext.collection("my_collection"), {
/// model: MyModelPrototype
/// });
/// ```
///
/// Example with listeners:
///
/// ```js
/// var ValidatedModel = Model.extend({
/// schema: {...}
/// }, {
/// beforeSave(modelInstance) {
/// if (!modelInstance.valid) {
/// throw new Error('Refusing to save: model is not valid!');
/// }
/// }
/// });
/// instance = new Repository(collection, {model: ValidatedModel});
/// ```
/// @endDocuBlock
////////////////////////////////////////////////////////////////////////////////
`new FoxxRepository(collection, opts)`
Create a new instance of Repository.
A Foxx Repository is always initialized with a collection object. You can get
your collection object by asking your Foxx.Controller for it: the
*collection* method takes the name of the collection (and will prepend
the prefix of your application). It also takes two optional arguments:
1. Model: The prototype of a model. If you do not provide it, it will default
to Foxx.Model
2. Prefix: You can provide the prefix of the application if you need it in
your Repository (for some AQL queries probably)
If the Model has any static methods named after the lifecycle events, they
will automatically be registered as listeners to the events emitted by this
repository.
**Examples**
```js
instance = new Repository(appContext.collection("my_collection"));
or:
instance = new Repository(appContext.collection("my_collection"), {
model: MyModelPrototype
});
```
Example with listeners:
```js
var ValidatedModel = Model.extend({
schema: {...}
}, {
beforeSave(modelInstance) {
if (!modelInstance.valid) {
throw new Error('Refusing to save: model is not valid!');
}
}
});
instance = new Repository(collection, {model: ValidatedModel});
```

9
Documentation/DocuBlocks/JSF_foxx_repository_model.md
View File

@ -1,5 +1,4 @@
////////////////////////////////////////////////////////////////////////////////
/// @startDocuBlock JSF_foxx_repository_model
/// The model of this repository. Formerly called "modelPrototype".
/// @endDocuBlock
////////////////////////////////////////////////////////////////////////////////
The model of this repository. Formerly called "modelPrototype".

9
Documentation/DocuBlocks/JSF_foxx_repository_modelSchema.md
View File

@ -1,5 +1,4 @@
////////////////////////////////////////////////////////////////////////////////
/// @startDocuBlock JSF_foxx_repository_modelSchema
/// The schema of this repository's model.
/// @endDocuBlock
////////////////////////////////////////////////////////////////////////////////
The schema of this repository's model.

57
Documentation/DocuBlocks/JSF_foxx_repository_near.md
View File

@ -1,29 +1,28 @@
////////////////////////////////////////////////////////////////////////////////
/// @startDocuBlock JSF_foxx_repository_near
/// `FoxxRepository#near(latitude, longitude, options)`
///
/// Finds models near the coordinate *(latitude, longitude)*. The returned
/// list is sorted by distance with the nearest model coming first.
///
/// For geo queries it is required that a geo index is present in the
/// repository. If no geo index is present, the methods will not be available.
///
/// *Parameter*
///
/// * *latitude*: latitude of the coordinate.
/// * *longitude*: longitude of the coordinate.
/// * *options* (optional):
/// * *geo* (optional): name of the specific geo index to use.
/// * *distance* (optional): If set to a truthy value, the returned models
/// will have an additional property containing the distance between the
/// given coordinate and the model. If the value is a string, that value
/// will be used as the property name, otherwise the name defaults to *"distance"*.
/// * *limit* (optional): number of models to return. Defaults to *100*.
///
/// @EXAMPLES
///
/// ```javascript
/// repository.near(0, 0, {geo: "home", distance: true, limit: 10});
/// ```
/// @endDocuBlock
////////////////////////////////////////////////////////////////////////////////
`FoxxRepository#near(latitude, longitude, options)`
Finds models near the coordinate *(latitude, longitude)*. The returned
list is sorted by distance with the nearest model coming first.
For geo queries it is required that a geo index is present in the
repository. If no geo index is present, the methods will not be available.
*Parameter*
* *latitude*: latitude of the coordinate.
* *longitude*: longitude of the coordinate.
* *options* (optional):
* *geo* (optional): name of the specific geo index to use.
* *distance* (optional): If set to a truthy value, the returned models
will have an additional property containing the distance between the
given coordinate and the model. If the value is a string, that value
will be used as the property name, otherwise the name defaults to *"distance"*.
* *limit* (optional): number of models to return. Defaults to *100*.
@EXAMPLES
```javascript
repository.near(0, 0, {geo: "home", distance: true, limit: 10});
```

11
Documentation/DocuBlocks/JSF_foxx_repository_prefix.md
View File

@ -1,6 +1,5 @@
////////////////////////////////////////////////////////////////////////////////
/// @startDocuBlock JSF_foxx_repository_prefix
/// The prefix of the application. This is useful if you want to construct AQL
/// queries for example.
/// @endDocuBlock
////////////////////////////////////////////////////////////////////////////////
The prefix of the application. This is useful if you want to construct AQL
queries for example.

47
Documentation/DocuBlocks/JSF_foxx_repository_range.md
View File

@ -1,24 +1,23 @@
////////////////////////////////////////////////////////////////////////////////
/// @startDocuBlock JSF_foxx_repository_range
/// `FoxxRepository#range(attribute, left, right)`
///
/// Returns all models in the repository such that the attribute is greater
/// than or equal to *left* and strictly less than *right*.
///
/// For range queries it is required that a skiplist index is present for the
/// queried attribute. If no skiplist index is present on the attribute, the
/// method will not be available.
///
/// *Parameter*
///
/// * *attribute*: attribute to query.
/// * *left*: lower bound of the value range (inclusive).
/// * *right*: upper bound of the value range (exclusive).
///
/// @EXAMPLES
///
/// ```javascript
/// repository.range("age", 10, 13);
/// ```
/// @endDocuBlock
////////////////////////////////////////////////////////////////////////////////
`FoxxRepository#range(attribute, left, right)`
Returns all models in the repository such that the attribute is greater
than or equal to *left* and strictly less than *right*.
For range queries it is required that a skiplist index is present for the
queried attribute. If no skiplist index is present on the attribute, the
method will not be available.
*Parameter*
* *attribute*: attribute to query.
* *left*: lower bound of the value range (inclusive).
* *right*: upper bound of the value range (exclusive).
@EXAMPLES
```javascript
repository.range("age", 10, 13);
```

27
Documentation/DocuBlocks/JSF_foxx_repository_remove.md
View File

@ -1,14 +1,13 @@
////////////////////////////////////////////////////////////////////////////////
/// @startDocuBlock JSF_foxx_repository_remove
/// `FoxxRepository#remove(model)`
///
/// Remove the model from the repository.
/// Expects a model.
///
/// @EXAMPLES
///
/// ```javascript
/// repository.remove(myModel);
/// ```
/// @endDocuBlock
////////////////////////////////////////////////////////////////////////////////
`FoxxRepository#remove(model)`
Remove the model from the repository.
Expects a model.
@EXAMPLES
```javascript
repository.remove(myModel);
```

Some files were not shown because too many files have changed in this diff Show More