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:33 UTC
[18/21] james-project git commit: JAMES-2272 Docs: Add swagger
documentation to TaskRoutes
JAMES-2272 Docs: Add swagger documentation to TaskRoutes
Project: http://git-wip-us.apache.org/repos/asf/james-project/repo
Commit: http://git-wip-us.apache.org/repos/asf/james-project/commit/54b79056
Tree: http://git-wip-us.apache.org/repos/asf/james-project/tree/54b79056
Diff: http://git-wip-us.apache.org/repos/asf/james-project/diff/54b79056
Branch: refs/heads/master
Commit: 54b790562692ced5a0fbfb420108caabc75035bd
Parents: 1561b6a
Author: benwa <bt...@linagora.com>
Authored: Wed Dec 27 16:04:20 2017 +0700
Committer: benwa <bt...@linagora.com>
Committed: Thu Jan 4 15:12:47 2018 +0700
----------------------------------------------------------------------
.../routes/CassandraMigrationRoutes.java | 161 +++++++++++++------
.../james/webadmin/routes/TasksRoutes.java | 62 ++++++-
2 files changed, 170 insertions(+), 53 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/james-project/blob/54b79056/server/protocols/webadmin/webadmin-cassandra/src/main/java/org/apache/james/webadmin/routes/CassandraMigrationRoutes.java
----------------------------------------------------------------------
diff --git a/server/protocols/webadmin/webadmin-cassandra/src/main/java/org/apache/james/webadmin/routes/CassandraMigrationRoutes.java b/server/protocols/webadmin/webadmin-cassandra/src/main/java/org/apache/james/webadmin/routes/CassandraMigrationRoutes.java
index bff6d1f..4ae87ed 100644
--- a/server/protocols/webadmin/webadmin-cassandra/src/main/java/org/apache/james/webadmin/routes/CassandraMigrationRoutes.java
+++ b/server/protocols/webadmin/webadmin-cassandra/src/main/java/org/apache/james/webadmin/routes/CassandraMigrationRoutes.java
@@ -20,6 +20,10 @@
package org.apache.james.webadmin.routes;
import javax.inject.Inject;
+import javax.ws.rs.GET;
+import javax.ws.rs.POST;
+import javax.ws.rs.Path;
+import javax.ws.rs.Produces;
import org.apache.james.backends.cassandra.migration.CassandraMigrationService;
import org.apache.james.backends.cassandra.migration.Migration;
@@ -36,8 +40,20 @@ import org.eclipse.jetty.http.HttpStatus;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
+import io.swagger.annotations.Api;
+import io.swagger.annotations.ApiImplicitParam;
+import io.swagger.annotations.ApiImplicitParams;
+import io.swagger.annotations.ApiOperation;
+import io.swagger.annotations.ApiResponse;
+import io.swagger.annotations.ApiResponses;
+import io.swagger.annotations.ResponseHeader;
+import spark.Request;
+import spark.Response;
import spark.Service;
+@Api(tags = "Cassandra migration")
+@Path(":cassandra/version")
+@Produces("application/json")
public class CassandraMigrationRoutes implements Routes {
private static final Logger LOGGER = LoggerFactory.getLogger(CassandraMigrationRoutes.class);
@@ -65,54 +81,101 @@ public class CassandraMigrationRoutes implements Routes {
@Override
public void define(Service service) {
- service.get(VERSION_BASE,
- (request, response) -> new CassandraVersionResponse(cassandraMigrationService.getCurrentVersion()),
- jsonTransformer);
-
- service.get(VERSION_BASE_LATEST,
- (request, response) -> new CassandraVersionResponse(cassandraMigrationService.getLatestVersion()),
- jsonTransformer);
-
- service.post(VERSION_UPGRADE_BASE, (request, response) -> {
- LOGGER.debug("Cassandra upgrade launched");
- try {
- CassandraVersionRequest cassandraVersionRequest = CassandraVersionRequest.parse(request.body());
- Migration migration = cassandraMigrationService.upgradeToVersion(cassandraVersionRequest.getValue());
- TaskId taskId = taskManager.submit(migration);
- return TaskIdDto.respond(response, taskId);
- } catch (NullPointerException | IllegalArgumentException e) {
- LOGGER.info(INVALID_VERSION_UPGRADE_REQUEST);
- throw ErrorResponder.builder()
- .statusCode(HttpStatus.BAD_REQUEST_400)
- .type(ErrorType.INVALID_ARGUMENT)
- .message(INVALID_VERSION_UPGRADE_REQUEST)
- .cause(e)
- .haltError();
- } catch (IllegalStateException e) {
- LOGGER.info(MIGRATION_REQUEST_CAN_NOT_BE_DONE, e);
- throw ErrorResponder.builder()
- .statusCode(HttpStatus.CONFLICT_409)
- .type(ErrorType.WRONG_STATE)
- .message(MIGRATION_REQUEST_CAN_NOT_BE_DONE)
- .cause(e)
- .haltError();
- }
- }, jsonTransformer);
-
- service.post(VERSION_UPGRADE_TO_LATEST_BASE, (request, response) -> {
- try {
- Migration migration = cassandraMigrationService.upgradeToLastVersion();
- TaskId taskId = taskManager.submit(migration);
- return TaskIdDto.respond(response, taskId);
- } catch (IllegalStateException e) {
- LOGGER.info(MIGRATION_REQUEST_CAN_NOT_BE_DONE, e);
- throw ErrorResponder.builder()
- .statusCode(HttpStatus.CONFLICT_409)
- .type(ErrorType.WRONG_STATE)
- .message(MIGRATION_REQUEST_CAN_NOT_BE_DONE)
- .cause(e)
- .haltError();
- }
- }, jsonTransformer);
+ service.get(VERSION_BASE, (request, response) -> getCassandraCurrentVersion(), jsonTransformer);
+
+ service.get(VERSION_BASE_LATEST, (request, response) -> getCassandraLatestVersion(), jsonTransformer);
+
+ service.post(VERSION_UPGRADE_BASE, this::upgradeToVersion, jsonTransformer);
+
+ service.post(VERSION_UPGRADE_TO_LATEST_BASE, (request, response) -> upgradeToLatest(response), jsonTransformer);
+ }
+
+ @POST
+ @Path("upgrade/latest")
+ @ApiOperation("Triggers a migration of Cassandra schema to the latest available")
+ @ApiResponses({
+ @ApiResponse(code = HttpStatus.CREATED_201, message = "The taskId of the given scheduled task", response = TaskIdDto.class,
+ responseHeaders = {
+ @ResponseHeader(name = "Location", description = "URL of the resource associated with the scheduled task")
+ }),
+ @ApiResponse(code = HttpStatus.CONFLICT_409, message = "Migration can not be done")
+ })
+ public Object upgradeToLatest(Response response) {
+ try {
+ Migration migration = cassandraMigrationService.upgradeToLastVersion();
+ TaskId taskId = taskManager.submit(migration);
+ return TaskIdDto.respond(response, taskId);
+ } catch (IllegalStateException e) {
+ LOGGER.info(MIGRATION_REQUEST_CAN_NOT_BE_DONE, e);
+ throw ErrorResponder.builder()
+ .statusCode(HttpStatus.CONFLICT_409)
+ .type(ErrorType.WRONG_STATE)
+ .message(MIGRATION_REQUEST_CAN_NOT_BE_DONE)
+ .cause(e)
+ .haltError();
+ }
+ }
+
+ @POST
+ @Path("upgrade")
+ @ApiOperation("Triggers a migration of Cassandra schema to a specific version")
+ @ApiImplicitParams({
+ @ApiImplicitParam(
+ required = true,
+ paramType = "body",
+ dataType = "Integer",
+ example = "3",
+ value = "The schema version to upgrade to.")
+ })
+ @ApiResponses({
+ @ApiResponse(code = HttpStatus.CREATED_201, message = "The taskId of the given scheduled task", response = TaskIdDto.class,
+ responseHeaders = {
+ @ResponseHeader(name = "Location", description = "URL of the resource associated with the scheduled task")
+ }),
+ @ApiResponse(code = HttpStatus.CONFLICT_409, message = "Migration can not be done")
+ })
+ public Object upgradeToVersion(Request request, Response response) {
+ LOGGER.debug("Cassandra upgrade launched");
+ try {
+ CassandraVersionRequest cassandraVersionRequest = CassandraVersionRequest.parse(request.body());
+ Migration migration = cassandraMigrationService.upgradeToVersion(cassandraVersionRequest.getValue());
+ TaskId taskId = taskManager.submit(migration);
+ return TaskIdDto.from(taskId);
+ } catch (NullPointerException | IllegalArgumentException e) {
+ LOGGER.info(INVALID_VERSION_UPGRADE_REQUEST);
+ throw ErrorResponder.builder()
+ .statusCode(HttpStatus.BAD_REQUEST_400)
+ .type(ErrorType.INVALID_ARGUMENT)
+ .message(INVALID_VERSION_UPGRADE_REQUEST)
+ .cause(e)
+ .haltError();
+ } catch (IllegalStateException e) {
+ LOGGER.info(MIGRATION_REQUEST_CAN_NOT_BE_DONE, e);
+ throw ErrorResponder.builder()
+ .statusCode(HttpStatus.CONFLICT_409)
+ .type(ErrorType.WRONG_STATE)
+ .message(MIGRATION_REQUEST_CAN_NOT_BE_DONE)
+ .cause(e)
+ .haltError();
+ }
+ }
+
+ @GET
+ @Path("latest")
+ @ApiOperation(value = "Getting the latest version available for Cassandra schema")
+ @ApiResponses(value = {
+ @ApiResponse(code = HttpStatus.OK_200, message = "The latest version of the schema", response = CassandraVersionResponse.class)
+ })
+ public CassandraVersionResponse getCassandraLatestVersion() {
+ return new CassandraVersionResponse(cassandraMigrationService.getLatestVersion());
+ }
+
+ @GET
+ @ApiOperation(value = "Getting the current version used by Cassandra schema")
+ @ApiResponses(value = {
+ @ApiResponse(code = HttpStatus.OK_200, message = "The current version of the schema", response = CassandraVersionResponse.class)
+ })
+ public CassandraVersionResponse getCassandraCurrentVersion() {
+ return new CassandraVersionResponse(cassandraMigrationService.getCurrentVersion());
}
}
http://git-wip-us.apache.org/repos/asf/james-project/blob/54b79056/server/protocols/webadmin/webadmin-core/src/main/java/org/apache/james/webadmin/routes/TasksRoutes.java
----------------------------------------------------------------------
diff --git a/server/protocols/webadmin/webadmin-core/src/main/java/org/apache/james/webadmin/routes/TasksRoutes.java b/server/protocols/webadmin/webadmin-core/src/main/java/org/apache/james/webadmin/routes/TasksRoutes.java
index 99bd2df..9116b51 100644
--- a/server/protocols/webadmin/webadmin-core/src/main/java/org/apache/james/webadmin/routes/TasksRoutes.java
+++ b/server/protocols/webadmin/webadmin-core/src/main/java/org/apache/james/webadmin/routes/TasksRoutes.java
@@ -19,11 +19,16 @@
package org.apache.james.webadmin.routes;
+import java.util.List;
import java.util.Optional;
import java.util.UUID;
import java.util.function.Supplier;
import javax.inject.Inject;
+import javax.ws.rs.DELETE;
+import javax.ws.rs.GET;
+import javax.ws.rs.Path;
+import javax.ws.rs.Produces;
import org.apache.james.task.TaskExecutionDetails;
import org.apache.james.task.TaskId;
@@ -36,10 +41,19 @@ import org.apache.james.webadmin.utils.ErrorResponder;
import org.apache.james.webadmin.utils.JsonTransformer;
import org.eclipse.jetty.http.HttpStatus;
+import io.swagger.annotations.Api;
+import io.swagger.annotations.ApiImplicitParam;
+import io.swagger.annotations.ApiImplicitParams;
+import io.swagger.annotations.ApiOperation;
+import io.swagger.annotations.ApiResponse;
+import io.swagger.annotations.ApiResponses;
import spark.Request;
import spark.Response;
import spark.Service;
+@Api(tags = "Tasks")
+@Path(":task")
+@Produces("application/json")
public class TasksRoutes implements Routes {
public static final String BASE = "/tasks";
private final TaskManager taskManager;
@@ -62,7 +76,24 @@ public class TasksRoutes implements Routes {
service.get(BASE, this::list, jsonTransformer);
}
- private Object list(Request req, Response response) {
+ @GET
+ @ApiOperation(value = "Listing tasks")
+ @ApiImplicitParams({
+ @ApiImplicitParam(
+ required = false,
+ paramType = "query parameter",
+ dataType = "String",
+ defaultValue = "None",
+ example = "?status=inProgress",
+ value = "If present, allow to filter the tasks and keep only the one with a given status. " +
+ "The status are one of [waiting, inProgress, failed, canceled, completed]")
+ })
+ @ApiResponses(value = {
+ @ApiResponse(code = HttpStatus.OK_200, message = "A specific class execution details", response = List.class),
+ @ApiResponse(code = HttpStatus.BAD_REQUEST_400, message = "The provided payload is invalid (JSON error or invalid status)"),
+ @ApiResponse(code = HttpStatus.NOT_FOUND_404, message = "The taskId is not found")
+ })
+ public Object list(Request req, Response response) {
try {
return ExecutionDetailsDto.from(
Optional.ofNullable(req.queryParams("status"))
@@ -79,13 +110,29 @@ public class TasksRoutes implements Routes {
}
}
- private Object getStatus(Request req, Response response) {
+ @GET
+ @Path("/{taskId}")
+ @ApiOperation(value = "Getting a task execution details")
+ @ApiResponses(value = {
+ @ApiResponse(code = HttpStatus.OK_200, message = "A specific class execution details", response = ExecutionDetailsDto.class),
+ @ApiResponse(code = HttpStatus.BAD_REQUEST_400, message = "The taskId is invalid"),
+ @ApiResponse(code = HttpStatus.NOT_FOUND_404, message = "The taskId is not found")
+ })
+ public Object getStatus(Request req, Response response) {
TaskId taskId = getTaskId(req);
return respondStatus(taskId,
() -> taskManager.getExecutionDetails(getTaskId(req)));
}
- private Object await(Request req, Response response) {
+ @GET
+ @Path("/{taskId}/await")
+ @ApiOperation(value = "Await, then get a task execution details")
+ @ApiResponses(value = {
+ @ApiResponse(code = HttpStatus.OK_200, message = "A specific class execution details", response = ExecutionDetailsDto.class),
+ @ApiResponse(code = HttpStatus.BAD_REQUEST_400, message = "The taskId is invalid"),
+ @ApiResponse(code = HttpStatus.NOT_FOUND_404, message = "The taskId is not found")
+ })
+ public Object await(Request req, Response response) {
TaskId taskId = getTaskId(req);
return respondStatus(taskId,
() -> taskManager.await(getTaskId(req)));
@@ -104,7 +151,14 @@ public class TasksRoutes implements Routes {
}
}
- private Object cancel(Request req, Response response) {
+ @DELETE
+ @Path("/{taskId}")
+ @ApiOperation(value = "Cancel a given task")
+ @ApiResponses(value = {
+ @ApiResponse(code = HttpStatus.NO_CONTENT_204, message = "Task is cancelled"),
+ @ApiResponse(code = HttpStatus.BAD_REQUEST_400, message = "The taskId is invalid")
+ })
+ public Object cancel(Request req, Response response) {
TaskId taskId = getTaskId(req);
taskManager.cancel(taskId);
response.status(HttpStatus.NO_CONTENT_204);
---------------------------------------------------------------------
To unsubscribe, e-mail: server-dev-unsubscribe@james.apache.org
For additional commands, e-mail: server-dev-help@james.apache.org