james-server-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From btell...@apache.org
Subject [21/21] james-project git commit: JAMES-2272 Docs: Document Task API and Cassandra migration API changes on the website
Date Thu, 04 Jan 2018 08:13:36 GMT
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 <btellier@linagora.com>
Authored: Wed Dec 27 15:43:26 2017 +0700
Committer: benwa <btellier@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


Mime
View raw message