NIFI-292: - Continuing to document/annotate REST resources. Project: http://git-wip-us.apache.org/repos/asf/incubator-nifi/repo Commit: http://git-wip-us.apache.org/repos/asf/incubator-nifi/commit/bb956284 Tree: http://git-wip-us.apache.org/repos/asf/incubator-nifi/tree/bb956284 Diff: http://git-wip-us.apache.org/repos/asf/incubator-nifi/diff/bb956284
Branch: refs/heads/NIFI-292 Commit: bb9562845738144372ad2baaff4546a51c3e76b0 Parents: 0e44b9f Author: Matt Gilman <[email protected]> Authored: Wed Apr 29 11:47:10 2015 -0400 Committer: Matt Gilman <[email protected]> Committed: Wed Apr 29 11:47:10 2015 -0400 ---------------------------------------------------------------------- .../apache/nifi/web/api/ConnectionResource.java | 3 +- .../nifi/web/api/ControllerServiceResource.java | 16 +- .../apache/nifi/web/api/ProvenanceResource.java | 305 ++++++++++++++++++- .../web/api/RemoteProcessGroupResource.java | 198 +++++++++++- .../nifi/web/api/ReportingTaskResource.java | 279 +++++++++++++++-- .../apache/nifi/web/api/SnippetResource.java | 164 +++++++++- .../nifi/web/api/SystemDiagnosticsResource.java | 34 ++- .../apache/nifi/web/api/TemplateResource.java | 141 ++++++++- .../apache/nifi/web/api/UserGroupResource.java | 112 ++++++- .../org/apache/nifi/web/api/UserResource.java | 152 ++++++++- 10 files changed, 1322 insertions(+), 82 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/incubator-nifi/blob/bb956284/nifi/nifi-nar-bundles/nifi-framework-bundle/nifi-framework/nifi-web/nifi-web-api/src/main/java/org/apache/nifi/web/api/ConnectionResource.java ---------------------------------------------------------------------- diff --git a/nifi/nifi-nar-bundles/nifi-framework-bundle/nifi-framework/nifi-web/nifi-web-api/src/main/java/org/apache/nifi/web/api/ConnectionResource.java b/nifi/nifi-nar-bundles/nifi-framework-bundle/nifi-framework/nifi-web/nifi-web-api/src/main/java/org/apache/nifi/web/api/ConnectionResource.java index c518750..5dfc8ad 100644 --- a/nifi/nifi-nar-bundles/nifi-framework-bundle/nifi-framework/nifi-web/nifi-web-api/src/main/java/org/apache/nifi/web/api/ConnectionResource.java +++ b/nifi/nifi-nar-bundles/nifi-framework-bundle/nifi-framework/nifi-web/nifi-web-api/src/main/java/org/apache/nifi/web/api/ConnectionResource.java @@ -482,7 +482,8 @@ public class ConnectionResource extends ApplicationResource { @ApiParam( value = "The connection configuration details.", required = true - ) ConnectionEntity connectionEntity) { + ) + ConnectionEntity connectionEntity) { if (connectionEntity == null || connectionEntity.getConnection() == null) { throw new IllegalArgumentException("Connection details must be specified."); http://git-wip-us.apache.org/repos/asf/incubator-nifi/blob/bb956284/nifi/nifi-nar-bundles/nifi-framework-bundle/nifi-framework/nifi-web/nifi-web-api/src/main/java/org/apache/nifi/web/api/ControllerServiceResource.java ---------------------------------------------------------------------- diff --git a/nifi/nifi-nar-bundles/nifi-framework-bundle/nifi-framework/nifi-web/nifi-web-api/src/main/java/org/apache/nifi/web/api/ControllerServiceResource.java b/nifi/nifi-nar-bundles/nifi-framework-bundle/nifi-framework/nifi-web/nifi-web-api/src/main/java/org/apache/nifi/web/api/ControllerServiceResource.java index 1581722..5ed57d2 100644 --- a/nifi/nifi-nar-bundles/nifi-framework-bundle/nifi-framework/nifi-web/nifi-web-api/src/main/java/org/apache/nifi/web/api/ControllerServiceResource.java +++ b/nifi/nifi-nar-bundles/nifi-framework-bundle/nifi-framework/nifi-web/nifi-web-api/src/main/java/org/apache/nifi/web/api/ControllerServiceResource.java @@ -191,7 +191,7 @@ public class ControllerServiceResource extends ApplicationResource { ) @QueryParam(CLIENT_ID) @DefaultValue(StringUtils.EMPTY) ClientIdParameter clientId, @ApiParam( - value = "Whether the controller is available on the NCM or nodes. If the NiFi is standalone the availability should be NODE.", + value = "Whether the controller service is available on the NCM or nodes. If the NiFi is standalone the availability should be NODE.", allowableValues = "NCM, NODE", required = true ) @@ -301,7 +301,7 @@ public class ControllerServiceResource extends ApplicationResource { public Response createControllerService( @Context HttpServletRequest httpServletRequest, @ApiParam( - value = "Whether the controller is available on the NCM or nodes. If the NiFi is standalone the availability should be NODE.", + value = "Whether the controller service is available on the NCM or nodes. If the NiFi is standalone the availability should be NODE.", allowableValues = "NCM, NODE", required = true ) @@ -424,7 +424,7 @@ public class ControllerServiceResource extends ApplicationResource { ) @QueryParam(CLIENT_ID) @DefaultValue(StringUtils.EMPTY) ClientIdParameter clientId, @ApiParam( - value = "Whether the controller is available on the NCM or nodes. If the NiFi is standalone the availability should be NODE.", + value = "Whether the controller service is available on the NCM or nodes. If the NiFi is standalone the availability should be NODE.", allowableValues = "NCM, NODE", required = true ) @@ -499,7 +499,7 @@ public class ControllerServiceResource extends ApplicationResource { ) @QueryParam(CLIENT_ID) @DefaultValue(StringUtils.EMPTY) ClientIdParameter clientId, @ApiParam( - value = "Whether the controller is available on the NCM or nodes. If the NiFi is standalone the availability should be NODE.", + value = "Whether the controller service is available on the NCM or nodes. If the NiFi is standalone the availability should be NODE.", allowableValues = "NCM, NODE", required = true ) @@ -586,7 +586,7 @@ public class ControllerServiceResource extends ApplicationResource { ) @QueryParam(CLIENT_ID) @DefaultValue(StringUtils.EMPTY) ClientIdParameter clientId, @ApiParam( - value = "Whether the controller is available on the NCM or nodes. If the NiFi is standalone the availability should be NODE.", + value = "Whether the controller service is available on the NCM or nodes. If the NiFi is standalone the availability should be NODE.", allowableValues = "NCM, NODE", required = true ) @@ -673,7 +673,7 @@ public class ControllerServiceResource extends ApplicationResource { ) @FormParam(CLIENT_ID) @DefaultValue(StringUtils.EMPTY) ClientIdParameter clientId, @ApiParam( - value = "Whether the controller is available on the NCM or nodes. If the NiFi is standalone the availability should be NODE.", + value = "Whether the controller service is available on the NCM or nodes. If the NiFi is standalone the availability should be NODE.", allowableValues = "NCM, NODE", required = true ) @@ -898,7 +898,7 @@ public class ControllerServiceResource extends ApplicationResource { public Response updateControllerService( @Context HttpServletRequest httpServletRequest, @ApiParam( - value = "Whether the controller is available on the NCM or nodes. If the NiFi is standalone the availability should be NODE.", + value = "Whether the controller service is available on the NCM or nodes. If the NiFi is standalone the availability should be NODE.", allowableValues = "NCM, NODE", required = true ) @@ -1018,7 +1018,7 @@ public class ControllerServiceResource extends ApplicationResource { ) @QueryParam(CLIENT_ID) @DefaultValue(StringUtils.EMPTY) ClientIdParameter clientId, @ApiParam( - value = "Whether the controller is available on the NCM or nodes. If the NiFi is standalone the availability should be NODE.", + value = "Whether the controller service is available on the NCM or nodes. If the NiFi is standalone the availability should be NODE.", allowableValues = "NCM, NODE", required = true ) http://git-wip-us.apache.org/repos/asf/incubator-nifi/blob/bb956284/nifi/nifi-nar-bundles/nifi-framework-bundle/nifi-framework/nifi-web/nifi-web-api/src/main/java/org/apache/nifi/web/api/ProvenanceResource.java ---------------------------------------------------------------------- diff --git a/nifi/nifi-nar-bundles/nifi-framework-bundle/nifi-framework/nifi-web/nifi-web-api/src/main/java/org/apache/nifi/web/api/ProvenanceResource.java b/nifi/nifi-nar-bundles/nifi-framework-bundle/nifi-framework/nifi-web/nifi-web-api/src/main/java/org/apache/nifi/web/api/ProvenanceResource.java index 574ec3d..012a1d3 100644 --- a/nifi/nifi-nar-bundles/nifi-framework-bundle/nifi-framework/nifi-web/nifi-web-api/src/main/java/org/apache/nifi/web/api/ProvenanceResource.java +++ b/nifi/nifi-nar-bundles/nifi-framework-bundle/nifi-framework/nifi-web/nifi-web-api/src/main/java/org/apache/nifi/web/api/ProvenanceResource.java @@ -17,6 +17,11 @@ package org.apache.nifi.web.api; import com.wordnik.swagger.annotations.Api; +import com.wordnik.swagger.annotations.ApiOperation; +import com.wordnik.swagger.annotations.ApiParam; +import com.wordnik.swagger.annotations.ApiResponse; +import com.wordnik.swagger.annotations.ApiResponses; +import com.wordnik.swagger.annotations.Authorization; import java.io.IOException; import java.io.InputStream; import java.io.OutputStream; @@ -119,11 +124,33 @@ public class ProvenanceResource extends ApplicationResource { * @return A provenanceOptionsEntity */ @GET + @Consumes(MediaType.WILDCARD) @Produces({MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML}) @Path("/search-options") @PreAuthorize("hasRole('ROLE_PROVENANCE')") @TypeHint(ProvenanceOptionsEntity.class) - public Response getSearchOptions(@QueryParam(CLIENT_ID) @DefaultValue(StringUtils.EMPTY) ClientIdParameter clientId) { + @ApiOperation( + value = "Gets the searchable attributes for provenance events", + response = ProvenanceOptionsEntity.class, + authorizations = { + @Authorization(value = "Provenance", type = "ROLE_PROVENANCE") + } + ) + @ApiResponses( + value = { + @ApiResponse(code = 400, message = "NiFi was unable to complete the request because it was invalid. The request should not be retried without modification."), + @ApiResponse(code = 401, message = "Client could not be authenticated."), + @ApiResponse(code = 403, message = "Client is not authorized to make this request."), + @ApiResponse(code = 409, message = "The request was valid but NiFi was not in the appropriate state to process it. Retrying the same request later may be successful.") + } + ) + public Response getSearchOptions( + @ApiParam( + value = "If the client id is not specified, new one will be generated. This value (whether specified or generated) is included in the response.", + required = false + ) + @QueryParam(CLIENT_ID) @DefaultValue(StringUtils.EMPTY) ClientIdParameter clientId) { + // replicate if cluster manager if (properties.isClusterManager()) { return clusterManager.applyRequest(HttpMethod.GET, getAbsolutePath(), getRequestParameters(true), getHeaders()).getResponse(); @@ -155,14 +182,43 @@ public class ProvenanceResource extends ApplicationResource { * @return A provenanceEventEntity */ @POST + @Consumes(MediaType.WILDCARD) @Produces({MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML}) - @PreAuthorize("hasRole('ROLE_PROVENANCE') and hasRole('ROLE_DFM')") @Path("/replays") + @PreAuthorize("hasRole('ROLE_PROVENANCE') and hasRole('ROLE_DFM')") @TypeHint(ProvenanceEventEntity.class) + @ApiOperation( + value = "Replays content from a provenance event", + response = ProvenanceEventEntity.class, + authorizations = { + @Authorization(value = "Provenance and Data Flow Manager", type = "ROLE_PROVENANCE and ROLE_DFM") + } + ) + @ApiResponses( + value = { + @ApiResponse(code = 400, message = "NiFi was unable to complete the request because it was invalid. The request should not be retried without modification."), + @ApiResponse(code = 401, message = "Client could not be authenticated."), + @ApiResponse(code = 403, message = "Client is not authorized to make this request."), + @ApiResponse(code = 404, message = "The specified resource could not be found."), + @ApiResponse(code = 409, message = "The request was valid but NiFi was not in the appropriate state to process it. Retrying the same request later may be successful.") + } + ) public Response submitReplay( @Context HttpServletRequest httpServletRequest, + @ApiParam( + value = "If the client id is not specified, new one will be generated. This value (whether specified or generated) is included in the response.", + required = false + ) @FormParam(CLIENT_ID) @DefaultValue(StringUtils.EMPTY) ClientIdParameter clientId, + @ApiParam( + value = "The id of the node where the content exists if clustered.", + required = false + ) @FormParam("clusterNodeId") String clusterNodeId, + @ApiParam( + value = "The provenance event id.", + required = true + ) @FormParam("eventId") LongParameter eventId) { // ensure the event id is specified @@ -222,12 +278,40 @@ public class ProvenanceResource extends ApplicationResource { * @return The content stream */ @GET + @Consumes(MediaType.WILDCARD) @Produces(MediaType.APPLICATION_OCTET_STREAM) @Path("/events/{id}/content/input") @PreAuthorize("hasRole('ROLE_PROVENANCE')") + @ApiOperation( + value = "Gets the input content for a provenance event", + authorizations = { + @Authorization(value = "Provenance", type = "ROLE_PROVENANCE") + } + ) + @ApiResponses( + value = { + @ApiResponse(code = 400, message = "NiFi was unable to complete the request because it was invalid. The request should not be retried without modification."), + @ApiResponse(code = 401, message = "Client could not be authenticated."), + @ApiResponse(code = 403, message = "Client is not authorized to make this request."), + @ApiResponse(code = 404, message = "The specified resource could not be found."), + @ApiResponse(code = 409, message = "The request was valid but NiFi was not in the appropriate state to process it. Retrying the same request later may be successful.") + } + ) public Response getInputContent( + @ApiParam( + value = "If the client id is not specified, new one will be generated. This value (whether specified or generated) is included in the response.", + required = false + ) @QueryParam(CLIENT_ID) @DefaultValue(StringUtils.EMPTY) ClientIdParameter clientId, + @ApiParam( + value = "The id of the node where the content exists if clustered.", + required = false + ) @QueryParam("clusterNodeId") String clusterNodeId, + @ApiParam( + value = "The provenance event id.", + required = true + ) @PathParam("id") LongParameter id) { // ensure proper input @@ -293,12 +377,40 @@ public class ProvenanceResource extends ApplicationResource { * @return The content stream */ @GET + @Consumes(MediaType.WILDCARD) @Produces(MediaType.APPLICATION_OCTET_STREAM) @Path("/events/{id}/content/output") @PreAuthorize("hasRole('ROLE_PROVENANCE')") + @ApiOperation( + value = "Gets the output content for a provenance event", + authorizations = { + @Authorization(value = "Provenance", type = "ROLE_PROVENANCE") + } + ) + @ApiResponses( + value = { + @ApiResponse(code = 400, message = "NiFi was unable to complete the request because it was invalid. The request should not be retried without modification."), + @ApiResponse(code = 401, message = "Client could not be authenticated."), + @ApiResponse(code = 403, message = "Client is not authorized to make this request."), + @ApiResponse(code = 404, message = "The specified resource could not be found."), + @ApiResponse(code = 409, message = "The request was valid but NiFi was not in the appropriate state to process it. Retrying the same request later may be successful.") + } + ) public Response getOutputContent( + @ApiParam( + value = "If the client id is not specified, new one will be generated. This value (whether specified or generated) is included in the response.", + required = false + ) @QueryParam(CLIENT_ID) @DefaultValue(StringUtils.EMPTY) ClientIdParameter clientId, + @ApiParam( + value = "The id of the node where the content exists if clustered.", + required = false + ) @QueryParam("clusterNodeId") String clusterNodeId, + @ApiParam( + value = "The provenance event id.", + required = true + ) @PathParam("id") LongParameter id) { // ensure proper input @@ -376,7 +488,9 @@ public class ProvenanceResource extends ApplicationResource { * @return A provenanceEntity */ @POST + @Consumes(MediaType.APPLICATION_FORM_URLENCODED) @Produces({MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML}) + @Path("") // necessary due to bug in swagger @PreAuthorize("hasRole('ROLE_PROVENANCE')") @TypeHint(ProvenanceEntity.class) public Response submitProvenanceRequest( @@ -458,11 +572,30 @@ public class ProvenanceResource extends ApplicationResource { @POST @Consumes({MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML}) @Produces({MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML}) + @Path("") // necessary due to bug in swagger @PreAuthorize("hasRole('ROLE_PROVENANCE')") @TypeHint(ProvenanceEntity.class) + @ApiOperation( + value = "Submits a provenance query", + response = ProvenanceEntity.class, + authorizations = { + @Authorization(value = "Provenance", type = "ROLE_PROVENANCE") + } + ) + @ApiResponses( + value = { + @ApiResponse(code = 400, message = "NiFi was unable to complete the request because it was invalid. The request should not be retried without modification."), + @ApiResponse(code = 401, message = "Client could not be authenticated."), + @ApiResponse(code = 403, message = "Client is not authorized to make this request."), + @ApiResponse(code = 409, message = "The request was valid but NiFi was not in the appropriate state to process it. Retrying the same request later may be successful.") + } + ) public Response submitProvenanceRequest( @Context HttpServletRequest httpServletRequest, - ProvenanceEntity provenanceEntity) { + @ApiParam( + value = "The provenance query details.", + required = true + ) ProvenanceEntity provenanceEntity) { // check the request if (provenanceEntity == null) { @@ -550,13 +683,42 @@ public class ProvenanceResource extends ApplicationResource { * @return A provenanceEntity */ @GET + @Consumes(MediaType.WILDCARD) @Produces({MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML}) @Path("/{id}") @PreAuthorize("hasRole('ROLE_PROVENANCE')") @TypeHint(ProvenanceEntity.class) + @ApiOperation( + value = "Gets a provenance query", + response = ProvenanceEntity.class, + authorizations = { + @Authorization(value = "Provenance", type = "ROLE_PROVENANCE") + } + ) + @ApiResponses( + value = { + @ApiResponse(code = 400, message = "NiFi was unable to complete the request because it was invalid. The request should not be retried without modification."), + @ApiResponse(code = 401, message = "Client could not be authenticated."), + @ApiResponse(code = 403, message = "Client is not authorized to make this request."), + @ApiResponse(code = 404, message = "The specified resource could not be found."), + @ApiResponse(code = 409, message = "The request was valid but NiFi was not in the appropriate state to process it. Retrying the same request later may be successful.") + } + ) public Response getProvenance( + @ApiParam( + value = "If the client id is not specified, new one will be generated. This value (whether specified or generated) is included in the response.", + required = false + ) @QueryParam(CLIENT_ID) @DefaultValue(StringUtils.EMPTY) ClientIdParameter clientId, + @ApiParam( + value = "The id of the node where this query exists if clustered.", + required = false + ) @QueryParam("clusterNodeId") String clusterNodeId, + @ApiParam( + value = "The id of the provenance query.", + required = true + ) @PathParam("id") String id) { // replicate if cluster manager @@ -608,14 +770,43 @@ public class ProvenanceResource extends ApplicationResource { * @return A provenanceEntity */ @DELETE + @Consumes(MediaType.WILDCARD) @Produces({MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML}) @Path("/{id}") @PreAuthorize("hasRole('ROLE_PROVENANCE')") @TypeHint(ProvenanceEntity.class) + @ApiOperation( + value = "Deletes a provenance query", + response = ProvenanceEntity.class, + authorizations = { + @Authorization(value = "Provenance", type = "ROLE_PROVENANCE") + } + ) + @ApiResponses( + value = { + @ApiResponse(code = 400, message = "NiFi was unable to complete the request because it was invalid. The request should not be retried without modification."), + @ApiResponse(code = 401, message = "Client could not be authenticated."), + @ApiResponse(code = 403, message = "Client is not authorized to make this request."), + @ApiResponse(code = 404, message = "The specified resource could not be found."), + @ApiResponse(code = 409, message = "The request was valid but NiFi was not in the appropriate state to process it. Retrying the same request later may be successful.") + } + ) public Response deleteProvenance( @Context HttpServletRequest httpServletRequest, + @ApiParam( + value = "If the client id is not specified, new one will be generated. This value (whether specified or generated) is included in the response.", + required = false + ) @QueryParam(CLIENT_ID) @DefaultValue(StringUtils.EMPTY) ClientIdParameter clientId, + @ApiParam( + value = "The id of the node where this query exists if clustered.", + required = false + ) @QueryParam("clusterNodeId") String clusterNodeId, + @ApiParam( + value = "The id of the provenance query.", + required = true + ) @PathParam("id") String id) { // replicate if cluster manager @@ -669,13 +860,42 @@ public class ProvenanceResource extends ApplicationResource { * @return A provenanceEventEntity */ @GET + @Consumes(MediaType.WILDCARD) @Produces({MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML}) @Path("/events/{id}") @PreAuthorize("hasRole('ROLE_PROVENANCE')") @TypeHint(ProvenanceEventEntity.class) + @ApiOperation( + value = "Gets a provenance event", + response = ProvenanceEventEntity.class, + authorizations = { + @Authorization(value = "Provenance", type = "ROLE_PROVENANCE") + } + ) + @ApiResponses( + value = { + @ApiResponse(code = 400, message = "NiFi was unable to complete the request because it was invalid. The request should not be retried without modification."), + @ApiResponse(code = 401, message = "Client could not be authenticated."), + @ApiResponse(code = 403, message = "Client is not authorized to make this request."), + @ApiResponse(code = 404, message = "The specified resource could not be found."), + @ApiResponse(code = 409, message = "The request was valid but NiFi was not in the appropriate state to process it. Retrying the same request later may be successful.") + } + ) public Response getProvenanceEvent( + @ApiParam( + value = "If the client id is not specified, new one will be generated. This value (whether specified or generated) is included in the response.", + required = false + ) @QueryParam(CLIENT_ID) @DefaultValue(StringUtils.EMPTY) ClientIdParameter clientId, + @ApiParam( + value = "The id of the node where this event exists if clustered.", + required = false + ) @QueryParam("clusterNodeId") String clusterNodeId, + @ApiParam( + value = "The provenence event id.", + required = true + ) @PathParam("id") LongParameter id) { // ensure the id is specified @@ -740,6 +960,7 @@ public class ProvenanceResource extends ApplicationResource { * @return A lineageEntity */ @POST + @Consumes(MediaType.APPLICATION_FORM_URLENCODED) @Produces({MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML}) @Path("/lineage") @PreAuthorize("hasRole('ROLE_PROVENANCE')") @@ -806,8 +1027,28 @@ public class ProvenanceResource extends ApplicationResource { @Path("/lineage") @PreAuthorize("hasRole('ROLE_PROVENANCE')") @TypeHint(LineageEntity.class) + @ApiOperation( + value = "Submits a lineage query", + response = LineageEntity.class, + authorizations = { + @Authorization(value = "Provenance", type = "ROLE_PROVENANCE") + } + ) + @ApiResponses( + value = { + @ApiResponse(code = 400, message = "NiFi was unable to complete the request because it was invalid. The request should not be retried without modification."), + @ApiResponse(code = 401, message = "Client could not be authenticated."), + @ApiResponse(code = 403, message = "Client is not authorized to make this request."), + @ApiResponse(code = 404, message = "The specified resource could not be found."), + @ApiResponse(code = 409, message = "The request was valid but NiFi was not in the appropriate state to process it. Retrying the same request later may be successful.") + } + ) public Response submitLineageRequest( @Context HttpServletRequest httpServletRequest, + @ApiParam( + value = "The lineage query details.", + required = true + ) final LineageEntity lineageEntity) { if (lineageEntity == null || lineageEntity.getLineage() == null || lineageEntity.getLineage().getRequest() == null) { @@ -900,13 +1141,42 @@ public class ProvenanceResource extends ApplicationResource { * @return A lineageEntity */ @GET + @Consumes(MediaType.WILDCARD) @Produces({MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML}) @Path("/lineage/{id}") @PreAuthorize("hasRole('ROLE_PROVENANCE')") @TypeHint(LineageEntity.class) + @ApiOperation( + value = "Gets a lineage query", + response = LineageEntity.class, + authorizations = { + @Authorization(value = "Provenance", type = "ROLE_PROVENANCE") + } + ) + @ApiResponses( + value = { + @ApiResponse(code = 400, message = "NiFi was unable to complete the request because it was invalid. The request should not be retried without modification."), + @ApiResponse(code = 401, message = "Client could not be authenticated."), + @ApiResponse(code = 403, message = "Client is not authorized to make this request."), + @ApiResponse(code = 404, message = "The specified resource could not be found."), + @ApiResponse(code = 409, message = "The request was valid but NiFi was not in the appropriate state to process it. Retrying the same request later may be successful.") + } + ) public Response getLineage( + @ApiParam( + value = "If the client id is not specified, new one will be generated. This value (whether specified or generated) is included in the response.", + required = false + ) @QueryParam(CLIENT_ID) @DefaultValue(StringUtils.EMPTY) ClientIdParameter clientId, + @ApiParam( + value = "The id of the node where this query exists if clustered.", + required = false + ) @QueryParam("clusterNodeId") String clusterNodeId, + @ApiParam( + value = "The id of the lineage query.", + required = true + ) @PathParam("id") String id) { // replicate if cluster manager @@ -956,14 +1226,43 @@ public class ProvenanceResource extends ApplicationResource { * @return A lineageEntity */ @DELETE + @Consumes(MediaType.WILDCARD) @Produces({MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML}) @Path("/lineage/{id}") @PreAuthorize("hasRole('ROLE_PROVENANCE')") @TypeHint(LineageEntity.class) + @ApiOperation( + value = "Deletes a lineage query", + response = LineageEntity.class, + authorizations = { + @Authorization(value = "Provenance", type = "ROLE_PROVENANCE") + } + ) + @ApiResponses( + value = { + @ApiResponse(code = 400, message = "NiFi was unable to complete the request because it was invalid. The request should not be retried without modification."), + @ApiResponse(code = 401, message = "Client could not be authenticated."), + @ApiResponse(code = 403, message = "Client is not authorized to make this request."), + @ApiResponse(code = 404, message = "The specified resource could not be found."), + @ApiResponse(code = 409, message = "The request was valid but NiFi was not in the appropriate state to process it. Retrying the same request later may be successful.") + } + ) public Response deleteLineage( @Context HttpServletRequest httpServletRequest, + @ApiParam( + value = "If the client id is not specified, new one will be generated. This value (whether specified or generated) is included in the response.", + required = false + ) @QueryParam(CLIENT_ID) @DefaultValue(StringUtils.EMPTY) ClientIdParameter clientId, + @ApiParam( + value = "The id of the node where this query exists if clustered.", + required = false + ) @QueryParam("clusterNodeId") String clusterNodeId, + @ApiParam( + value = "The id of the lineage query.", + required = true + ) @PathParam("id") String id) { // replicate if cluster manager http://git-wip-us.apache.org/repos/asf/incubator-nifi/blob/bb956284/nifi/nifi-nar-bundles/nifi-framework-bundle/nifi-framework/nifi-web/nifi-web-api/src/main/java/org/apache/nifi/web/api/RemoteProcessGroupResource.java ---------------------------------------------------------------------- diff --git a/nifi/nifi-nar-bundles/nifi-framework-bundle/nifi-framework/nifi-web/nifi-web-api/src/main/java/org/apache/nifi/web/api/RemoteProcessGroupResource.java b/nifi/nifi-nar-bundles/nifi-framework-bundle/nifi-framework/nifi-web/nifi-web-api/src/main/java/org/apache/nifi/web/api/RemoteProcessGroupResource.java index 0c70c3e..4a040b5 100644 --- a/nifi/nifi-nar-bundles/nifi-framework-bundle/nifi-framework/nifi-web/nifi-web-api/src/main/java/org/apache/nifi/web/api/RemoteProcessGroupResource.java +++ b/nifi/nifi-nar-bundles/nifi-framework-bundle/nifi-framework/nifi-web/nifi-web-api/src/main/java/org/apache/nifi/web/api/RemoteProcessGroupResource.java @@ -17,6 +17,11 @@ package org.apache.nifi.web.api; import com.wordnik.swagger.annotations.Api; +import com.wordnik.swagger.annotations.ApiOperation; +import com.wordnik.swagger.annotations.ApiParam; +import com.wordnik.swagger.annotations.ApiResponse; +import com.wordnik.swagger.annotations.ApiResponses; +import com.wordnik.swagger.annotations.Authorization; import java.net.URI; import java.net.URISyntaxException; import java.util.HashMap; @@ -62,6 +67,7 @@ import org.apache.nifi.web.api.request.DoubleParameter; import org.apache.nifi.web.api.request.IntegerParameter; import org.apache.nifi.web.api.request.LongParameter; import org.apache.commons.lang3.StringUtils; +import org.apache.nifi.web.api.entity.ConnectionsEntity; import org.codehaus.enunciate.jaxrs.TypeHint; import org.slf4j.Logger; import org.slf4j.LoggerFactory; @@ -116,11 +122,39 @@ public class RemoteProcessGroupResource extends ApplicationResource { * @return A remoteProcessGroupEntity. */ @GET + @Consumes(MediaType.WILDCARD) @Produces({MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML}) + @Path("") // necessary due to bug in swagger @PreAuthorize("hasAnyRole('ROLE_MONITOR', 'ROLE_DFM', 'ROLE_ADMIN')") @TypeHint(RemoteProcessGroupsEntity.class) + @ApiOperation( + value = "Gets all remote process groups", + response = ConnectionsEntity.class, + authorizations = { + @Authorization(value = "Read Only", type = "ROLE_MONITOR"), + @Authorization(value = "Data Flow Manager", type = "ROLE_DFM"), + @Authorization(value = "Administrator", type = "ROLE_ADMIN") + } + ) + @ApiResponses( + value = { + @ApiResponse(code = 400, message = "NiFi was unable to complete the request because it was invalid. The request should not be retried without modification."), + @ApiResponse(code = 401, message = "Client could not be authenticated."), + @ApiResponse(code = 403, message = "Client is not authorized to make this request."), + @ApiResponse(code = 404, message = "The specified resource could not be found."), + @ApiResponse(code = 409, message = "The request was valid but NiFi was not in the appropriate state to process it. Retrying the same request later may be successful.") + } + ) public Response getRemoteProcessGroups( + @ApiParam( + value = "If the client id is not specified, new one will be generated. This value (whether specified or generated) is included in the response.", + required = false + ) @QueryParam(CLIENT_ID) @DefaultValue(StringUtils.EMPTY) ClientIdParameter clientId, + @ApiParam( + value = "Whether to include any encapulated ports or just details about the remote process group.", + required = false + ) @QueryParam("verbose") @DefaultValue(VERBOSE_DEFAULT_VALUE) Boolean verbose) { // replicate if cluster manager @@ -160,13 +194,44 @@ public class RemoteProcessGroupResource extends ApplicationResource { * @return A remoteProcessGroupEntity. */ @GET + @Consumes(MediaType.WILDCARD) @Produces({MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML}) @Path("{id}") @PreAuthorize("hasAnyRole('ROLE_MONITOR', 'ROLE_DFM', 'ROLE_ADMIN')") @TypeHint(RemoteProcessGroupEntity.class) + @ApiOperation( + value = "Gets a remote process group", + response = RemoteProcessGroupEntity.class, + authorizations = { + @Authorization(value = "Read Only", type = "ROLE_MONITOR"), + @Authorization(value = "Data Flow Manager", type = "ROLE_DFM"), + @Authorization(value = "Administrator", type = "ROLE_ADMIN") + } + ) + @ApiResponses( + value = { + @ApiResponse(code = 400, message = "NiFi was unable to complete the request because it was invalid. The request should not be retried without modification."), + @ApiResponse(code = 401, message = "Client could not be authenticated."), + @ApiResponse(code = 403, message = "Client is not authorized to make this request."), + @ApiResponse(code = 404, message = "The specified resource could not be found."), + @ApiResponse(code = 409, message = "The request was valid but NiFi was not in the appropriate state to process it. Retrying the same request later may be successful.") + } + ) public Response getRemoteProcessGroup( + @ApiParam( + value = "If the client id is not specified, new one will be generated. This value (whether specified or generated) is included in the response.", + required = false + ) @QueryParam(CLIENT_ID) @DefaultValue(StringUtils.EMPTY) ClientIdParameter clientId, + @ApiParam( + value = "Whether to include any encapulated ports or just details about the remote process group.", + required = false + ) @QueryParam("verbose") @DefaultValue(VERBOSE_DEFAULT_VALUE) Boolean verbose, + @ApiParam( + value = "The remote process group id.", + required = true + ) @PathParam("id") String id) { // replicate if cluster manager @@ -202,11 +267,40 @@ public class RemoteProcessGroupResource extends ApplicationResource { * @return A statusHistoryEntity. */ @GET + @Consumes(MediaType.WILDCARD) @Produces({MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML}) @Path("/{id}/status/history") @PreAuthorize("hasAnyRole('ROLE_MONITOR', 'ROLE_DFM', 'ROLE_ADMIN')") @TypeHint(StatusHistoryEntity.class) - public Response getRemoteProcessGroupStatusHistory(@QueryParam(CLIENT_ID) @DefaultValue(StringUtils.EMPTY) ClientIdParameter clientId, @PathParam("id") String id) { + @ApiOperation( + value = "Gets the status history", + response = StatusHistoryEntity.class, + authorizations = { + @Authorization(value = "Read Only", type = "ROLE_MONITOR"), + @Authorization(value = "Data Flow Manager", type = "ROLE_DFM"), + @Authorization(value = "Administrator", type = "ROLE_ADMIN") + } + ) + @ApiResponses( + value = { + @ApiResponse(code = 400, message = "NiFi was unable to complete the request because it was invalid. The request should not be retried without modification."), + @ApiResponse(code = 401, message = "Client could not be authenticated."), + @ApiResponse(code = 403, message = "Client is not authorized to make this request."), + @ApiResponse(code = 404, message = "The specified resource could not be found."), + @ApiResponse(code = 409, message = "The request was valid but NiFi was not in the appropriate state to process it. Retrying the same request later may be successful.") + } + ) + public Response getRemoteProcessGroupStatusHistory( + @ApiParam( + value = "If the client id is not specified, new one will be generated. This value (whether specified or generated) is included in the response.", + required = false + ) + @QueryParam(CLIENT_ID) @DefaultValue(StringUtils.EMPTY) ClientIdParameter clientId, + @ApiParam( + value = "The remote process group id.", + required = true + ) + @PathParam("id") String id) { // replicate if cluster manager if (properties.isClusterManager()) { @@ -243,6 +337,7 @@ public class RemoteProcessGroupResource extends ApplicationResource { @POST @Consumes(MediaType.APPLICATION_FORM_URLENCODED) @Produces({MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML}) + @Path("") // necessary due to bug in swagger @PreAuthorize("hasRole('ROLE_DFM')") @TypeHint(RemoteProcessGroupEntity.class) public Response createRemoteProcessGroup( @@ -289,11 +384,33 @@ public class RemoteProcessGroupResource extends ApplicationResource { @POST @Consumes({MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML}) @Produces({MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML}) + @Path("") // necessary due to bug in swagger @PreAuthorize("hasRole('ROLE_DFM')") @TypeHint(RemoteProcessGroupEntity.class) + @ApiOperation( + value = "Creates a new process group", + response = RemoteProcessGroupEntity.class, + authorizations = { + @Authorization(value = "Read Only", type = "ROLE_MONITOR"), + @Authorization(value = "Data Flow Manager", type = "ROLE_DFM"), + @Authorization(value = "Administrator", type = "ROLE_ADMIN") + } + ) + @ApiResponses( + value = { + @ApiResponse(code = 400, message = "NiFi was unable to complete the request because it was invalid. The request should not be retried without modification."), + @ApiResponse(code = 401, message = "Client could not be authenticated."), + @ApiResponse(code = 403, message = "Client is not authorized to make this request."), + @ApiResponse(code = 404, message = "The specified resource could not be found."), + @ApiResponse(code = 409, message = "The request was valid but NiFi was not in the appropriate state to process it. Retrying the same request later may be successful.") + } + ) public Response createRemoteProcessGroup( @Context HttpServletRequest httpServletRequest, - RemoteProcessGroupEntity remoteProcessGroupEntity) { + @ApiParam( + value = "The remote process group configuration details.", + required = true + ) RemoteProcessGroupEntity remoteProcessGroupEntity) { if (remoteProcessGroupEntity == null || remoteProcessGroupEntity.getRemoteProcessGroup() == null) { throw new IllegalArgumentException("Remote process group details must be specified."); @@ -402,14 +519,43 @@ public class RemoteProcessGroupResource extends ApplicationResource { * @return A remoteProcessGroupEntity. */ @DELETE + @Consumes(MediaType.WILDCARD) @Produces({MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML}) @Path("/{id}") @PreAuthorize("hasRole('ROLE_DFM')") @TypeHint(RemoteProcessGroupEntity.class) + @ApiOperation( + value = "Deletes a remote process group", + response = RemoteProcessGroupEntity.class, + authorizations = { + @Authorization(value = "Data Flow Manager", type = "ROLE_DFM") + } + ) + @ApiResponses( + value = { + @ApiResponse(code = 400, message = "NiFi was unable to complete the request because it was invalid. The request should not be retried without modification."), + @ApiResponse(code = 401, message = "Client could not be authenticated."), + @ApiResponse(code = 403, message = "Client is not authorized to make this request."), + @ApiResponse(code = 404, message = "The specified resource could not be found."), + @ApiResponse(code = 409, message = "The request was valid but NiFi was not in the appropriate state to process it. Retrying the same request later may be successful.") + } + ) public Response removeRemoteProcessGroup( @Context HttpServletRequest httpServletRequest, + @ApiParam( + value = "The revision is used to verify the client is working with the latest version of the flow.", + required = false + ) @QueryParam(VERSION) LongParameter version, + @ApiParam( + value = "If the client id is not specified, new one will be generated. This value (whether specified or generated) is included in the response.", + required = false + ) @QueryParam(CLIENT_ID) @DefaultValue(StringUtils.EMPTY) ClientIdParameter clientId, + @ApiParam( + value = "The remote process group id.", + required = true + ) @PathParam("id") String id) { // replicate if cluster manager @@ -517,6 +663,22 @@ public class RemoteProcessGroupResource extends ApplicationResource { @Path("/{id}/input-ports/{port-id}") @PreAuthorize("hasRole('ROLE_DFM')") @TypeHint(RemoteProcessGroupPortEntity.class) + @ApiOperation( + value = "Updates a remote port", + response = RemoteProcessGroupPortEntity.class, + authorizations = { + @Authorization(value = "Data Flow Manager", type = "ROLE_DFM") + } + ) + @ApiResponses( + value = { + @ApiResponse(code = 400, message = "NiFi was unable to complete the request because it was invalid. The request should not be retried without modification."), + @ApiResponse(code = 401, message = "Client could not be authenticated."), + @ApiResponse(code = 403, message = "Client is not authorized to make this request."), + @ApiResponse(code = 404, message = "The specified resource could not be found."), + @ApiResponse(code = 409, message = "The request was valid but NiFi was not in the appropriate state to process it. Retrying the same request later may be successful.") + } + ) public Response updateRemoteProcessGroupInputPort( @Context HttpServletRequest httpServletRequest, @PathParam("id") String id, @@ -647,6 +809,22 @@ public class RemoteProcessGroupResource extends ApplicationResource { @Path("/{id}/output-ports/{port-id}") @PreAuthorize("hasRole('ROLE_DFM')") @TypeHint(RemoteProcessGroupPortEntity.class) + @ApiOperation( + value = "Updates a remote port", + response = RemoteProcessGroupPortEntity.class, + authorizations = { + @Authorization(value = "Data Flow Manager", type = "ROLE_DFM") + } + ) + @ApiResponses( + value = { + @ApiResponse(code = 400, message = "NiFi was unable to complete the request because it was invalid. The request should not be retried without modification."), + @ApiResponse(code = 401, message = "Client could not be authenticated."), + @ApiResponse(code = 403, message = "Client is not authorized to make this request."), + @ApiResponse(code = 404, message = "The specified resource could not be found."), + @ApiResponse(code = 409, message = "The request was valid but NiFi was not in the appropriate state to process it. Retrying the same request later may be successful.") + } + ) public Response updateRemoteProcessGroupOutputPort( @Context HttpServletRequest httpServletRequest, @PathParam("id") String id, @@ -780,6 +958,22 @@ public class RemoteProcessGroupResource extends ApplicationResource { @Path("/{id}") @PreAuthorize("hasRole('ROLE_DFM')") @TypeHint(RemoteProcessGroupEntity.class) + @ApiOperation( + value = "Updates a remote process group", + response = RemoteProcessGroupEntity.class, + authorizations = { + @Authorization(value = "Data Flow Manager", type = "ROLE_DFM") + } + ) + @ApiResponses( + value = { + @ApiResponse(code = 400, message = "NiFi was unable to complete the request because it was invalid. The request should not be retried without modification."), + @ApiResponse(code = 401, message = "Client could not be authenticated."), + @ApiResponse(code = 403, message = "Client is not authorized to make this request."), + @ApiResponse(code = 404, message = "The specified resource could not be found."), + @ApiResponse(code = 409, message = "The request was valid but NiFi was not in the appropriate state to process it. Retrying the same request later may be successful.") + } + ) public Response updateRemoteProcessGroup( @Context HttpServletRequest httpServletRequest, @PathParam("id") String id, http://git-wip-us.apache.org/repos/asf/incubator-nifi/blob/bb956284/nifi/nifi-nar-bundles/nifi-framework-bundle/nifi-framework/nifi-web/nifi-web-api/src/main/java/org/apache/nifi/web/api/ReportingTaskResource.java ---------------------------------------------------------------------- diff --git a/nifi/nifi-nar-bundles/nifi-framework-bundle/nifi-framework/nifi-web/nifi-web-api/src/main/java/org/apache/nifi/web/api/ReportingTaskResource.java b/nifi/nifi-nar-bundles/nifi-framework-bundle/nifi-framework/nifi-web/nifi-web-api/src/main/java/org/apache/nifi/web/api/ReportingTaskResource.java index 293b7b3..67a5809 100644 --- a/nifi/nifi-nar-bundles/nifi-framework-bundle/nifi-framework/nifi-web/nifi-web-api/src/main/java/org/apache/nifi/web/api/ReportingTaskResource.java +++ b/nifi/nifi-nar-bundles/nifi-framework-bundle/nifi-framework/nifi-web/nifi-web-api/src/main/java/org/apache/nifi/web/api/ReportingTaskResource.java @@ -17,6 +17,11 @@ package org.apache.nifi.web.api; import com.wordnik.swagger.annotations.Api; +import com.wordnik.swagger.annotations.ApiOperation; +import com.wordnik.swagger.annotations.ApiParam; +import com.wordnik.swagger.annotations.ApiResponse; +import com.wordnik.swagger.annotations.ApiResponses; +import com.wordnik.swagger.annotations.Authorization; import java.net.URI; import java.net.URISyntaxException; import java.util.HashMap; @@ -119,7 +124,8 @@ public class ReportingTaskResource extends ApplicationResource { } /** - * Parses the availability and ensure that the specified availability makes sense for the given NiFi instance. + * Parses the availability and ensure that the specified availability makes + * sense for the given NiFi instance. */ private Availability parseAvailability(final String availability) { final Availability avail; @@ -140,16 +146,50 @@ public class ReportingTaskResource extends ApplicationResource { /** * Retrieves all the of reporting tasks in this NiFi. * - * @param clientId Optional client id. If the client id is not specified, a new one will be generated. This value (whether specified or generated) is included in the response. - * @param availability Whether the reporting task is available on the NCM only (ncm) or on the nodes only (node). If this instance is not clustered all tasks should use the node availability. + * @param clientId Optional client id. If the client id is not specified, a + * new one will be generated. This value (whether specified or generated) is + * included in the response. + * @param availability Whether the reporting task is available on the NCM + * only (ncm) or on the nodes only (node). If this instance is not clustered + * all tasks should use the node availability. * @return A reportingTasksEntity. */ @GET + @Consumes(MediaType.WILDCARD) @Produces({MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML}) @Path("/{availability}") @PreAuthorize("hasAnyRole('ROLE_MONITOR', 'ROLE_DFM', 'ROLE_ADMIN')") @TypeHint(ReportingTasksEntity.class) - public Response getReportingTasks(@QueryParam(CLIENT_ID) @DefaultValue(StringUtils.EMPTY) ClientIdParameter clientId, @PathParam("availability") String availability) { + @ApiOperation( + value = "Gets all reporting tasks", + response = ReportingTasksEntity.class, + authorizations = { + @Authorization(value = "Read Only", type = "ROLE_MONITOR"), + @Authorization(value = "Data Flow Manager", type = "ROLE_DFM"), + @Authorization(value = "Administrator", type = "ROLE_ADMIN") + } + ) + @ApiResponses( + value = { + @ApiResponse(code = 400, message = "NiFi was unable to complete the request because it was invalid. The request should not be retried without modification."), + @ApiResponse(code = 401, message = "Client could not be authenticated."), + @ApiResponse(code = 403, message = "Client is not authorized to make this request."), + @ApiResponse(code = 409, message = "The request was valid but NiFi was not in the appropriate state to process it. Retrying the same request later may be successful.") + } + ) + public Response getReportingTasks( + @ApiParam( + value = "If the client id is not specified, new one will be generated. This value (whether specified or generated) is included in the response.", + required = false + ) + @QueryParam(CLIENT_ID) @DefaultValue(StringUtils.EMPTY) ClientIdParameter clientId, + @ApiParam( + value = "Whether the reporting task is available on the NCM or nodes. If the NiFi is standalone the availability should be NODE.", + allowableValues = "NCM, NODE", + required = true + ) + @PathParam("availability") String availability) { + final Availability avail = parseAvailability(availability); // replicate if cluster manager @@ -177,9 +217,14 @@ public class ReportingTaskResource extends ApplicationResource { * Creates a new reporting task. * * @param httpServletRequest request - * @param version The revision is used to verify the client is working with the latest version of the flow. - * @param clientId Optional client id. If the client id is not specified, a new one will be generated. This value (whether specified or generated) is included in the response. - * @param availability Whether the reporting task is available on the NCM only (ncm) or on the nodes only (node). If this instance is not clustered all tasks should use the node availability. + * @param version The revision is used to verify the client is working with + * the latest version of the flow. + * @param clientId Optional client id. If the client id is not specified, a + * new one will be generated. This value (whether specified or generated) is + * included in the response. + * @param availability Whether the reporting task is available on the NCM + * only (ncm) or on the nodes only (node). If this instance is not clustered + * all tasks should use the node availability. * @param type The type of reporting task to create. * @return A reportingTaskEntity. */ @@ -219,7 +264,9 @@ public class ReportingTaskResource extends ApplicationResource { * Creates a new Reporting Task. * * @param httpServletRequest request - * @param availability Whether the reporting task is available on the NCM only (ncm) or on the nodes only (node). If this instance is not clustered all tasks should use the node availability. + * @param availability Whether the reporting task is available on the NCM + * only (ncm) or on the nodes only (node). If this instance is not clustered + * all tasks should use the node availability. * @param reportingTaskEntity A reportingTaskEntity. * @return A reportingTaskEntity. */ @@ -229,10 +276,33 @@ public class ReportingTaskResource extends ApplicationResource { @Path("/{availability}") @PreAuthorize("hasRole('ROLE_DFM')") @TypeHint(ReportingTaskEntity.class) + @ApiOperation( + value = "Creates a new remote process group", + response = ReportingTaskEntity.class, + authorizations = { + @Authorization(value = "Data Flow Manager", type = "ROLE_DFM") + } + ) + @ApiResponses( + value = { + @ApiResponse(code = 400, message = "NiFi was unable to complete the request because it was invalid. The request should not be retried without modification."), + @ApiResponse(code = 401, message = "Client could not be authenticated."), + @ApiResponse(code = 403, message = "Client is not authorized to make this request."), + @ApiResponse(code = 409, message = "The request was valid but NiFi was not in the appropriate state to process it. Retrying the same request later may be successful.") + } + ) public Response createReportingTask( @Context HttpServletRequest httpServletRequest, + @ApiParam( + value = "Whether the reporting task is available on the NCM or nodes. If the NiFi is standalone the availability should be NODE.", + allowableValues = "NCM, NODE", + required = true + ) @PathParam("availability") String availability, - ReportingTaskEntity reportingTaskEntity) { + @ApiParam( + value = "The reporting task configuration details.", + required = true + ) ReportingTaskEntity reportingTaskEntity) { final Availability avail = parseAvailability(availability); @@ -307,18 +377,56 @@ public class ReportingTaskResource extends ApplicationResource { /** * Retrieves the specified reporting task. * - * @param clientId Optional client id. If the client id is not specified, a new one will be generated. This value (whether specified or generated) is included in the response. - * @param availability Whether the reporting task is available on the NCM only (ncm) or on the nodes only (node). If this instance is not clustered all tasks should use the node availability. + * @param clientId Optional client id. If the client id is not specified, a + * new one will be generated. This value (whether specified or generated) is + * included in the response. + * @param availability Whether the reporting task is available on the NCM + * only (ncm) or on the nodes only (node). If this instance is not clustered + * all tasks should use the node availability. * @param id The id of the reporting task to retrieve * @return A reportingTaskEntity. */ @GET + @Consumes(MediaType.WILDCARD) @Produces({MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML}) @Path("/{availability}/{id}") @PreAuthorize("hasAnyRole('ROLE_MONITOR', 'ROLE_DFM', 'ROLE_ADMIN')") @TypeHint(ReportingTaskEntity.class) - public Response getReportingTask(@QueryParam(CLIENT_ID) @DefaultValue(StringUtils.EMPTY) ClientIdParameter clientId, - @PathParam("availability") String availability, @PathParam("id") String id) { + @ApiOperation( + value = "Gets a reporting task", + response = ReportingTaskEntity.class, + authorizations = { + @Authorization(value = "Read Only", type = "ROLE_MONITOR"), + @Authorization(value = "Data Flow Manager", type = "ROLE_DFM"), + @Authorization(value = "Administrator", type = "ROLE_ADMIN") + } + ) + @ApiResponses( + value = { + @ApiResponse(code = 400, message = "NiFi was unable to complete the request because it was invalid. The request should not be retried without modification."), + @ApiResponse(code = 401, message = "Client could not be authenticated."), + @ApiResponse(code = 403, message = "Client is not authorized to make this request."), + @ApiResponse(code = 404, message = "The specified resource could not be found."), + @ApiResponse(code = 409, message = "The request was valid but NiFi was not in the appropriate state to process it. Retrying the same request later may be successful.") + } + ) + public Response getReportingTask( + @ApiParam( + value = "If the client id is not specified, new one will be generated. This value (whether specified or generated) is included in the response.", + required = false + ) + @QueryParam(CLIENT_ID) @DefaultValue(StringUtils.EMPTY) ClientIdParameter clientId, + @ApiParam( + value = "Whether the reporting task is available on the NCM or nodes. If the NiFi is standalone the availability should be NODE.", + allowableValues = "NCM, NODE", + required = true + ) + @PathParam("availability") String availability, + @ApiParam( + value = "The reporting task id.", + required = true + ) + @PathParam("id") String id) { final Availability avail = parseAvailability(availability); @@ -345,20 +453,59 @@ public class ReportingTaskResource extends ApplicationResource { /** * Returns the descriptor for the specified property. * - * @param clientId Optional client id. If the client id is not specified, a new one will be generated. This value (whether specified or generated) is included in the response. + * @param clientId Optional client id. If the client id is not specified, a + * new one will be generated. This value (whether specified or generated) is + * included in the response. * @param availability availability * @param id The id of the reporting task. * @param propertyName The property * @return a propertyDescriptorEntity */ @GET + @Consumes(MediaType.WILDCARD) @Produces({MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML}) @Path("/{availability}/{id}/descriptors") @PreAuthorize("hasAnyRole('ROLE_MONITOR', 'ROLE_DFM', 'ROLE_ADMIN')") @TypeHint(PropertyDescriptorEntity.class) + @ApiOperation( + value = "Gets a reporting task property descriptor", + response = PropertyDescriptorEntity.class, + authorizations = { + @Authorization(value = "Read Only", type = "ROLE_MONITOR"), + @Authorization(value = "Data Flow Manager", type = "ROLE_DFM"), + @Authorization(value = "Administrator", type = "ROLE_ADMIN") + } + ) + @ApiResponses( + value = { + @ApiResponse(code = 400, message = "NiFi was unable to complete the request because it was invalid. The request should not be retried without modification."), + @ApiResponse(code = 401, message = "Client could not be authenticated."), + @ApiResponse(code = 403, message = "Client is not authorized to make this request."), + @ApiResponse(code = 404, message = "The specified resource could not be found."), + @ApiResponse(code = 409, message = "The request was valid but NiFi was not in the appropriate state to process it. Retrying the same request later may be successful.") + } + ) public Response getPropertyDescriptor( + @ApiParam( + value = "If the client id is not specified, new one will be generated. This value (whether specified or generated) is included in the response.", + required = false + ) @QueryParam(CLIENT_ID) @DefaultValue(StringUtils.EMPTY) ClientIdParameter clientId, - @PathParam("availability") String availability, @PathParam("id") String id, + @ApiParam( + value = "Whether the reporting task is available on the NCM or nodes. If the NiFi is standalone the availability should be NODE.", + allowableValues = "NCM, NODE", + required = true + ) + @PathParam("availability") String availability, + @ApiParam( + value = "The reporting task id.", + required = true + ) + @PathParam("id") String id, + @ApiParam( + value = "The property name.", + required = true + ) @QueryParam("propertyName") String propertyName) { final Availability avail = parseAvailability(availability); @@ -393,19 +540,27 @@ public class ReportingTaskResource extends ApplicationResource { * Updates the specified reporting task. * * @param httpServletRequest request - * @param version The revision is used to verify the client is working with the latest version of the flow. - * @param clientId Optional client id. If the client id is not specified, a new one will be generated. This value (whether specified or generated) is included in the response. - * @param availability Whether the reporting task is available on the NCM only (ncm) or on the nodes only (node). If this instance is not clustered all tasks should use the node availability. + * @param version The revision is used to verify the client is working with + * the latest version of the flow. + * @param clientId Optional client id. If the client id is not specified, a + * new one will be generated. This value (whether specified or generated) is + * included in the response. + * @param availability Whether the reporting task is available on the NCM + * only (ncm) or on the nodes only (node). If this instance is not clustered + * all tasks should use the node availability. * @param id The id of the reporting task to update. * @param name The name of the reporting task * @param annotationData The annotation data for the reporting task - * @param markedForDeletion Array of property names whose value should be removed. + * @param markedForDeletion Array of property names whose value should be + * removed. * @param state The updated scheduled state * @param schedulingStrategy The scheduling strategy for this reporting task * @param schedulingPeriod The scheduling period for this reporting task * @param comments The comments for this reporting task - * @param formParams Additionally, the processor properties and styles are specified in the form parameters. Because the property names and styles differ from processor to processor they are - * specified in a map-like fashion: + * @param formParams Additionally, the processor properties and styles are + * specified in the form parameters. Because the property names and styles + * differ from processor to processor they are specified in a map-like + * fashion: * <br> * <ul> * <li>properties[required.file.path]=/path/to/file</li> @@ -493,7 +648,9 @@ public class ReportingTaskResource extends ApplicationResource { * Updates the specified a Reporting Task. * * @param httpServletRequest request - * @param availability Whether the reporting task is available on the NCM only (ncm) or on the nodes only (node). If this instance is not clustered all tasks should use the node availability. + * @param availability Whether the reporting task is available on the NCM + * only (ncm) or on the nodes only (node). If this instance is not clustered + * all tasks should use the node availability. * @param id The id of the reporting task to update. * @param reportingTaskEntity A reportingTaskEntity. * @return A reportingTaskEntity. @@ -504,11 +661,39 @@ public class ReportingTaskResource extends ApplicationResource { @Path("/{availability}/{id}") @PreAuthorize("hasRole('ROLE_DFM')") @TypeHint(ReportingTaskEntity.class) + @ApiOperation( + value = "Updates a reporting task", + response = ReportingTaskEntity.class, + authorizations = { + @Authorization(value = "Data Flow Manager", type = "ROLE_DFM") + } + ) + @ApiResponses( + value = { + @ApiResponse(code = 400, message = "NiFi was unable to complete the request because it was invalid. The request should not be retried without modification."), + @ApiResponse(code = 401, message = "Client could not be authenticated."), + @ApiResponse(code = 403, message = "Client is not authorized to make this request."), + @ApiResponse(code = 404, message = "The specified resource could not be found."), + @ApiResponse(code = 409, message = "The request was valid but NiFi was not in the appropriate state to process it. Retrying the same request later may be successful.") + } + ) public Response updateReportingTask( @Context HttpServletRequest httpServletRequest, + @ApiParam( + value = "Whether the reporting task is available on the NCM or nodes. If the NiFi is standalone the availability should be NODE.", + allowableValues = "NCM, NODE", + required = true + ) @PathParam("availability") String availability, + @ApiParam( + value = "The reporting task id.", + required = true + ) @PathParam("id") String id, - ReportingTaskEntity reportingTaskEntity) { + @ApiParam( + value = "The reporting task configuration details.", + required = true + ) ReportingTaskEntity reportingTaskEntity) { final Availability avail = parseAvailability(availability); @@ -569,22 +754,62 @@ public class ReportingTaskResource extends ApplicationResource { * Removes the specified reporting task. * * @param httpServletRequest request - * @param version The revision is used to verify the client is working with the latest version of the flow. - * @param clientId Optional client id. If the client id is not specified, a new one will be generated. This value (whether specified or generated) is included in the response. - * @param availability Whether the reporting task is available on the NCM only (ncm) or on the nodes only (node). If this instance is not clustered all tasks should use the node availability. + * @param version The revision is used to verify the client is working with + * the latest version of the flow. + * @param clientId Optional client id. If the client id is not specified, a + * new one will be generated. This value (whether specified or generated) is + * included in the response. + * @param availability Whether the reporting task is available on the NCM + * only (ncm) or on the nodes only (node). If this instance is not clustered + * all tasks should use the node availability. * @param id The id of the reporting task to remove. * @return A entity containing the client id and an updated revision. */ @DELETE + @Consumes(MediaType.WILDCARD) @Produces({MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML}) @Path("/{availability}/{id}") @PreAuthorize("hasRole('ROLE_DFM')") @TypeHint(ReportingTaskEntity.class) + @ApiOperation( + value = "Deletes a reporting task", + response = ReportingTaskEntity.class, + authorizations = { + @Authorization(value = "Data Flow Manager", type = "ROLE_DFM") + } + ) + @ApiResponses( + value = { + @ApiResponse(code = 400, message = "NiFi was unable to complete the request because it was invalid. The request should not be retried without modification."), + @ApiResponse(code = 401, message = "Client could not be authenticated."), + @ApiResponse(code = 403, message = "Client is not authorized to make this request."), + @ApiResponse(code = 404, message = "The specified resource could not be found."), + @ApiResponse(code = 409, message = "The request was valid but NiFi was not in the appropriate state to process it. Retrying the same request later may be successful.") + } + ) public Response removeReportingTask( @Context HttpServletRequest httpServletRequest, + @ApiParam( + value = "The revision is used to verify the client is working with the latest version of the flow.", + required = false + ) @QueryParam(VERSION) LongParameter version, + @ApiParam( + value = "If the client id is not specified, new one will be generated. This value (whether specified or generated) is included in the response.", + required = false + ) @QueryParam(CLIENT_ID) @DefaultValue(StringUtils.EMPTY) ClientIdParameter clientId, - @PathParam("availability") String availability, @PathParam("id") String id) { + @ApiParam( + value = "Whether the reporting task is available on the NCM or nodes. If the NiFi is standalone the availability should be NODE.", + allowableValues = "NCM, NODE", + required = true + ) + @PathParam("availability") String availability, + @ApiParam( + value = "The reporting task id.", + required = true + ) + @PathParam("id") String id) { final Availability avail = parseAvailability(availability);
