You are viewing a plain text version of this content. The canonical link for it is here.
Posted to server-dev@james.apache.org by bt...@apache.org on 2018/01/04 08:13:36 UTC
[21/21] james-project git commit: JAMES-2272 Docs: Document Task API
and Cassandra migration API changes on the website
JAMES-2272 Docs: Document Task API and Cassandra migration API changes on the website
Project: http://git-wip-us.apache.org/repos/asf/james-project/repo
Commit: http://git-wip-us.apache.org/repos/asf/james-project/commit/1561b6af
Tree: http://git-wip-us.apache.org/repos/asf/james-project/tree/1561b6af
Diff: http://git-wip-us.apache.org/repos/asf/james-project/diff/1561b6af
Branch: refs/heads/master
Commit: 1561b6afca5a65b813c23410e749f943460e8d97
Parents: 45eec2e
Author: benwa <bt...@linagora.com>
Authored: Wed Dec 27 15:43:26 2017 +0700
Committer: benwa <bt...@linagora.com>
Committed: Thu Jan 4 15:12:47 2018 +0700
----------------------------------------------------------------------
src/site/markdown/server/manage-webadmin.md | 147 +++++++++++++++++++++--
1 file changed, 138 insertions(+), 9 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/james-project/blob/1561b6af/src/site/markdown/server/manage-webadmin.md
----------------------------------------------------------------------
diff --git a/src/site/markdown/server/manage-webadmin.md b/src/site/markdown/server/manage-webadmin.md
index e0f59af..10347ea 100644
--- a/src/site/markdown/server/manage-webadmin.md
+++ b/src/site/markdown/server/manage-webadmin.md
@@ -405,37 +405,67 @@ Response codes:
curl -XPOST http://ip:port/cassandra/version/upgrade -d '3'
```
-Will run the migrations you need to reach schema version 3.
+
+Will schedule the run of the migrations you need to reach schema version 3. The `taskId` will allow you to monitor and manage this process.
+
+```
+{"taskId":"3294a976-ce63-491e-bd52-1b6f465ed7a2"}
+```
Response codes:
- - 204: Success
+ - 200: Success. The scheduled task taskId is returned.
- 400: The version is invalid. The version should be a strictly positive number.
- - 410: Error running the migration. This resource is gone away. Reason is mentionned in the body.
- - 500: Internal error. This can result from a partial migration, in which case the reason is contained in the body.
+ - 410: Error while planning this migration. This resource is gone away. Reason is mentionned in the body.
+ - 500: Internal error while creating the migration task.
Note that several calls to this endpoint will be run in a sequential pattern.
If the server restarts during the migration, the migration is silently aborted.
+
+The scheduled task will have the following type `CassandraMigration` and the following `additionalInformation`:
+
+```
+{"toVersion":3}
+```
+
### Upgrading to the latest version
```
curl -XPOST http://ip:port/cassandra/version/upgrade/latest
```
-Will run the migrations you need to reach the latest schema version.
+Will schedule the run of the migrations you need to reach the latest schema version. The `taskId` will allow you to monitor and manage this process.
+
+```
+{"taskId":"3294a976-ce63-491e-bd52-1b6f465ed7a2"}
+```
+
+Positionned headers:
+
+ - Location header indicates the location of the resource associated with the scheduled task. Example:
+
+```
+Location: /tasks/3294a976-ce63-491e-bd52-1b6f465ed7a2
+```
Response codes:
- - 204: Success
- - 410: Error running the migration. This resource is gone away. Reason is mentionned in the body.
- - 500: Internal error. This can result from a partial migration, in which case the reason is contained in the body.
+ - 200: Success. The scheduled task taskId is returned.
+ - 410: Error while planning this migration. This resource is gone away. Reason is mentionned in the body.
+ - 500: Internal error while creating the migration task.
Note that several calls to this endpoint will be run in a sequential pattern.
If the server restarts during the migration, the migration is silently aborted.
+The scheduled task will have the following type `CassandraMigration` and the following `additionalInformation`:
+
+```
+{"toVersion":2}
+```
+
## Creating address group
You can use **webadmin** to define address groups.
@@ -512,4 +542,103 @@ Response codes:
- 200: Success
- 400: Group structure or member is not valid
- - 500: Internal error
\ No newline at end of file
+ - 500: Internal error
+
+## Task management
+
+Some webadmin features schedules tasks. The task management API allow to monitor and manage the execution of the following tasks.
+
+Note that the `taskId` used in the following APIs is returned by other WebAdmin APIs scheduling tasks.
+
+### Getting a task details
+
+```
+curl -XGET http://ip:port/tasks/3294a976-ce63-491e-bd52-1b6f465ed7a2
+```
+
+An Execution Report will be returned:
+
+```
+{
+ "submitDate": "2017-12-27T15:15:24.805+0700",
+ "startedDate": "2017-12-27T15:15:24.809+0700",
+ "completedDate": "2017-12-27T15:15:24.815+0700",
+ "cancelledDate": null,
+ "failedDate": null,
+ "taskId": "3294a976-ce63-491e-bd52-1b6f465ed7a2",
+ "additionalInformation": {},
+ "status": "completed",
+ "type": "typeOfTheTask"
+}
+```
+
+Note that:
+
+ - `status` can have the value:
+ - `waiting`: The task is schedule but its execution did not start yet
+ - `inProgress`: The task is currently executed
+ - `cancelled`: The task had been cancelled
+ - `completed`: The task execution is finished, and this execution is a success
+ - `failed`: The task execution is finished, and this execution is a failure
+
+ - `additionalInformation` is a task specific object giving additional informationa and context about that task. The structure
+ of this `additionalInformation` field is provided along the specific task submission endpoint.
+
+Response codes:
+
+ - 200: The specific task was found and the execution report exposed above is returned
+ - 400: Invalid task ID
+ - 404: Task ID was not found
+
+### Awaiting a task
+
+One can await the end of a task, then receive it's final execution report.
+
+That feature is especially usefull for testing purpose but still can serve real-life scenari.
+
+```
+curl -XGET http://ip:port/tasks/3294a976-ce63-491e-bd52-1b6f465ed7a2/await
+```
+
+An Execution Report will be returned.
+
+Response codes:
+
+ - 200: The specific task was found and the execution report exposed above is returned
+ - 400: Invalid task ID
+ - 404: Task ID was not found
+
+### Cancelling a task
+
+You can cancel a task by calling:
+
+```
+curl -XDELETE http://ip:port/tasks/3294a976-ce63-491e-bd52-1b6f465ed7a2
+```
+
+Response codes:
+ - 204: Task had been cancelled
+ - 400: Invalid task ID
+
+### Listing tasks
+
+A list of all tasks can be retrieved:
+
+```
+curl -XGET /tasks
+```
+
+Will return a list of Execution reports
+
+One can filter the above results by status. For example:
+
+```
+curl -XGET /tasks?status=inProgress
+```
+
+Will return a list of Execution reports that are currently in progress.
+
+Response codes:
+
+ - 200: A list of corresponding tasks is returned
+ - 400: Invalid status value
\ No newline at end of file
---------------------------------------------------------------------
To unsubscribe, e-mail: server-dev-unsubscribe@james.apache.org
For additional commands, e-mail: server-dev-help@james.apache.org