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

Changed some code comments

This commit is contained in:
Thomas Schmidts 2014-07-01 16:30:36 +02:00
parent 0d6ecea63f
commit a828ed3d08
9 changed files with 545 additions and 510 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

387
Documentation/Books/Users/HttpAsyncResultsManagement/ManagingAsyncResults.mdpp
View File

@ -1,387 +0,0 @@
!CHAPTER Managing Async Results via HTTP
`PUT /_api/job/job-id`*(Returns the result of an async job)*
!SUBSECTION URL parameters
`job-id (string,required)`
The async job id.
!SUBSECTION Description
Returns the result of an async job identified by job-id. If the async job result is present on the server, the result will be removed from the list of result. That means this method can be called for each job-id once.
The method will return the original job result's headers and body, plus the additional HTTP header x-arango-async-job-id. If this header is present, then the job was found and the response contains the original job's result. If the header is not present, the job was not found and the response contains status information from the job amanger.
!SUBSECTION Return codes
Any HTTP status code might be returned by this method. To tell the original job response from a job manager response apart, check for the HTTP header x-arango-async-id. If it is present, the response contains the original job's result. Otherwise the response is from the job manager.
`HTTP 204`
is returned if the job requested via job-id is still in the queue of pending (or not yet finished) jobs. In this case, no x-arango-async-id HTTP header will be returned.
`HTTP 400`
is returned if no job-id was specified in the request. In this case, no x-arango-async-id HTTP header will be returned.
`HTTP 404`
is returned if the job was not found or already deleted or fetched from the job result list. In this case, no x-arango-async-id HTTP header will be returned.
*Examples*
Not providing a job-id:
```
unix> curl -X PUT --dump - http://localhost:8529/_api/job/
HTTP/1.1 400 Bad Request
content-type: application/json; charset=utf-8
{"error":true,"errorMessage":"bad parameter","code":400,"errorNum":400}
```
Providing a job-id for a non-existing job:
```
unix> curl -X PUT --dump - http://localhost:8529/_api/job/foobar
HTTP/1.1 404 Not Found
content-type: application/json; charset=utf-8
{"error":true,"errorMessage":"not found","code":404,"errorNum":404}
```
Fetching the result of an HTTP GET job:
```
unix> curl --header 'x-arango-async: store' --dump - http://localhost:8529/_api/version
HTTP/1.1 202 Accepted
content-type: text/plain; charset=utf-8
x-arango-async-id: 265413601
unix> curl -X PUT --dump - http://localhost:8529/_api/job/265413601
HTTP/1.1 200 OK
content-type: application/json; charset=utf-8
x-arango-async-id: 265413601
{"server":"arango","version":"2.1.0"}
```
Fetching the result of an HTTP POST job that failed:
```
unix> curl -X POST --header 'x-arango-async: store' --data-binary @- --dump - http://localhost:8529/_api/collection
{"name":" this name is invalid "}
HTTP/1.1 202 Accepted
content-type: text/plain; charset=utf-8
x-arango-async-id: 265479137
unix> curl -X PUT --dump - http://localhost:8529/_api/job/265479137
HTTP/1.1 400 Bad Request
content-type: application/json; charset=utf-8
x-arango-async-id: 265479137
{"error":true,"code":400,"errorNum":1208,"errorMessage":"cannot create collection: illegal name"}
```
`PUT /_api/job/job-id/cancel`*(Cancels an async job)*
!SUBSECTION URL parameters
`job-id (string,required)`
The async job id.
!SUBSECTION Description
Cancels the currently running job identified by job-id. Note that it still might take some time to actually cancel the running async job.
!SUBSECTION Return codes
Any HTTP status code might be returned by this method. To tell the original job response from a job manager response apart, check for the HTTP header x-arango-async-id. If it is present, the response contains the original job's result. Otherwise the response is from the job manager.
`HTTP 200`
cancel has been initiated.
`HTTP 400`
is returned if no job-id was specified in the request. In this case, no x-arango-async-id HTTP header will be returned.
`HTTP 404`
is returned if the job was not found or already deleted or fetched from the job result list. In this case, no x-arango-async-id HTTP header will be returned.
*Examples*
```
unix> curl -X POST --header 'x-arango-async: store' --data-binary @- --dump - http://localhost:8529/_api/cursor
{"query": "FOR i IN 1..10 FOR j IN 1..10 LET x = sleep(1.0) FILTER i == 5 && j == 5 RETURN 42"}
HTTP/1.1 202 Accepted
content-type: text/plain; charset=utf-8
x-arango-async-id: 268952545
unix> curl --dump - http://localhost:8529/_api/job/pending
HTTP/1.1 200 OK
content-type: application/json; charset=utf-8
["268952545"]
unix> curl -X PUT --dump - http://localhost:8529/_api/job/268952545/cancel
HTTP/1.1 200 OK
content-type: application/json; charset=utf-8
{"result":true}
unix> curl --dump - http://localhost:8529/_api/job/pending
HTTP/1.1 200 OK
content-type: application/json; charset=utf-8
["268952545"]
```
`DELETE /_api/job/type`*(Deletes the result of async jobs)*
!SUBSECTION URL parameters
`type (string,required)`
The type of jobs to delete. type can be:
* all: deletes all jobs results. Currently executing or queued async jobs will not be stopped by this call.
* expired: deletes expired results. To determine the expiration status of a result, pass the stamp URL parameter. stamp needs to be a UNIX timestamp, and all async job results created at a lower timestamp will be deleted.
* an actual job-id: in this case, the call will remove the result of the specified async job. If the job is currently executing or queued, it will not be aborted.
!SUBSECTION Query parameters
`stamp (number,optional)`
A UNIX timestamp specifying the expiration threshold when type is expired.
!SUBSECTION Description
Deletes either all job results, expired job results, or the result of a specific job. Clients can use this method to perform an eventual garbage collection of job results.
!SUBSECTION Return codes
`HTTP 200`
is returned if the deletion operation was carried out successfully. This code will also be returned if no results were deleted.
`HTTP 400`
is returned if type is not specified or has an invalid value.
`HTTP 404`
is returned if type is a job-id but no async job with the specified id was found.
*Examples*
Deleting all jobs:
```
unix> curl --header 'x-arango-async: store' --dump - http://localhost:8529/_api/version
HTTP/1.1 202 Accepted
content-type: text/plain; charset=utf-8
x-arango-async-id: 270132193
unix> curl -X DELETE --dump - http://localhost:8529/_api/job/all
HTTP/1.1 200 OK
content-type: application/json; charset=utf-8
{
"result" : true
}
```
Deleting expired jobs:
```
unix> curl --header 'x-arango-async: store' --dump - http://localhost:8529/_api/version
HTTP/1.1 202 Accepted
content-type: text/plain; charset=utf-8
x-arango-async-id: 270197729
unix> curl -X DELETE --dump - http://localhost:8529/_api/job/expired?stamp=1401376184
HTTP/1.1 200 OK
content-type: application/json; charset=utf-8
{
"result" : true
}
```
Deleting the result of a specific job:
```
unix> curl --header 'x-arango-async: store' --dump - http://localhost:8529/_api/version
HTTP/1.1 202 Accepted
content-type: text/plain; charset=utf-8
x-arango-async-id: 270263265
unix> curl -X DELETE --dump - http://localhost:8529/_api/job/270263265
HTTP/1.1 200 OK
content-type: application/json; charset=utf-8
{
"result" : true
}
```
Deleting the result of a non-existing job:
```
unix> curl -X DELETE --dump - http://localhost:8529/_api/job/foobar
HTTP/1.1 404 Not Found
content-type: application/json; charset=utf-8
{
"error" : true,
"errorMessage" : "not found",
"code" : 404,
"errorNum" : 404
}
```
`GET /_api/job/job-id`*(Returns the status of the specified job)*
!SUBSECTION URL parameters
`job-id (string,required)`
The async job id.
!SUBSECTION Description
Returns the processing status of the specified job. The processing status can be determined by peeking into the HTTP response code of the response.
!SUBSECTION Return codes
`HTTP 200`
is returned if the job requested via job-id has been executed successfully and its result is ready to fetch.
`HTTP 204`
is returned if the job requested via job-id is still in the queue of pending (or not yet finished) jobs.
`HTTP 400`
is returned if no job-id was specified in the request.
`HTTP 404`
is returned if the job was not found or already deleted or fetched from the job result list.
*Examples*
Querying the status of a done job:
```
unix> curl --header 'x-arango-async: store' --dump - http://localhost:8529/_api/version
HTTP/1.1 202 Accepted
content-type: text/plain; charset=utf-8
x-arango-async-id: 270328801
unix> curl --dump - http://localhost:8529/_api/job/270328801
HTTP/1.1 200 OK
content-type: text/plain; charset=utf-8
Querying the status of a pending job:
unix> curl --header 'x-arango-async: store' --dump - http://localhost:8529/_admin/sleep?duration=3
HTTP/1.1 202 Accepted
content-type: text/plain; charset=utf-8
x-arango-async-id: 270394337
unix> curl --dump - http://localhost:8529/_api/job/270394337
HTTP/1.1 204 No Content
content-type: text/plain; charset=utf-8
```
`GET /_api/job/type`*(Returns the list of job result ids with a specific status)*
!SUBSECTION URL parameters
`type (string,required)`
The type of jobs to return. The type can be either done or pending. Setting the type to done will make the method return the ids of already completed async jobs for which results can be fetched. Setting the type to pending will return the ids of not yet finished async jobs.
!SUBSECTION Query parameters
`count (number,optional)`
The maximum number of ids to return per call. If not specified, a server-defined maximum value will be used.
!SUBSECTION Description
Returns the list of ids of async jobs with a specific status (either done or pending). The list can be used by the client to get an overview of the job system status and to retrieve completed job results later.
!SUBSECTION Return codes
`HTTP 200`
is returned if the list can be compiled successfully. Note: the list might be empty.
`HTTP 400`
is returned if type is not specified or has an invalid value.
*Examples*
Fetching the list of done jobs:
```
unix> curl --header 'x-arango-async: store' --dump - http://localhost:8529/_api/version
HTTP/1.1 202 Accepted
content-type: text/plain; charset=utf-8
x-arango-async-id: 270459873
unix> curl --dump - http://localhost:8529/_api/job/done
HTTP/1.1 200 OK
content-type: application/json; charset=utf-8
[
"270459873"
]
```
Fetching the list of pending jobs:
```
unix> curl --header 'x-arango-async: store' --dump - http://localhost:8529/_api/version
HTTP/1.1 202 Accepted
content-type: text/plain; charset=utf-8
x-arango-async-id: 270525409
unix> curl --dump - http://localhost:8529/_api/job/pending
HTTP/1.1 200 OK
content-type: application/json; charset=utf-8
[ ]
```

