http://git-wip-us.apache.org/repos/asf/incubator-nifi/blob/997ed946/nifi/nifi-nar-bundles/nifi-framework-bundle/nifi-framework/nifi-web/nifi-web-api/src/main/java/org/apache/nifi/web/api/ClusterResource.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/ClusterResource.java b/nifi/nifi-nar-bundles/nifi-framework-bundle/nifi-framework/nifi-web/nifi-web-api/src/main/java/org/apache/nifi/web/api/ClusterResource.java index b080fc6..857df56 100644 --- a/nifi/nifi-nar-bundles/nifi-framework-bundle/nifi-framework/nifi-web/nifi-web-api/src/main/java/org/apache/nifi/web/api/ClusterResource.java +++ b/nifi/nifi-nar-bundles/nifi-framework-bundle/nifi-framework/nifi-web/nifi-web-api/src/main/java/org/apache/nifi/web/api/ClusterResource.java @@ -69,14 +69,23 @@ import org.apache.commons.lang3.StringUtils; import org.springframework.security.access.prepost.PreAuthorize; import com.sun.jersey.api.core.ResourceContext; +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 org.apache.nifi.web.api.dto.status.ClusterProcessGroupStatusDTO; import org.apache.nifi.web.api.entity.ClusterProcessGroupStatusEntity; -import org.codehaus.enunciate.jaxrs.TypeHint; /** * RESTful endpoint for managing a cluster. */ @Path("/cluster") +@Api( + value = "/cluster", + description = "Provides access to the cluster of Nodes that comprise this NiFi" +) public class ClusterResource extends ApplicationResource { @Context @@ -90,6 +99,10 @@ public class ClusterResource extends ApplicationResource { * @return node resource */ @Path("/nodes") + @ApiOperation( + value = "Gets the node resource", + response = NodeResource.class + ) public NodeResource getNodeResource() { return resourceContext.getResource(NodeResource.class); } @@ -101,11 +114,33 @@ public class ClusterResource extends ApplicationResource { * @return A clusterStatusEntity */ @GET + @Consumes(MediaType.WILDCARD) @Produces({MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML}) @Path("/status") @PreAuthorize("hasAnyRole('ROLE_MONITOR', 'ROLE_DFM', 'ROLE_ADMIN')") - @TypeHint(ClusterStatusEntity.class) - public Response getClusterStatus(@QueryParam(CLIENT_ID) @DefaultValue(StringUtils.EMPTY) ClientIdParameter clientId) { + @ApiOperation( + value = "Gets the status of the cluster", + response = ClusterStatusEntity.class, + authorizations = { + @Authorization(value = "Read Only", type = "ROLE_MONITOR"), + @Authorization(value = "DFM", type = "ROLE_DFM"), + @Authorization(value = "Admin", 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 getClusterStatus( + @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) { if (properties.isClusterManager()) { @@ -134,7 +169,8 @@ public class ClusterResource extends ApplicationResource { * @return An OK response with an empty entity body. */ @HEAD - @Produces({MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML}) + @Consumes(MediaType.WILDCARD) + @Produces({MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON}) public Response getClusterHead() { if (properties.isClusterManager()) { return Response.ok().build(); @@ -150,10 +186,33 @@ public class ClusterResource extends ApplicationResource { * @return A clusterEntity */ @GET - @Produces({MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML}) + @Consumes(MediaType.WILDCARD) + @Produces({MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON}) @PreAuthorize("hasAnyRole('ROLE_MONITOR', 'ROLE_DFM', 'ROLE_ADMIN')") - @TypeHint(ClusterEntity.class) - public Response getCluster(@QueryParam(CLIENT_ID) @DefaultValue(StringUtils.EMPTY) ClientIdParameter clientId) { + @ApiOperation( + value = "Gets the contents of the cluster", + notes = "Returns the contents of the cluster including all nodes and their status.", + response = ClusterEntity.class, + authorizations = { + @Authorization(value = "Read Only", type = "ROLE_MONITOR"), + @Authorization(value = "DFM", type = "ROLE_DFM"), + @Authorization(value = "Admin", 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 getCluster( + @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) { if (properties.isClusterManager()) { @@ -182,11 +241,34 @@ public class ClusterResource extends ApplicationResource { * @return Nodes that match the specified criteria */ @GET - @Produces({MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML}) + @Consumes(MediaType.WILDCARD) + @Produces({MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON}) @Path("/search-results") @PreAuthorize("hasAnyRole('ROLE_MONITOR', 'ROLE_DFM', 'ROLE_ADMIN')") - @TypeHint(ClusterSearchResultsEntity.class) - public Response searchCluster(@QueryParam("q") @DefaultValue(StringUtils.EMPTY) String value) { + @ApiOperation( + value = "Searches the cluster for a node with the specified address", + response = ClusterSearchResultsEntity.class, + authorizations = { + @Authorization(value = "Read Only", type = "ROLE_MONITOR"), + @Authorization(value = "DFM", type = "ROLE_DFM"), + @Authorization(value = "Admin", 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 searchCluster( + @ApiParam( + value = "Node address to search for.", + required = true + ) + @QueryParam("q") @DefaultValue(StringUtils.EMPTY) String value) { // ensure this is the cluster manager if (properties.isClusterManager()) { @@ -233,11 +315,40 @@ public class ClusterResource extends ApplicationResource { * @return A processorEntity */ @GET - @Produces({MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML}) + @Consumes(MediaType.WILDCARD) + @Produces({MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON}) @Path("/processors/{id}") @PreAuthorize("hasAnyRole('ROLE_MONITOR', 'ROLE_DFM', 'ROLE_ADMIN')") - @TypeHint(ProcessorEntity.class) - public Response getProcessor(@QueryParam(CLIENT_ID) @DefaultValue(StringUtils.EMPTY) ClientIdParameter clientId, @PathParam("id") String id) { + @ApiOperation( + value = "Gets the specified processor", + response = ProcessorEntity.class, + authorizations = { + @Authorization(value = "Read Only", type = "ROLE_MONITOR"), + @Authorization(value = "DFM", type = "ROLE_DFM"), + @Authorization(value = "Admin", 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 getProcessor( + @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 processor id.", + required = true + ) + @PathParam("id") String id) { + if (!properties.isClusterManager()) { final ProcessorDTO dto = serviceFacade.getProcessor(id); @@ -270,10 +381,9 @@ public class ClusterResource extends ApplicationResource { */ @PUT @Consumes(MediaType.APPLICATION_FORM_URLENCODED) - @Produces({MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML}) + @Produces({MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON}) @Path("/processors/{id}") @PreAuthorize("hasAnyRole('ROLE_DFM')") - @TypeHint(ProcessorEntity.class) public Response updateProcessor( @Context HttpServletRequest httpServletRequest, @FormParam(VERSION) LongParameter version, @@ -321,13 +431,38 @@ public class ClusterResource extends ApplicationResource { */ @PUT @Consumes({MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML}) - @Produces({MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML}) + @Produces({MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON}) @Path("/processors/{id}") @PreAuthorize("hasAnyRole('ROLE_DFM')") - @TypeHint(ProcessorEntity.class) + @ApiOperation( + value = "Updates processor annotation data", + response = ProcessorEntity.class, + authorizations = { + @Authorization(value = "Read Only", type = "ROLE_MONITOR"), + @Authorization(value = "DFM", type = "ROLE_DFM"), + @Authorization(value = "Admin", 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 updateProcessor( @Context HttpServletRequest httpServletRequest, + @ApiParam( + value = "The processor id.", + required = true + ) @PathParam("id") final String processorId, + @ApiParam( + value = "The processor configuration details. The only configuration that will be honored at this endpoint is the processor annontation data.", + required = true + ) final ProcessorEntity processorEntity) { if (!properties.isClusterManager()) { @@ -392,11 +527,39 @@ public class ClusterResource extends ApplicationResource { * @return A clusterProcessorStatusEntity */ @GET - @Produces({MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML}) + @Consumes(MediaType.WILDCARD) + @Produces({MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON}) @Path("/processors/{id}/status") @PreAuthorize("hasAnyRole('ROLE_MONITOR', 'ROLE_DFM', 'ROLE_ADMIN')") - @TypeHint(ClusterProcessorStatusEntity.class) - public Response getProcessorStatus(@QueryParam(CLIENT_ID) @DefaultValue(StringUtils.EMPTY) ClientIdParameter clientId, @PathParam("id") String id) { + @ApiOperation( + value = "Gets the processor status across the cluster", + response = ClusterProcessorStatusEntity.class, + authorizations = { + @Authorization(value = "Read Only", type = "ROLE_MONITOR"), + @Authorization(value = "DFM", type = "ROLE_DFM"), + @Authorization(value = "Admin", 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 getProcessorStatus( + @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 processor id", + required = true + ) + @PathParam("id") String id) { if (properties.isClusterManager()) { @@ -426,11 +589,39 @@ public class ClusterResource extends ApplicationResource { * @return A clusterProcessorStatusHistoryEntity */ @GET - @Produces({MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML}) + @Consumes(MediaType.WILDCARD) + @Produces({MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON}) @Path("/processors/{id}/status/history") @PreAuthorize("hasAnyRole('ROLE_MONITOR', 'ROLE_DFM', 'ROLE_ADMIN')") - @TypeHint(ClusterStatusHistoryEntity.class) - public Response getProcessorStatusHistory(@QueryParam(CLIENT_ID) @DefaultValue(StringUtils.EMPTY) ClientIdParameter clientId, @PathParam("id") String id) { + @ApiOperation( + value = "Gets processor status history across the cluster", + response = ClusterStatusHistoryEntity.class, + authorizations = { + @Authorization(value = "Read Only", type = "ROLE_MONITOR"), + @Authorization(value = "DFM", type = "ROLE_DFM"), + @Authorization(value = "Admin", 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 getProcessorStatusHistory( + @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 processor id", + required = true + ) + @PathParam("id") String id) { if (properties.isClusterManager()) { final ClusterStatusHistoryDTO dto = serviceFacade.getClusterProcessorStatusHistory(id); @@ -459,11 +650,39 @@ public class ClusterResource extends ApplicationResource { * @return A clusterProcessorStatusEntity */ @GET - @Produces({MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML}) + @Consumes(MediaType.WILDCARD) + @Produces({MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON}) @Path("/connections/{id}/status") @PreAuthorize("hasAnyRole('ROLE_MONITOR', 'ROLE_DFM', 'ROLE_ADMIN')") - @TypeHint(ClusterConnectionStatusEntity.class) - public Response getConnectionStatus(@QueryParam(CLIENT_ID) @DefaultValue(StringUtils.EMPTY) ClientIdParameter clientId, @PathParam("id") String id) { + @ApiOperation( + value = "Gets connection status across the cluster", + response = ClusterConnectionStatusEntity.class, + authorizations = { + @Authorization(value = "Read Only", type = "ROLE_MONITOR"), + @Authorization(value = "DFM", type = "ROLE_DFM"), + @Authorization(value = "Admin", 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 getConnectionStatus( + @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 connection id", + required = true + ) + @PathParam("id") String id) { if (properties.isClusterManager()) { @@ -493,11 +712,39 @@ public class ClusterResource extends ApplicationResource { * @return A clusterProcessorStatusHistoryEntity */ @GET - @Produces({MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML}) + @Consumes(MediaType.WILDCARD) + @Produces({MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON}) @Path("/connections/{id}/status/history") @PreAuthorize("hasAnyRole('ROLE_MONITOR', 'ROLE_DFM', 'ROLE_ADMIN')") - @TypeHint(ClusterStatusHistoryEntity.class) - public Response getConnectionStatusHistory(@QueryParam(CLIENT_ID) @DefaultValue(StringUtils.EMPTY) ClientIdParameter clientId, @PathParam("id") String id) { + @ApiOperation( + value = "Gets connection status history across the cluster", + response = ClusterStatusHistoryEntity.class, + authorizations = { + @Authorization(value = "Read Only", type = "ROLE_MONITOR"), + @Authorization(value = "DFM", type = "ROLE_DFM"), + @Authorization(value = "Admin", 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 getConnectionStatusHistory( + @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 connection id.", + required = true + ) + @PathParam("id") String id) { if (properties.isClusterManager()) { final ClusterStatusHistoryDTO dto = serviceFacade.getClusterConnectionStatusHistory(id); @@ -526,11 +773,39 @@ public class ClusterResource extends ApplicationResource { * @return A clusterProcessGroupStatusEntity */ @GET - @Produces({MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML}) + @Consumes(MediaType.WILDCARD) + @Produces({MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON}) @Path("/process-groups/{id}/status") @PreAuthorize("hasAnyRole('ROLE_MONITOR', 'ROLE_DFM', 'ROLE_ADMIN')") - @TypeHint(ClusterConnectionStatusEntity.class) - public Response getProcessGroupStatus(@QueryParam(CLIENT_ID) @DefaultValue(StringUtils.EMPTY) ClientIdParameter clientId, @PathParam("id") String id) { + @ApiOperation( + value = "Gets process group status across the cluster", + response = ClusterProcessGroupStatusEntity.class, + authorizations = { + @Authorization(value = "Read Only", type = "ROLE_MONITOR"), + @Authorization(value = "DFM", type = "ROLE_DFM"), + @Authorization(value = "Admin", 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 getProcessGroupStatus( + @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 process group id.", + required = true + ) + @PathParam("id") String id) { if (properties.isClusterManager()) { @@ -560,11 +835,39 @@ public class ClusterResource extends ApplicationResource { * @return A clusterProcessGroupStatusHistoryEntity */ @GET - @Produces({MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML}) + @Consumes(MediaType.WILDCARD) + @Produces({MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON}) @Path("/process-groups/{id}/status/history") @PreAuthorize("hasAnyRole('ROLE_MONITOR', 'ROLE_DFM', 'ROLE_ADMIN')") - @TypeHint(ClusterStatusHistoryEntity.class) - public Response getProcessGroupStatusHistory(@QueryParam(CLIENT_ID) @DefaultValue(StringUtils.EMPTY) ClientIdParameter clientId, @PathParam("id") String id) { + @ApiOperation( + value = "Gets process group status history across the cluster", + response = ClusterStatusHistoryEntity.class, + authorizations = { + @Authorization(value = "Read Only", type = "ROLE_MONITOR"), + @Authorization(value = "DFM", type = "ROLE_DFM"), + @Authorization(value = "Admin", 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 getProcessGroupStatusHistory( + @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 process group id.", + required = true + ) + @PathParam("id") String id) { if (properties.isClusterManager()) { final ClusterStatusHistoryDTO dto = serviceFacade.getClusterProcessGroupStatusHistory(id); @@ -593,11 +896,39 @@ public class ClusterResource extends ApplicationResource { * @return A clusterRemoteProcessGroupStatusEntity */ @GET - @Produces({MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML}) + @Consumes(MediaType.WILDCARD) + @Produces({MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON}) @Path("/remote-process-groups/{id}/status") @PreAuthorize("hasAnyRole('ROLE_MONITOR', 'ROLE_DFM', 'ROLE_ADMIN')") - @TypeHint(ClusterRemoteProcessGroupStatusEntity.class) - public Response getRemoteProcessGroupStatus(@QueryParam(CLIENT_ID) @DefaultValue(StringUtils.EMPTY) ClientIdParameter clientId, @PathParam("id") String id) { + @ApiOperation( + value = "Gets remote process group status across the cluster", + response = ClusterRemoteProcessGroupStatusEntity.class, + authorizations = { + @Authorization(value = "Read Only", type = "ROLE_MONITOR"), + @Authorization(value = "DFM", type = "ROLE_DFM"), + @Authorization(value = "Admin", 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 getRemoteProcessGroupStatus( + @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) { if (properties.isClusterManager()) { @@ -627,11 +958,39 @@ public class ClusterResource extends ApplicationResource { * @return A clusterPortStatusEntity */ @GET - @Produces({MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML}) + @Consumes(MediaType.WILDCARD) + @Produces({MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON}) @Path("/input-ports/{id}/status") @PreAuthorize("hasAnyRole('ROLE_MONITOR', 'ROLE_DFM', 'ROLE_ADMIN')") - @TypeHint(ClusterPortStatusEntity.class) - public Response getInputPortStatus(@QueryParam(CLIENT_ID) @DefaultValue(StringUtils.EMPTY) ClientIdParameter clientId, @PathParam("id") String id) { + @ApiOperation( + value = "Gets input port status across the cluster", + response = ClusterPortStatusEntity.class, + authorizations = { + @Authorization(value = "Read Only", type = "ROLE_MONITOR"), + @Authorization(value = "DFM", type = "ROLE_DFM"), + @Authorization(value = "Admin", 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 getInputPortStatus( + @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 input port id.", + required = true + ) + @PathParam("id") String id) { if (properties.isClusterManager()) { @@ -661,11 +1020,39 @@ public class ClusterResource extends ApplicationResource { * @return A clusterPortStatusEntity */ @GET - @Produces({MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML}) + @Consumes(MediaType.WILDCARD) + @Produces({MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON}) @Path("/output-ports/{id}/status") @PreAuthorize("hasAnyRole('ROLE_MONITOR', 'ROLE_DFM', 'ROLE_ADMIN')") - @TypeHint(ClusterPortStatusEntity.class) - public Response getOutputPortStatus(@QueryParam(CLIENT_ID) @DefaultValue(StringUtils.EMPTY) ClientIdParameter clientId, @PathParam("id") String id) { + @ApiOperation( + value = "Gets output port status across the cluster", + response = ClusterPortStatusEntity.class, + authorizations = { + @Authorization(value = "Read Only", type = "ROLE_MONITOR"), + @Authorization(value = "DFM", type = "ROLE_DFM"), + @Authorization(value = "Admin", 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 getOutputPortStatus( + @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 output port id.", + required = true + ) + @PathParam("id") String id) { if (properties.isClusterManager()) { @@ -695,11 +1082,39 @@ public class ClusterResource extends ApplicationResource { * @return A clusterRemoteProcessGroupStatusHistoryEntity */ @GET - @Produces({MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML}) + @Consumes(MediaType.WILDCARD) + @Produces({MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON}) @Path("/remote-process-groups/{id}/status/history") @PreAuthorize("hasAnyRole('ROLE_MONITOR', 'ROLE_DFM', 'ROLE_ADMIN')") - @TypeHint(ClusterStatusHistoryEntity.class) - public Response getRemoteProcessGroupStatusHistory(@QueryParam(CLIENT_ID) @DefaultValue(StringUtils.EMPTY) ClientIdParameter clientId, @PathParam("id") String id) { + @ApiOperation( + value = "Gets the remote process group status history across the cluster", + response = ClusterStatusHistoryEntity.class, + authorizations = { + @Authorization(value = "Read Only", type = "ROLE_MONITOR"), + @Authorization(value = "DFM", type = "ROLE_DFM"), + @Authorization(value = "Admin", 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) { if (properties.isClusterManager()) { final ClusterStatusHistoryDTO dto = serviceFacade.getClusterRemoteProcessGroupStatusHistory(id);
http://git-wip-us.apache.org/repos/asf/incubator-nifi/blob/997ed946/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 137cc07..93fde8f 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 @@ -16,6 +16,12 @@ */ 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.ArrayList; @@ -65,7 +71,6 @@ import org.apache.nifi.web.api.request.IntegerParameter; import org.apache.nifi.web.api.request.LongParameter; import org.apache.commons.lang3.StringUtils; -import org.codehaus.enunciate.jaxrs.TypeHint; import org.slf4j.Logger; import org.slf4j.LoggerFactory; import org.springframework.security.access.prepost.PreAuthorize; @@ -73,6 +78,7 @@ import org.springframework.security.access.prepost.PreAuthorize; /** * RESTful endpoint for managing a Connection. */ +@Api(hidden = true) public class ConnectionResource extends ApplicationResource { private static final Logger logger = LoggerFactory.getLogger(ConnectionResource.class); @@ -111,10 +117,34 @@ public class ConnectionResource extends ApplicationResource { * @return A connectionsEntity. */ @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(ConnectionsEntity.class) - public Response getConnections(@QueryParam(CLIENT_ID) @DefaultValue(StringUtils.EMPTY) ClientIdParameter clientId) { + @ApiOperation( + value = "Gets all connections", + 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 getConnections( + @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()) { @@ -145,11 +175,38 @@ public class ConnectionResource extends ApplicationResource { * @return A connectionEntity. */ @GET + @Consumes(MediaType.WILDCARD) @Produces({MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML}) @Path("/{id}") @PreAuthorize("hasAnyRole('ROLE_MONITOR', 'ROLE_DFM', 'ROLE_ADMIN')") - @TypeHint(ConnectionEntity.class) - public Response getConnection(@QueryParam(CLIENT_ID) @DefaultValue(StringUtils.EMPTY) ClientIdParameter clientId, + @ApiOperation( + value = "Gets a connection", + response = ConnectionEntity.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 getConnection( + @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 connection id.", + required = true + ) @PathParam("id") String id) { // replicate if cluster manager @@ -181,11 +238,39 @@ public class ConnectionResource 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 getConnectionStatusHistory(@QueryParam(CLIENT_ID) @DefaultValue(StringUtils.EMPTY) ClientIdParameter clientId, @PathParam("id") String id) { + @ApiOperation( + value = "Gets the status history for a connection", + 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 getConnectionStatusHistory( + @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 connection id.", + required = true + ) + @PathParam("id") String id) { // replicate if cluster manager if (properties.isClusterManager()) { @@ -234,8 +319,8 @@ public class ConnectionResource 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(ConnectionEntity.class) public Response createConnection( @Context HttpServletRequest httpServletRequest, @FormParam(VERSION) LongParameter version, @@ -368,10 +453,30 @@ public class ConnectionResource 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(ConnectionEntity.class) + @ApiOperation( + value = "Creates a connection", + response = ConnectionEntity.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 createConnection( @Context HttpServletRequest httpServletRequest, + @ApiParam( + value = "The connection configuration details.", + required = true + ) ConnectionEntity connectionEntity) { if (connectionEntity == null || connectionEntity.getConnection() == null) { @@ -474,7 +579,6 @@ public class ConnectionResource extends ApplicationResource { @Produces({MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML}) @Path("/{id}") @PreAuthorize("hasRole('ROLE_DFM')") - @TypeHint(ConnectionEntity.class) public Response updateConnection( @Context HttpServletRequest httpServletRequest, @FormParam(VERSION) LongParameter version, @@ -612,11 +716,33 @@ public class ConnectionResource extends ApplicationResource { @Produces({MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML}) @Path("/{id}") @PreAuthorize("hasRole('ROLE_DFM')") - @TypeHint(ConnectionEntity.class) + @ApiOperation( + value = "Updates a connection", + response = ConnectionEntity.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 updateConnection( @Context HttpServletRequest httpServletRequest, + @ApiParam( + value = "The connection id.", + required = true + ) @PathParam("id") String id, - ConnectionEntity connectionEntity) { + @ApiParam( + value = "The connection configuration details.", + required = true + ) ConnectionEntity connectionEntity) { if (connectionEntity == null || connectionEntity.getConnection() == null) { throw new IllegalArgumentException("Connection details must be specified."); @@ -680,14 +806,42 @@ public class ConnectionResource extends ApplicationResource { * @return An Entity containing the client id and an updated revision. */ @DELETE + @Consumes(MediaType.WILDCARD) @Produces({MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML}) @Path("/{id}") @PreAuthorize("hasRole('ROLE_DFM')") - @TypeHint(ConnectionEntity.class) + @ApiOperation( + value = "Deletes a connection", + response = ConnectionEntity.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 deleteRelationshipTarget( @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 connection id.", + required = true + ) @PathParam("id") String id) { // replicate if cluster manager
