diff --git a/Documentation/Books/Users/HttpAsyncResultsManagement/ManagingAsyncResults.mdpp b/Documentation/Books/Users/HttpAsyncResultsManagement/ManagingAsyncResults.mdpp deleted file mode 100644 index 254cf780bc..0000000000 --- a/Documentation/Books/Users/HttpAsyncResultsManagement/ManagingAsyncResults.mdpp +++ /dev/null @@ -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 - -[ ] -``` diff --git a/Documentation/Books/Users/HttpAsyncResultsManagement/README.mdpp b/Documentation/Books/Users/HttpAsyncResultsManagement/README.mdpp index 414e9a4482..432a41e808 100644 --- a/Documentation/Books/Users/HttpAsyncResultsManagement/README.mdpp +++ b/Documentation/Books/Users/HttpAsyncResultsManagement/README.mdpp @@ -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 + + + +@startDocuBlock JSF_put_api_async_return + + + + +@startDocuBlock JSF_put_api_async_cancel + + + + +@startDocuBlock JSF_get_api_async_delete + + + + +@startDocuBlock JSF_get_api_async_return + + + + +@startDocuBlock JSF_get_api_async_return_list diff --git a/Documentation/Books/Users/ModuleConsole/README.mdpp b/Documentation/Books/Users/ModuleConsole/README.mdpp index 9127ad177a..5da732be15 100644 --- a/Documentation/Books/Users/ModuleConsole/README.mdpp +++ b/Documentation/Books/Users/ModuleConsole/README.mdpp @@ -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"); diff --git a/Documentation/Books/Users/ModuleFs/README.mdpp b/Documentation/Books/Users/ModuleFs/README.mdpp index cb08b5b0f3..e15f748b33 100644 --- a/Documentation/Books/Users/ModuleFs/README.mdpp +++ b/Documentation/Books/Users/ModuleFs/README.mdpp @@ -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. + -`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)` + -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)` + -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)` + -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)` + -Reads in a file and returns the content as string. The file content is Base64 encoded. +@startDocuBlock JS_ListTree -`fs.remove(filename)` + -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 - -@CLEARPAGE -@anchor JSModuleFsIsFile -@copydetails JS_IsFile +@startDocuBlock JS_Read -@CLEARPAGE -@anchor JSModuleFsList -@copydetails JS_List -@CLEARPAGE -@anchor JSModuleFsListTree -@copydetails JS_ListTree + -@CLEARPAGE -@anchor JSModuleFsMove -@copydetails JS_Move +@startDocuBlock JS_Read64 -@CLEARPAGE -@anchor JSModuleFsRead -@copydetails JS_Read -@CLEARPAGE -@anchor JSModuleFsRead64 -@copydetails JS_Read64 + -@CLEARPAGE -@anchor JSModuleFsRemove -@copydetails JS_Remove - -@BNAVIGATE_JSModuleFs ---> \ No newline at end of file +@startDocuBlock JS_Remove diff --git a/Documentation/Books/Users/ModuleJavaScript/README.mdpp b/Documentation/Books/Users/ModuleJavaScript/README.mdpp index ca432adea2..9016cab98e 100644 --- a/Documentation/Books/Users/ModuleJavaScript/README.mdpp +++ b/Documentation/Books/Users/ModuleJavaScript/README.mdpp @@ -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. diff --git a/Documentation/Books/Users/SUMMARY.md b/Documentation/Books/Users/SUMMARY.md index 26e607980c..b78c996621 100644 --- a/Documentation/Books/Users/SUMMARY.md +++ b/Documentation/Books/Users/SUMMARY.md @@ -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) diff --git a/Documentation/Books/codeBlockReader.py b/Documentation/Books/codeBlockReader.py index 44311027b6..380fcd9bfe 100644 --- a/Documentation/Books/codeBlockReader.py +++ b/Documentation/Books/codeBlockReader.py @@ -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)) diff --git a/lib/HttpServer/AsyncJobManager.h b/lib/HttpServer/AsyncJobManager.h index db8ccccb97..5b4a91c101 100644 --- a/lib/HttpServer/AsyncJobManager.h +++ b/lib/HttpServer/AsyncJobManager.h @@ -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 byStatus (AsyncJobResult::Status status, diff --git a/lib/V8/v8-utils.cpp b/lib/V8/v8-utils.cpp index a81b942ae5..ff82961dd6 100644 --- a/lib/V8/v8-utils.cpp +++ b/lib/V8/v8-utils.cpp @@ -382,7 +382,7 @@ static v8::Handle 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 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 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 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 JS_Exists (v8::Arguments const& argv) { @@ -935,10 +936,11 @@ static v8::Handle 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 JS_SizeFile (v8::Arguments const& argv) { @@ -983,10 +985,11 @@ static v8::Handle 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 JS_GetTempPath (v8::Arguments const& argv) { @@ -1010,14 +1013,15 @@ static v8::Handle 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 JS_GetTempFile (v8::Arguments const& argv) { @@ -1054,10 +1058,11 @@ static v8::Handle 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 JS_IsDirectory (v8::Arguments const& argv) { @@ -1080,10 +1085,11 @@ static v8::Handle 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 JS_IsFile (v8::Arguments const& argv) { @@ -1106,11 +1112,12 @@ static v8::Handle 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 JS_MakeAbsolute(v8::Arguments const& argv) { @@ -1151,15 +1158,16 @@ static v8::Handle 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 JS_List (v8::Arguments const& argv) { @@ -1195,14 +1203,15 @@ static v8::Handle 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 JS_ListTree (v8::Arguments const& argv) { @@ -1238,10 +1247,11 @@ static v8::Handle 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 JS_MakeDirectory (v8::Arguments const& argv) { @@ -1271,14 +1281,15 @@ static v8::Handle 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 JS_UnzipFile (v8::Arguments const& argv) { @@ -1323,12 +1334,13 @@ static v8::Handle 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 JS_ZipFile (v8::Arguments const& argv) { @@ -1393,7 +1405,7 @@ static v8::Handle 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 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 JS_Move (v8::Arguments const& argv) { @@ -1852,11 +1865,12 @@ static v8::Handle 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 JS_Read (v8::Arguments const& argv) { @@ -1888,11 +1902,12 @@ static v8::Handle 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 JS_Read64 (v8::Arguments const& argv) { @@ -1924,7 +1939,7 @@ static v8::Handle 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 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 JS_Remove (v8::Arguments const& argv) { @@ -1996,11 +2012,12 @@ static v8::Handle 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 JS_RemoveDirectory (v8::Arguments const& argv) { @@ -2032,11 +2049,12 @@ static v8::Handle 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 JS_RemoveRecursiveDirectory (v8::Arguments const& argv) {