26
Documentation/Books/Users/HttpAsyncResultsManagement/README.mdpp
View File

@ -105,7 +105,6 @@ then only the code running on the coordinator is stopped, there may
remain tasks within the cluster which have already been distributed to
the DBservers and it is currently not possible to cancel them as well.
!SUBSUBSECTION Async Execution and Authentication
If a request requires authentication, the authentication procedure is run before
@ -113,3 +112,28 @@ queueing. The request will only be queued if it valid credentials and the authen
succeeds. If the request does not contain valid credentials, it will not be queued but
rejected instantly in the same way as a "regular", non-queued request.
!CHAPTER Managing Async Results via HTTP
<!-- lib/HttpServer/AsyncJobManager.h -->
@startDocuBlock JSF_put_api_async_return
<!-- lib/HttpServer/AsyncJobManager.h -->
@startDocuBlock JSF_put_api_async_cancel
<!-- lib/HttpServer/AsyncJobManager.h -->
@startDocuBlock JSF_get_api_async_delete
<!-- lib/HttpServer/AsyncJobManager.h -->
@startDocuBlock JSF_get_api_async_return
<!-- lib/HttpServer/AsyncJobManager.h -->
@startDocuBlock JSF_get_api_async_return_list

4
Documentation/Books/Users/ModuleConsole/README.mdpp
View File

