source.dussan.org Git - archiva.git/blob

   1 package org.apache.archiva.rest.api.services.v2;
   2 /*
   3  * Licensed to the Apache Software Foundation (ASF) under one
   4  * or more contributor license agreements.  See the NOTICE file
   5  * distributed with this work for additional information
   6  * regarding copyright ownership.  The ASF licenses this file
   7  * to you under the Apache License, Version 2.0 (the
   8  * "License"); you may not use this file except in compliance
   9  * with the License.  You may obtain a copy of the License at
  10  *
  11  *   http://www.apache.org/licenses/LICENSE-2.0
  12  *
  13  * Unless required by applicable law or agreed to in writing,
  14  * software distributed under the License is distributed on an
  15  * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
  16  * KIND, either express or implied.  See the License for the
  17  * specific language governing permissions and limitations
  18  * under the License.
  19  */
  20
  21 import io.swagger.v3.oas.annotations.Operation;
  22 import io.swagger.v3.oas.annotations.Parameter;
  23 import io.swagger.v3.oas.annotations.headers.Header;
  24 import io.swagger.v3.oas.annotations.media.Content;
  25 import io.swagger.v3.oas.annotations.media.Schema;
  26 import io.swagger.v3.oas.annotations.parameters.RequestBody;
  27 import io.swagger.v3.oas.annotations.responses.ApiResponse;
  28 import io.swagger.v3.oas.annotations.security.SecurityRequirement;
  29 import org.apache.archiva.components.rest.model.PagedResult;
  30 import org.apache.archiva.redback.authorization.RedbackAuthorization;
  31 import org.apache.archiva.rest.api.model.v2.RepositoryGroup;
  32 import org.apache.archiva.security.common.ArchivaRoleConstants;
  33
  34 import javax.ws.rs.Consumes;
  35 import javax.ws.rs.DELETE;
  36 import javax.ws.rs.DefaultValue;
  37 import javax.ws.rs.GET;
  38 import javax.ws.rs.POST;
  39 import javax.ws.rs.PUT;
  40 import javax.ws.rs.Path;
  41 import javax.ws.rs.PathParam;
  42 import javax.ws.rs.Produces;
  43 import javax.ws.rs.QueryParam;
  44 import javax.ws.rs.core.Response;
  45 import java.util.List;
  46
  47 import static javax.ws.rs.core.MediaType.APPLICATION_JSON;
  48 import static org.apache.archiva.rest.api.services.v2.RestConfiguration.DEFAULT_PAGE_LIMIT;
  49
  50 /**
  51  * Endpoint for repository groups that combine multiple repositories into a single virtual repository.
  52  *
  53  * @author Olivier Lamy
  54  * @author Martin Stockhammer
  55  * @since 3.0
  56  */
  57 @Path( "/repository_groups" )
  58 @Schema( name = "RepositoryGroups", description = "Managing of repository groups or virtual repositories" )
  59 public interface RepositoryGroupService
  60 {
  61     @Path( "" )
  62     @GET
  63     @Produces( {APPLICATION_JSON} )
  64     @RedbackAuthorization( permissions = ArchivaRoleConstants.OPERATION_MANAGE_CONFIGURATION )
  65     @Operation( summary = "Returns all repository group entries.",
  66         parameters = {
  67             @Parameter( name = "q", description = "Search term" ),
  68             @Parameter( name = "offset", description = "The offset of the first element returned" ),
  69             @Parameter( name = "limit", description = "Maximum number of items to return in the response" ),
  70             @Parameter( name = "orderBy", description = "List of attribute used for sorting (key, value)" ),
  71             @Parameter( name = "order", description = "The sort order. Either ascending (asc) or descending (desc)" )
  72         },
  73         security = {
  74             @SecurityRequirement(
  75                 name = ArchivaRoleConstants.OPERATION_MANAGE_CONFIGURATION
  76             )
  77         },
  78         responses = {
  79             @ApiResponse( responseCode = "200",
  80                 description = "If the list could be returned",
  81                 content = @Content( mediaType = APPLICATION_JSON, schema = @Schema( implementation = PagedResult.class ) )
  82             ),
  83             @ApiResponse( responseCode = "403", description = "Authenticated user is not permitted to gather the information",
  84                 content = @Content( mediaType = APPLICATION_JSON, schema = @Schema( implementation = ArchivaRestError.class ) ) )
  85         }
  86     )
  87     PagedResult<RepositoryGroup> getRepositoriesGroups( @QueryParam( "q" ) @DefaultValue( "" ) String searchTerm,
  88                                                         @QueryParam( "offset" ) @DefaultValue( "0" ) Integer offset,
  89                                                         @QueryParam( "limit" ) @DefaultValue( value = DEFAULT_PAGE_LIMIT ) Integer limit,
  90                                                         @QueryParam( "orderBy" ) @DefaultValue( "id" ) List<String> orderBy,
  91                                                         @QueryParam( "order" ) @DefaultValue( "asc" ) String order )
  92         throws ArchivaRestServiceException;
  93
  94     @Path( "{id}" )
  95     @GET
  96     @Produces( {APPLICATION_JSON} )
  97     @RedbackAuthorization( permissions = ArchivaRoleConstants.OPERATION_MANAGE_CONFIGURATION )
  98     @Operation( summary = "Returns a single repository group configuration.",
  99         security = {
 100             @SecurityRequirement(
 101                 name = ArchivaRoleConstants.OPERATION_MANAGE_CONFIGURATION
 102             )
 103         },
 104         responses = {
 105             @ApiResponse( responseCode = "200",
 106                 description = "If the configuration is returned",
 107                 content = @Content( mediaType = APPLICATION_JSON, schema = @Schema( implementation = RepositoryGroup.class ) )
 108             ),
 109             @ApiResponse( responseCode = "403", description = "Authenticated user is not permitted to gather the information",
 110                 content = @Content( mediaType = APPLICATION_JSON, schema = @Schema( implementation = ArchivaRestError.class ) ) ),
 111             @ApiResponse( responseCode = "404", description = "The repository group with the given id does not exist",
 112                 content = @Content( mediaType = APPLICATION_JSON, schema = @Schema( implementation = ArchivaRestError.class ) ) )
 113         }
 114     )
 115     RepositoryGroup getRepositoryGroup( @PathParam( "id" ) String repositoryGroupId )
 116         throws ArchivaRestServiceException;
 117
 118     @Path( "" )
 119     @POST
 120     @Consumes( {APPLICATION_JSON} )
 121     @Produces( {APPLICATION_JSON} )
 122     @RedbackAuthorization( permissions = ArchivaRoleConstants.OPERATION_MANAGE_CONFIGURATION )
 123     @Operation( summary = "Creates a new group entry.",
 124         requestBody =
 125         @RequestBody( required = true, description = "The configuration of the repository group.",
 126             content = @Content( mediaType = APPLICATION_JSON, schema = @Schema( implementation = RepositoryGroup.class ) )
 127         )
 128         ,
 129         security = {
 130             @SecurityRequirement(
 131                 name = ArchivaRoleConstants.OPERATION_MANAGE_CONFIGURATION
 132             )
 133         },
 134         responses = {
 135             @ApiResponse( responseCode = "201",
 136                 description = "If the repository group was created",
 137                 content = @Content( mediaType = APPLICATION_JSON, schema = @Schema( implementation = RepositoryGroup.class ) )
 138             ),
 139             @ApiResponse( responseCode = "303", description = "The repository group exists already",
 140                 headers = {
 141                     @Header( name = "Location", description = "The URL of existing group", schema = @Schema( type = "string" ) )
 142                 }
 143             ),
 144             @ApiResponse( responseCode = "403", description = "Authenticated user is not permitted to gather the information",
 145                 content = @Content( mediaType = APPLICATION_JSON, schema = @Schema( implementation = ArchivaRestError.class ) ) ),
 146             @ApiResponse( responseCode = "422", description = "The body data is not valid",
 147                 content = @Content( mediaType = APPLICATION_JSON, schema = @Schema( implementation = ArchivaRestError.class ) ) )
 148         }
 149     )
 150     RepositoryGroup addRepositoryGroup( RepositoryGroup repositoryGroup )
 151         throws ArchivaRestServiceException;
 152
 153     @Path( "{id}" )
 154     @PUT
 155     @Consumes( {APPLICATION_JSON} )
 156     @Produces( {APPLICATION_JSON} )
 157     @RedbackAuthorization( permissions = ArchivaRoleConstants.OPERATION_MANAGE_CONFIGURATION )
 158     @Operation( summary = "Returns all repository group entries.",
 159         requestBody =
 160         @RequestBody( required = true, description = "The configuration of the repository group.",
 161             content = @Content( mediaType = APPLICATION_JSON, schema = @Schema( implementation = RepositoryGroup.class ) )
 162         )
 163         ,
 164         security = {
 165             @SecurityRequirement(
 166                 name = ArchivaRoleConstants.OPERATION_MANAGE_CONFIGURATION
 167             )
 168         },
 169         responses = {
 170             @ApiResponse( responseCode = "200",
 171                 description = "If the group is returned",
 172                 content = @Content( mediaType = APPLICATION_JSON, schema = @Schema( implementation = RepositoryGroup.class ) )
 173             ),
 174             @ApiResponse( responseCode = "403", description = "Authenticated user is not permitted to gather the information",
 175                 content = @Content( mediaType = APPLICATION_JSON, schema = @Schema( implementation = ArchivaRestError.class ) ) ),
 176             @ApiResponse( responseCode = "404", description = "The group with the given id does not exist",
 177                 content = @Content( mediaType = APPLICATION_JSON, schema = @Schema( implementation = ArchivaRestError.class ) ) ),
 178             @ApiResponse( responseCode = "422", description = "The body data is not valid",
 179                 content = @Content( mediaType = APPLICATION_JSON, schema = @Schema( implementation = ArchivaRestError.class ) ) )
 180         }
 181     )
 182     RepositoryGroup updateRepositoryGroup( @PathParam( "id" ) String groupId, RepositoryGroup repositoryGroup )
 183         throws ArchivaRestServiceException;
 184
 185     @Path( "{id}" )
 186     @DELETE
 187     @Produces( {APPLICATION_JSON} )
 188     @RedbackAuthorization( permissions = ArchivaRoleConstants.OPERATION_MANAGE_CONFIGURATION )
 189     @Operation( summary = "Deletes the repository group entry with the given id.",
 190         security = {
 191             @SecurityRequirement(
 192                 name = ArchivaRoleConstants.OPERATION_MANAGE_CONFIGURATION
 193             )
 194         },
 195         responses = {
 196             @ApiResponse( responseCode = "200",
 197                 description = "If the group was deleted"
 198             ),
 199             @ApiResponse( responseCode = "403", description = "Authenticated user is not permitted to delete the group",
 200                 content = @Content( mediaType = APPLICATION_JSON, schema = @Schema( implementation = ArchivaRestError.class ) ) ),
 201             @ApiResponse( responseCode = "404", description = "The group with the given id does not exist",
 202                 content = @Content( mediaType = APPLICATION_JSON, schema = @Schema( implementation = ArchivaRestError.class ) ) ),
 203         }
 204     )
 205     Response deleteRepositoryGroup( @PathParam( "id" ) String repositoryGroupId )
 206         throws ArchivaRestServiceException;
 207
 208     @Path( "{id}/repositories/{repositoryId}" )
 209     @PUT
 210     @Produces( {APPLICATION_JSON} )
 211     @RedbackAuthorization( permissions = ArchivaRoleConstants.OPERATION_MANAGE_CONFIGURATION )
 212     @Operation( summary = "Adds the repository with the given id to the repository group.",
 213         security = {
 214             @SecurityRequirement(
 215                 name = ArchivaRoleConstants.OPERATION_MANAGE_CONFIGURATION
 216             )
 217         },
 218         responses = {
 219             @ApiResponse( responseCode = "200",
 220                 description = "If the repository was added or if it was already part of the group"
 221             ),
 222             @ApiResponse( responseCode = "403", description = "Authenticated user is not permitted to delete the group",
 223                 content = @Content( mediaType = APPLICATION_JSON, schema = @Schema( implementation = ArchivaRestError.class ) ) ),
 224             @ApiResponse( responseCode = "404", description = "The group with the given id does not exist",
 225                 content = @Content( mediaType = APPLICATION_JSON, schema = @Schema( implementation = ArchivaRestError.class ) ) ),
 226         }
 227     )
 228     RepositoryGroup addRepositoryToGroup( @PathParam( "id" ) String repositoryGroupId,
 229                                           @PathParam( "repositoryId" ) String repositoryId )
 230         throws ArchivaRestServiceException;
 231
 232     @Path( "{id}/repositories/{repositoryId}" )
 233     @DELETE
 234     @Produces( {APPLICATION_JSON} )
 235     @RedbackAuthorization( permissions = ArchivaRoleConstants.OPERATION_MANAGE_CONFIGURATION )
 236     @Operation( summary = "Removes the repository with the given id from the repository group.",
 237         security = {
 238             @SecurityRequirement(
 239                 name = ArchivaRoleConstants.OPERATION_MANAGE_CONFIGURATION
 240             )
 241         },
 242         responses = {
 243             @ApiResponse( responseCode = "200",
 244                 description = "If the repository was removed."
 245             ),
 246             @ApiResponse( responseCode = "403", description = "Authenticated user is not permitted to delete the group",
 247                 content = @Content( mediaType = APPLICATION_JSON, schema = @Schema( implementation = ArchivaRestError.class ) ) ),
 248             @ApiResponse( responseCode = "404", description = "The group with the given id does not exist, or the repository was not part of the group.",
 249                 content = @Content( mediaType = APPLICATION_JSON, schema = @Schema( implementation = ArchivaRestError.class ) ) ),
 250         }
 251     )
 252     RepositoryGroup deleteRepositoryFromGroup( @PathParam( "id" ) String repositoryGroupId,
 253                                                @PathParam( "repositoryId" ) String repositoryId )
 254         throws ArchivaRestServiceException;
 255
 256
 257 }