@ -10,7 +10,7 @@ The implementation follows the CommonJS specification
Tests that an expression is *true*. If not, logs a message and throws
an exception.
Example usage:
*Examples*
```js
console.assert(value === "abc", "expected: value === abc, actual:", value);
@ -32,7 +32,7 @@ String substitution patterns, which can be used in *format*.
* *%%f* floating point number
* *%%o* object hyperlink
Example usage:
*Examples*
```js
console.debug("%s", "this is a test");

73
Documentation/Books/Users/ModuleFs/README.mdpp
View File

@ -5,84 +5,47 @@
The implementation follows the CommonJS specification
[Filesystem/A/0](http://wiki.commonjs.org/wiki/Filesystem/A/0).
`fs.exists(path)`
Returns true if a file (of any type) or a directory exists at a given path. If the file is a broken symbolic link, returns false.
<!-- lib/V8/v8-utils.cpp -->
`fs.isDirectory(path)`
Returns true if the path points to a directory.
`fs.isFile(path)`
Returns true if the path points to a file.
@startDocuBlock JS_Exists
`fs.list(path)`
<!-- lib/V8/v8-utils.cpp -->
The functions returns the names of all the files in a directory, in lexically sorted order. Throws an exception if the directory cannot be traversed (or path is not a directory).
Note: this means that list("x") of a directory containing "a" and "b" would return ["a", "b"], not ["x/a", "x/b"].
`fs.listTree(path)`
The function returns an array that starts with the given path, and all of the paths relative to the given path, discovered by a depth first traversal of every directory in any visited directory, reporting but not traversing symbolic links to directories. The first path is always "", the path relative to itself.
@startDocuBlock JS_IsDirectory
`fs.move(source, destination)`
<!-- lib/V8/v8-utils.cpp -->
Moves source to destination. Failure to move the file, or specifying a directory for target when source is a file will throw an exception.
@startDocuBlock JS_IsFile
`fs.read(filename)`
<!-- lib/V8/v8-utils.cpp -->
Reads in a file and returns the content as string. Please note that the file content must be encoded in UTF-8.
@startDocuBlock JS_List
`fs.read64(filename)`
<!-- lib/V8/v8-utils.cpp -->
Reads in a file and returns the content as string. The file content is Base64 encoded.
@startDocuBlock JS_ListTree
`fs.remove(filename)`
<!-- lib/V8/v8-utils.cpp -->
Removes the file filename at the given path. Throws an exception if the path corresponds to anything that is not a file or a symbolic link. If "path" refers to a symbolic link, removes the symbolic link.
@startDocuBlock JS_Move
<!--
@anchor JSModuleFsExists
@copydetails JS_Exists
@CLEARPAGE
@anchor JSModuleFsIsDirectory
@copydetails JS_IsDirectory
<!-- lib/V8/v8-utils.cpp -->
@CLEARPAGE
@anchor JSModuleFsIsFile
@copydetails JS_IsFile
@startDocuBlock JS_Read
@CLEARPAGE
@anchor JSModuleFsList
@copydetails JS_List
@CLEARPAGE
@anchor JSModuleFsListTree
@copydetails JS_ListTree
<!-- lib/V8/v8-utils.cpp -->
@CLEARPAGE
@anchor JSModuleFsMove
@copydetails JS_Move
@startDocuBlock JS_Read64
@CLEARPAGE
@anchor JSModuleFsRead
@copydetails JS_Read
@CLEARPAGE
@anchor JSModuleFsRead64
@copydetails JS_Read64
<!-- lib/V8/v8-utils.cpp -->
@CLEARPAGE
@anchor JSModuleFsRemove
@copydetails JS_Remove
@BNAVIGATE_JSModuleFs
-->
@startDocuBlock JS_Remove

8
Documentation/Books/Users/ModuleJavaScript/README.mdpp
View File

@ -120,7 +120,7 @@ arangosh> test1.func1();
*require* follows the specification
[Modules/1.1.1](http://wiki.commonjs.org/wiki/Modules/1.1.1).
!CHAPTER Modules Path versus Modules Collection
!SECTION Modules Path versus Modules Collection
ArangoDB comes with predefined modules defined in the file-system under the path
specified by *startup.startup-directory*. In a standard installation this
@ -158,9 +158,9 @@ follows
content: "...."
}
```
**Note**: The leading */´ is important - even if you call *require* without a
leading */´. If such a document exists, then the value of the *content*
**Note**: The leading */* is important - even if you call *require* without a
leading */*. If such a document exists, then the value of the *content*
attribute must contain the JavaScript code of the module. This string is
executed in a new module context and the value of *exports* object is
returned. This value is also stored in the module cache.

1
Documentation/Books/Users/SUMMARY.md
View File

@ -183,7 +183,6 @@
* [Monitoring](HttpAdministrationAndMonitoring/README.md)
* [User Management](HttpUserManagement/README.md)
* [Async Result](HttpAsyncResultsManagement/README.md)
* [Management](HttpAsyncResultsManagement/ManagingAsyncResults.md)
* [Endpoints](HttpEndpoints/README.md)
* [Sharding](HttpShardingInterface/README.md)
* [Miscellaneous functions](HttpMiscellaneousFunctions/README.md)

2
Documentation/Books/codeBlockReader.py
View File

@ -192,7 +192,7 @@ def fetch_comments(dirpath):
if __name__ == "__main__":
open("allComments.txt", "w").close()
path = ["arangod/cluster","arangod/RestHandler","arangod/V8Server","arangod/RestServer",
"lib/Admin","lib/HttpServer",
"lib/Admin","lib/HttpServer","lib/V8",
"js/actions","js/client","js/apps/databases","js/apps/system/cerberus","js/apps/system/gharial","js/common","js/server"]
for i in path:
dirpath = os.path.abspath(os.path.join(os.path.dirname( __file__ ), os.pardir,"ArangoDB/../../"+i))

418
lib/HttpServer/AsyncJobManager.h
View File

@ -281,6 +281,106 @@ namespace triagens {
///
/// Get the result of an async job, and optionally remove it from the list of
/// done jobs if it is completed.
////////////////////////////////////////////////////////////////////////////////
////////////////////////////////////////////////////////////////////////////////
/// @startDocuBlock JSF_put_api_async_return
/// @brief Returns the result of an async job
///
/// @RESTHEADER{PUT /_api/job/job-id, Return result of an async job}
///
/// @RESTURLPARAMS
///
/// @RESTURLPARAM{job-id,string,required}
/// The async job id.
///
/// @RESTDESCRIPTION
/// Returns the result of an async job identified by job-id. If the async job
/// result is present on the server, the result will be removed from the list of
/// result. That means this method can be called for each job-id once.
/// The method will return the original job result's headers and body, plus the
/// additional HTTP header x-arango-async-job-id. If this header is present, then
/// the job was found and the response contains the original job's result. If
/// the header is not present, the job was not found and the response contains
/// status information from the job manager.
///
/// @RESTRETURNCODES
///
/// @RESTRETURNCODE{204}
/// is returned if the job requested via job-id is still in the queue of pending
/// (or not yet finished) jobs. In this case, no x-arango-async-id HTTP header
/// will be returned.
///
/// @RESTRETURNCODE{400}
/// is returned if no job-id was specified in the request. In this case,
/// no x-arango-async-id HTTP header will be returned.
///
/// @RESTRETURNCODE{404}
/// is returned if the job was not found or already deleted or fetched from
/// the job result list. In this case, no x-arango-async-id HTTP header will
/// be returned.
///
/// @EXAMPLES
/// Not providing a job-id:
///
/// ```js
/// unix> curl -X PUT --dump - http://localhost:8529/_api/job/
///
/// HTTP/1.1 400 Bad Request
/// content-type: application/json; charset=utf-8
///
/// {"error":true,"errorMessage":"bad parameter","code":400,"errorNum":400}
/// ```
///
/// Providing a job-id for a non-existing job:
///
/// ```js
/// unix> curl -X PUT --dump - http://localhost:8529/_api/job/foobar
///
/// HTTP/1.1 404 Not Found
/// content-type: application/json; charset=utf-8
///
/// {"error":true,"errorMessage":"not found","code":404,"errorNum":404}
/// ```
///
/// Fetching the result of an HTTP GET job:
///
/// ```js
/// unix> curl --header 'x-arango-async: store' --dump - http://localhost:8529/_api/version
///
/// HTTP/1.1 202 Accepted
/// content-type: text/plain; charset=utf-8
/// x-arango-async-id: 265413601
///
/// unix> curl -X PUT --dump - http://localhost:8529/_api/job/265413601
///
/// HTTP/1.1 200 OK
/// content-type: application/json; charset=utf-8
/// x-arango-async-id: 265413601
///
/// {"server":"arango","version":"2.1.0"}
/// ```
///
/// Fetching the result of an HTTP POST job that failed:
///
/// ```js
/// unix> curl -X POST --header 'x-arango-async: store' --data-binary @- --dump - http://localhost:8529/_api/collection
/// {"name":" this name is invalid "}
///
/// HTTP/1.1 202 Accepted
/// content-type: text/plain; charset=utf-8
/// x-arango-async-id: 265479137
///
/// unix> curl -X PUT --dump - http://localhost:8529/_api/job/265479137
///
/// HTTP/1.1 400 Bad Request
/// content-type: application/json; charset=utf-8
/// x-arango-async-id: 265479137
///
/// {"error":true,"code":400,"errorNum":1208,"errorMessage":"cannot create collection: illegal name"}
/// ```
///
/// @endDocuBlock
////////////////////////////////////////////////////////////////////////////////
HttpResponse* getJobResult (AsyncJobResult::IdType jobId,
@ -313,6 +413,188 @@ namespace triagens {
////////////////////////////////////////////////////////////////////////////////
/// @brief deletes the result of an async job, without returning it
////////////////////////////////////////////////////////////////////////////////
////////////////////////////////////////////////////////////////////////////////
/// @startDocuBlock JSF_put_api_async_cancel
/// @brief Cancels the result an async job
///
/// @RESTHEADER{PUT /_api/job/job-id/cancel, Cancel async job}
///
/// @RESTURLPARAMS
///
/// @RESTURLPARAM{job-id,string,required}
/// The async job id.
///
/// @RESTDESCRIPTION
/// Cancels the currently running job identified by job-id. Note that it still
/// might take some time to actually cancel the running async job.
///
/// @RESTRETURNCODES
///
/// @RESTRETURNCODE{200}
/// cancel has been initiated.
///
/// @RESTRETURNCODE{400}
/// is returned if no job-id was specified in the request. In this case,
/// no x-arango-async-id HTTP header will be returned.
///
/// @RESTRETURNCODE{404}
/// is returned if the job was not found or already deleted or fetched from
/// the job result list. In this case, no x-arango-async-id HTTP header will
/// be returned.
///
/// @EXAMPLES
///
/// ```js
/// unix> curl -X POST --header 'x-arango-async: store' --data-binary @- --dump - http://localhost:8529/_api/cursor
/// {"query": "FOR i IN 1..10 FOR j IN 1..10 LET x = sleep(1.0) FILTER i == 5 && j == 5 RETURN 42"}
///
/// HTTP/1.1 202 Accepted
/// content-type: text/plain; charset=utf-8
/// x-arango-async-id: 268952545
///
/// unix> curl --dump - http://localhost:8529/_api/job/pending
///
/// HTTP/1.1 200 OK
/// content-type: application/json; charset=utf-8
///
/// ["268952545"]
///
/// unix> curl -X PUT --dump - http://localhost:8529/_api/job/268952545/cancel
///
/// HTTP/1.1 200 OK
/// content-type: application/json; charset=utf-8
///
/// {"result":true}
///
/// unix> curl --dump - http://localhost:8529/_api/job/pending
///
/// HTTP/1.1 200 OK
/// content-type: application/json; charset=utf-8
///
/// ["268952545"]
/// ```
///
/// @endDocuBlock
////////////////////////////////////////////////////////////////////////////////
////////////////////////////////////////////////////////////////////////////////
/// @startDocuBlock JSF_get_api_async_delete
/// @brief Deletes the result of an async job
///
/// @RESTHEADER{DELETE /_api/job/type, Deletes async job}
///
/// @RESTURLPARAMS
///
/// @RESTURLPARAM{type,string,required}
/// The type of jobs to delete. type can be:
/// * *all*: Deletes all jobs results. Currently executing or queued async
/// jobs will not be stopped by this call.
/// * *expired*: Deletes expired results. To determine the expiration status of a
/// result, pass the stamp URL parameter. stamp needs to be a UNIX timestamp,
/// and all async job results created at a lower timestamp will be deleted.
/// * *an actual job-id*: In this case, the call will remove the result of the
/// specified async job. If the job is currently executing or queued, it will not be aborted.
///
/// @RESTQUERYPARAMS
///
/// @RESTPARAM{stamp, number, optional}
///
/// A UNIX timestamp specifying the expiration threshold when type is expired.
///
/// @RESTDESCRIPTION
/// Deletes either all job results, expired job results, or the result of a specific job.
/// Clients can use this method to perform an eventual garbage collection of job results.
///
/// @RESTRETURNCODES
///
/// @RESTRETURNCODE{200}
/// is returned if the deletion operation was carried out successfully.
/// This code will also be returned if no results were deleted.
///
/// @RESTRETURNCODE{400}
/// is returned if type is not specified or has an invalid value.
///
/// @RESTRETURNCODE{404}
/// is returned if type is a job-id but no async job with the specified id was found.
///
/// @EXAMPLES
///
/// Deleting all jobs:
///
/// ```js
/// unix> curl --header 'x-arango-async: store' --dump - http://localhost:8529/_api/version
///
/// HTTP/1.1 202 Accepted
/// content-type: text/plain; charset=utf-8
/// x-arango-async-id: 270132193
///
/// unix> curl -X DELETE --dump - http://localhost:8529/_api/job/all
///
/// HTTP/1.1 200 OK
/// content-type: application/json; charset=utf-8
///
/// {
/// "result" : true
/// }
/// ```
///
/// Deleting expired jobs:
///
/// ```js
/// unix> curl --header 'x-arango-async: store' --dump - http://localhost:8529/_api/version
///
/// HTTP/1.1 202 Accepted
/// content-type: text/plain; charset=utf-8
/// x-arango-async-id: 270197729
///
/// unix> curl -X DELETE --dump - http://localhost:8529/_api/job/expired?stamp=1401376184
///
/// HTTP/1.1 200 OK
/// content-type: application/json; charset=utf-8
///
/// {
/// "result" : true
/// }
/// ```
///
/// Deleting the result of a specific job:
///
/// ```js
/// unix> curl --header 'x-arango-async: store' --dump - http://localhost:8529/_api/version
///
/// HTTP/1.1 202 Accepted
/// content-type: text/plain; charset=utf-8
/// x-arango-async-id: 270263265
///
/// unix> curl -X DELETE --dump - http://localhost:8529/_api/job/270263265
///
/// HTTP/1.1 200 OK
/// content-type: application/json; charset=utf-8
///
/// {
/// "result" : true
/// }
/// ```
///
/// Deleting the result of a non-existing job:
///
/// ```js
/// unix> curl -X DELETE --dump - http://localhost:8529/_api/job/foobar
///
/// HTTP/1.1 404 Not Found
/// content-type: application/json; charset=utf-8
///
/// {
/// "error" : true,
/// "errorMessage" : "not found",
/// "code" : 404,
/// "errorNum" : 404
/// }
/// ```
///
/// @endDocuBlock
////////////////////////////////////////////////////////////////////////////////
bool deleteJobResult (AsyncJobResult::IdType jobId) {
@ -402,6 +684,142 @@ namespace triagens {
////////////////////////////////////////////////////////////////////////////////
/// @brief returns the list of jobs by status
////////////////////////////////////////////////////////////////////////////////
////////////////////////////////////////////////////////////////////////////////
/// @startDocuBlock JSF_get_api_async_return
/// @brief Returns the status of an async job
///
/// @RESTHEADER{GET /_api/job/job-id, Returns async job}
///
/// @RESTURLPARAMS
///
/// @RESTURLPARAM{job-id,string,required}
/// The async job id.
///
/// @RESTDESCRIPTION
/// Returns the processing status of the specified job. The processing status can be
/// determined by peeking into the HTTP response code of the response.
///
/// @RESTRETURNCODES
///
/// @RESTRETURNCODE{200}
/// is returned if the job requested via job-id has been executed successfully
/// and its result is ready to fetch.
///
/// @RESTRETURNCODE{204}
/// is returned if the job requested via job-id is still in the queue of pending
/// (or not yet finished) jobs.
///
/// @RESTRETURNCODE{404}
/// is returned if the job was not found or already deleted or fetched from the job result list.
///
/// @EXAMPLES
///
/// Querying the status of a done job:
///
/// ```js
/// unix> curl --header 'x-arango-async: store' --dump - http://localhost:8529/_api/version
///
/// HTTP/1.1 202 Accepted
/// content-type: text/plain; charset=utf-8
/// x-arango-async-id: 270328801
///
/// unix> curl --dump - http://localhost:8529/_api/job/270328801
///
/// HTTP/1.1 200 OK
/// content-type: text/plain; charset=utf-8
///
/// Querying the status of a pending job:
///
/// unix> curl --header 'x-arango-async: store' --dump - http://localhost:8529/_admin/sleep?duration=3
///
/// HTTP/1.1 202 Accepted
/// content-type: text/plain; charset=utf-8
/// x-arango-async-id: 270394337
///
/// unix> curl --dump - http://localhost:8529/_api/job/270394337
///
/// HTTP/1.1 204 No Content
/// content-type: text/plain; charset=utf-8
/// ```
///
/// @endDocuBlock
////////////////////////////////////////////////////////////////////////////////
///////////////////////////////////////////////////////////////////////////////
/// @startDocuBlock JSF_get_api_async_return_list
/// @brief Returns the list of job result id with a specific status
///
/// @RESTHEADER{GET /_api/job/type, Returns list of async job}
///
/// @RESTURLPARAMS
///
/// @RESTURLPARAM{type,string,required}
/// The type of jobs to return. The type can be either done or pending. Setting
/// the type to done will make the method return the ids of already completed async
/// jobs for which results can be fetched. Setting the type to pending will return
/// the ids of not yet finished async jobs.
///
/// @RESTQUERYPARAMS
///
/// @RESTPARAM{count, number, optional}
///
/// The maximum number of ids to return per call. If not specified, a
/// server-defined maximum value will be used.
///
/// @RESTDESCRIPTION
/// Returns the list of ids of async jobs with a specific status (either done or pending).
/// The list can be used by the client to get an overview of the job system status and
/// to retrieve completed job results later.
///
/// @RESTRETURNCODES
///
/// @RESTRETURNCODE{200}
/// is returned if the list can be compiled successfully. Note: the list might be empty.
///
/// @RESTRETURNCODE{400}
/// is returned if type is not specified or has an invalid value.
///
/// @EXAMPLES
///
/// Fetching the list of done jobs:
///
/// ```js
/// unix> curl --header 'x-arango-async: store' --dump - http://localhost:8529/_api/version
///
/// HTTP/1.1 202 Accepted
/// content-type: text/plain; charset=utf-8
/// x-arango-async-id: 270459873
///
/// unix> curl --dump - http://localhost:8529/_api/job/done
///
/// HTTP/1.1 200 OK
/// content-type: application/json; charset=utf-8
///
/// [
/// "270459873"
/// ]
/// ```
///
/// Fetching the list of pending jobs:
///
/// ```js
/// unix> curl --header 'x-arango-async: store' --dump - http://localhost:8529/_api/version
///
/// HTTP/1.1 202 Accepted
/// content-type: text/plain; charset=utf-8
/// x-arango-async-id: 270525409
///
/// unix> curl --dump - http://localhost:8529/_api/job/pending
///
/// HTTP/1.1 200 OK
/// content-type: application/json; charset=utf-8
///
/// [ ]
/// ```
///
/// @endDocuBlock
////////////////////////////////////////////////////////////////////////////////
const std::vector<AsyncJobResult::IdType> byStatus (AsyncJobResult::Status status,

136
lib/V8/v8-utils.cpp
View File

@ -382,7 +382,7 @@ static v8::Handle<v8::Value> JS_Base64Encode (v8::Arguments const& argv) {
/// @FUN{internal.parse(@FA{script})}
///
/// Parses the @FA{script} code, but does not execute it.
/// Will return @LIT{true} if the code does not have a parse error, and throw
/// Will return *true* if the code does not have a parse error, and throw
/// an exception otherwise.
////////////////////////////////////////////////////////////////////////////////
@ -446,7 +446,7 @@ static v8::Handle<v8::Value> JS_Parse (v8::Arguments const& argv) {
/// - @LIT{followRedirects}: whether or not to follow redirects
///
/// - @LIT{maxRedirects}: maximum number of redirects to follow, only useful
/// if @LIT{followRedirects} is @LIT{true}.
/// if @LIT{followRedirects} is *true*.
///
/// - @LIT{returnBodyOnError}: whether or not to return / save body on HTTP
/// error
@ -747,11 +747,11 @@ static v8::Handle<v8::Value> JS_Download (v8::Arguments const& argv) {
////////////////////////////////////////////////////////////////////////////////
/// @brief executes a script
///
/// @FUN{internal.execute(@FA{script}, @FA{sandbox}, @FA{filename})}
/// @FUN{internal.execute(@FA{script}, @FA{sandbox}, *filename*)}
///
/// Executes the @FA{script} with the @FA{sandbox} as context. Global variables
/// assigned inside the @FA{script}, will be visible in the @FA{sandbox} object
/// after execution. The @FA{filename} is used for displaying error
/// after execution. The *filename* is used for displaying error
/// messages.
///
/// If @FA{sandbox} is undefined, then @FN{execute} uses the current context.
@ -909,11 +909,12 @@ static v8::Handle<v8::Value> JS_RegisterExecuteFile (v8::Arguments const& argv)
////////////////////////////////////////////////////////////////////////////////
/// @brief checks if a file of any type or directory exists
///
/// @FUN{fs.exists(@FA{path})}
/// @startDocuBlock JS_Exists
/// `fs.exists(path)`
///
/// Returns true if a file (of any type) or a directory exists at a given
/// path. If the file is a broken symbolic link, returns false.
/// @endDocuBlock
////////////////////////////////////////////////////////////////////////////////
static v8::Handle<v8::Value> JS_Exists (v8::Arguments const& argv) {
@ -935,10 +936,11 @@ static v8::Handle<v8::Value> JS_Exists (v8::Arguments const& argv) {
////////////////////////////////////////////////////////////////////////////////
/// @brief gets the size of a file
/// @startDocuBlock JS_Size
/// `fs.size(path)`
///
/// @FUN{fs.size(@FA{path})}
///
/// Returns the size of the file specified by @FA{path}.
/// Returns the size of the file specified by *path*.
/// @endDocuBlock
////////////////////////////////////////////////////////////////////////////////
static v8::Handle<v8::Value> JS_SizeFile (v8::Arguments const& argv) {
@ -983,10 +985,11 @@ static v8::Handle<v8::Value> JS_Getline (v8::Arguments const& argv) {
////////////////////////////////////////////////////////////////////////////////
/// @brief returns the temporary directory
///
/// @FUN{fs.getTempPath()}
/// @startDocuBlock JS_GetTempPath
/// `fs.getTempPath()`
///
/// Returns the absolute path of the temporary directory
/// @endDocuBlock
////////////////////////////////////////////////////////////////////////////////
static v8::Handle<v8::Value> JS_GetTempPath (v8::Arguments const& argv) {
@ -1010,14 +1013,15 @@ static v8::Handle<v8::Value> JS_GetTempPath (v8::Arguments const& argv) {
////////////////////////////////////////////////////////////////////////////////
/// @brief returns the name for a (new) temporary file
/// @startDocuBlock JS_GetTempFile
/// `fs.getTempFile(directory, createFile)`
///
/// @FUN{fs.getTempFile(@FA{directory}, @FA{createFile})}
///
/// Returns the name for a new temporary file in directory @FA{directory}.
/// If @FA{createFile} is @LIT{true}, an empty file will be created so no other
/// Returns the name for a new temporary file in directory *directory*.
/// If *createFile* is *true*, an empty file will be created so no other
/// process can create a file of the same name.
///
/// Note that the directory @FA{directory} must exist.
/// **Note**: The directory *directory* must exist.
/// @endDocuBlock
////////////////////////////////////////////////////////////////////////////////
static v8::Handle<v8::Value> JS_GetTempFile (v8::Arguments const& argv) {
@ -1054,10 +1058,11 @@ static v8::Handle<v8::Value> JS_GetTempFile (v8::Arguments const& argv) {
////////////////////////////////////////////////////////////////////////////////
/// @brief tests if path is a directory
/// @startDocuBlock JS_IsDirectory
/// `fs.isDirectory(path)`
///
/// @FUN{fs.isDirectory(@FA{path})}
///
/// Returns true if the @FA{path} points to a directory.
/// Returns true if the *path* points to a directory.
/// @endDocuBlock
////////////////////////////////////////////////////////////////////////////////
static v8::Handle<v8::Value> JS_IsDirectory (v8::Arguments const& argv) {
@ -1080,10 +1085,11 @@ static v8::Handle<v8::Value> JS_IsDirectory (v8::Arguments const& argv) {
////////////////////////////////////////////////////////////////////////////////
/// @brief tests if path is a file
/// @startDocuBlock JS_IsFile
/// `fs.isFile(path)`
///
/// @FUN{fs.isFile(@FA{path})}
///
/// Returns true if the @FA{path} points to a file.
/// Returns true if the *path* points to a file.
/// @endDocuBlock
////////////////////////////////////////////////////////////////////////////////
static v8::Handle<v8::Value> JS_IsFile (v8::Arguments const& argv) {
@ -1106,11 +1112,12 @@ static v8::Handle<v8::Value> JS_IsFile (v8::Arguments const& argv) {
////////////////////////////////////////////////////////////////////////////////
/// @brief makes a given path absolute
///
/// @FUN{fs.makeAbsolute(@FA{path})}
/// @startDocuBlock JS_MakeAbsolute
/// `fs.makeAbsolute(path)`
///
/// Returns the given string if it is an absolute path, otherwise an
/// absolute path to the same location is returned.
/// @endDocuBlock
////////////////////////////////////////////////////////////////////////////////
static v8::Handle<v8::Value> JS_MakeAbsolute(v8::Arguments const& argv) {
@ -1151,15 +1158,16 @@ static v8::Handle<v8::Value> JS_MakeAbsolute(v8::Arguments const& argv) {
////////////////////////////////////////////////////////////////////////////////
/// @brief returns the directory listing
///
/// @FUN{fs.list(@FA{path})}
/// @startDocuBlock JS_List
/// `fs.list(path`
///
/// The functions returns the names of all the files in a directory, in
/// lexically sorted order. Throws an exception if the directory cannot be
/// traversed (or path is not a directory).
///
/// Note: this means that list("x") of a directory containing "a" and "b" would
/// **Note**: this means that list("x") of a directory containing "a" and "b" would
/// return ["a", "b"], not ["x/a", "x/b"].
/// @endDocuBlock
////////////////////////////////////////////////////////////////////////////////
static v8::Handle<v8::Value> JS_List (v8::Arguments const& argv) {
@ -1195,14 +1203,15 @@ static v8::Handle<v8::Value> JS_List (v8::Arguments const& argv) {
////////////////////////////////////////////////////////////////////////////////
/// @brief returns the directory tree
///
/// @FUN{fs.listTree(@FA{path})}
/// @startDocuBlock JS_ListTree
/// `fs.listTree(path)`
///
/// The function returns an array that starts with the given path, and all of
/// the paths relative to the given path, discovered by a depth first traversal
/// of every directory in any visited directory, reporting but not traversing
/// symbolic links to directories. The first path is always @LIT{""}, the path
/// symbolic links to directories. The first path is always *""*, the path
/// relative to itself.
/// @endDocuBlock
////////////////////////////////////////////////////////////////////////////////
static v8::Handle<v8::Value> JS_ListTree (v8::Arguments const& argv) {
@ -1238,10 +1247,11 @@ static v8::Handle<v8::Value> JS_ListTree (v8::Arguments const& argv) {
////////////////////////////////////////////////////////////////////////////////
/// @brief creates a directory
/// @startDocuBlock JS_MakeDirectory
/// `fs.makeDirectory(path)`
///
/// @FUN{fs.makeDirectory(@FA{path})}
///
/// Creates the directory specified by @FA{path}.
/// Creates the directory specified by *path*.
/// @endDocuBlock
////////////////////////////////////////////////////////////////////////////////
static v8::Handle<v8::Value> JS_MakeDirectory (v8::Arguments const& argv) {
@ -1271,14 +1281,15 @@ static v8::Handle<v8::Value> JS_MakeDirectory (v8::Arguments const& argv) {
////////////////////////////////////////////////////////////////////////////////
/// @brief unzips a file
/// @startDocuBlock JS_Unzip
/// `fs.unzip(filename, outpath, skipPaths, overwrite, password)`
///
/// @FUN{fs.unzip(@FA{filename}, @FA{outpath}, @FA{skipPaths}, @FA{overwrite}, @FA{password})}
/// Unzips the zip file specified by *filename* into the path specified by
/// * outpath*. Overwrites any existing target files if *overwrite* is set
/// to *true*.
///
/// Unzips the zip file specified by @FA{filename} into the path specified by
/// @FA{outpath}. Overwrites any existing target files if @FA{overwrite} is set
/// to @LIT{true}.
///
/// Returns @LIT{true} if the file was unzipped successfully.
/// Returns *true* if the file was unzipped successfully.
/// @endDocuBlock
////////////////////////////////////////////////////////////////////////////////
static v8::Handle<v8::Value> JS_UnzipFile (v8::Arguments const& argv) {
@ -1323,12 +1334,13 @@ static v8::Handle<v8::Value> JS_UnzipFile (v8::Arguments const& argv) {
////////////////////////////////////////////////////////////////////////////////
/// @brief zips a file
/// @startDocuBlock JS_Zip
/// `fs.zip(filename, files)`
///
/// @FUN{fs.zip(@FA{filename}, @FA{files})}
/// Stores the files specified by *files* in the zip file *filename*.
///
/// Stores the files specified by @FA{files} in the zip file @FA{filename}.
///
/// Returns @LIT{true} if the file was zipped successfully.
/// Returns *true* if the file was zipped successfully.
/// @endDocuBlock
////////////////////////////////////////////////////////////////////////////////
static v8::Handle<v8::Value> JS_ZipFile (v8::Arguments const& argv) {
@ -1393,7 +1405,7 @@ static v8::Handle<v8::Value> JS_ZipFile (v8::Arguments const& argv) {
////////////////////////////////////////////////////////////////////////////////
/// @brief reads a file and executes it
///
/// @FUN{internal.load(@FA{filename})}
/// @FUN{internal.load(*filename*)}
///
/// Reads in a files and executes the contents in the current context.
////////////////////////////////////////////////////////////////////////////////
@ -1677,12 +1689,13 @@ static v8::Handle<v8::Value> JS_MarkNonce (v8::Arguments const& argv) {
////////////////////////////////////////////////////////////////////////////////
/// @brief renames a file
/// @startDocuBlock JS_Move
/// `fs.move(source, destination)`
///
/// @FUN{fs.move(@FA{source}, @FA{destination})}
///
/// Moves @FA{source} to @FA{destination}. Failure to move the file, or
/// Moves *source to destination. Failure to move the file, or
/// specifying a directory for target when source is a file will throw an
/// exception.
/// @endDocuBlock
////////////////////////////////////////////////////////////////////////////////
static v8::Handle<v8::Value> JS_Move (v8::Arguments const& argv) {
@ -1852,11 +1865,12 @@ static v8::Handle<v8::Value> JS_Rand (v8::Arguments const& argv) {
////////////////////////////////////////////////////////////////////////////////
/// @brief reads in a file
///
/// @FUN{fs.read(@FA{filename})}
/// @startDocuBlock JS_Read
/// `fs.read(filename)`
///
/// Reads in a file and returns the content as string. Please note that the
/// file content must be encoded in UTF-8.
/// @endDocuBlock
////////////////////////////////////////////////////////////////////////////////
static v8::Handle<v8::Value> JS_Read (v8::Arguments const& argv) {
@ -1888,11 +1902,12 @@ static v8::Handle<v8::Value> JS_Read (v8::Arguments const& argv) {
////////////////////////////////////////////////////////////////////////////////
/// @brief reads in a file as base64
///
/// @FUN{fs.read64(@FA{filename})}
/// @startDocuBlock JS_Read64
/// `fs.read64(filename)`
///
/// Reads in a file and returns the content as string. The file content is
/// Base64 encoded.
/// @endDocuBlock
////////////////////////////////////////////////////////////////////////////////
static v8::Handle<v8::Value> JS_Read64 (v8::Arguments const& argv) {
@ -1924,7 +1939,7 @@ static v8::Handle<v8::Value> JS_Read64 (v8::Arguments const& argv) {
////////////////////////////////////////////////////////////////////////////////
/// @brief writes to a file
///
/// @FUN{internal.save(@FA{filename})}
/// @FUN{internal.save(*filename*)}
///
/// Writes the content into a file.
////////////////////////////////////////////////////////////////////////////////
@ -1963,12 +1978,13 @@ static v8::Handle<v8::Value> JS_Save (v8::Arguments const& argv) {
////////////////////////////////////////////////////////////////////////////////
/// @brief removes a file
/// @startDocuBlock JS_Remove
/// `fs.remove(filename)`
///
/// @FUN{fs.remove(@FA{filename})}
///
/// Removes the file @FA{filename} at the given path. Throws an exception if the
/// Removes the file *filename* at the given path. Throws an exception if the
/// path corresponds to anything that is not a file or a symbolic link. If
/// "path" refers to a symbolic link, removes the symbolic link.
/// @endDocuBlock
////////////////////////////////////////////////////////////////////////////////
static v8::Handle<v8::Value> JS_Remove (v8::Arguments const& argv) {
@ -1996,11 +2012,12 @@ static v8::Handle<v8::Value> JS_Remove (v8::Arguments const& argv) {
////////////////////////////////////////////////////////////////////////////////
/// @brief removes an empty directory
///
/// @FUN{fs.removeDirectory(@FA{path})}
/// @startDocuBlock JS_RemoveDirectory
/// `fs.removeDirectory(path)`
///
/// Removes a directory if it is empty. Throws an exception if the path is not
/// an empty directory.
/// @endDocuBlock
////////////////////////////////////////////////////////////////////////////////
static v8::Handle<v8::Value> JS_RemoveDirectory (v8::Arguments const& argv) {
@ -2032,11 +2049,12 @@ static v8::Handle<v8::Value> JS_RemoveDirectory (v8::Arguments const& argv) {
////////////////////////////////////////////////////////////////////////////////
/// @brief removes a directory
///
/// @FUN{fs.removeDirectoryRecursive(@FA{path})}
/// @startDocuBlock JS_RemoveDirectoryRecursive
/// `fs.removeDirectoryRecursive(path)`
///
/// Removes a directory with all subelements. Throws an exception if the path
/// is not a directory.
/// @endDocuBlock
////////////////////////////////////////////////////////////////////////////////
static v8::Handle<v8::Value> JS_RemoveRecursiveDirectory (v8::Arguments const& argv) {