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

   1 package org.apache.archiva.rest.api.v2.svc.maven;
   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  * Unless required by applicable law or agreed to in writing,
  13  * software distributed under the License is distributed on an
  14  * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
  15  * KIND, either express or implied.  See the License for the
  16  * specific language governing permissions and limitations
  17  * under the License.
  18  */
  19
  20 import io.swagger.v3.oas.annotations.Operation;
  21 import io.swagger.v3.oas.annotations.Parameter;
  22 import io.swagger.v3.oas.annotations.headers.Header;
  23 import io.swagger.v3.oas.annotations.media.Content;
  24 import io.swagger.v3.oas.annotations.media.Schema;
  25 import io.swagger.v3.oas.annotations.responses.ApiResponse;
  26 import io.swagger.v3.oas.annotations.security.SecurityRequirement;
  27 import io.swagger.v3.oas.annotations.tags.Tag;
  28 import org.apache.archiva.components.rest.model.PagedResult;
  29 import org.apache.archiva.redback.authorization.RedbackAuthorization;
  30 import org.apache.archiva.rest.api.v2.model.FileInfo;
  31 import org.apache.archiva.rest.api.v2.model.MavenManagedRepository;
  32 import org.apache.archiva.rest.api.v2.model.MavenManagedRepositoryUpdate;
  33 import org.apache.archiva.rest.api.v2.svc.ArchivaRestError;
  34 import org.apache.archiva.rest.api.v2.svc.ArchivaRestServiceException;
  35
  36 import javax.ws.rs.Consumes;
  37 import javax.ws.rs.DELETE;
  38 import javax.ws.rs.DefaultValue;
  39 import javax.ws.rs.GET;
  40 import javax.ws.rs.POST;
  41 import javax.ws.rs.PUT;
  42 import javax.ws.rs.Path;
  43 import javax.ws.rs.PathParam;
  44 import javax.ws.rs.Produces;
  45 import javax.ws.rs.QueryParam;
  46 import javax.ws.rs.core.MediaType;
  47 import javax.ws.rs.core.Response;
  48 import java.util.List;
  49
  50 import static javax.ws.rs.core.MediaType.APPLICATION_JSON;
  51 import static org.apache.archiva.rest.api.v2.svc.RestConfiguration.DEFAULT_PAGE_LIMIT;
  52 import static org.apache.archiva.security.common.ArchivaRoleConstants.*;
  53
  54 /**
  55  *
  56  * Service interface for update, delete, add of Managed Maven Repositories
  57  *
  58  * The add, delete, update methods for a repository use "/{id}" with the classical CRUD actions.
  59  * Where {id} is the repository ID.
  60  *
  61  * There are subpaths for certain repository management functions:
  62  * <ul>
  63  * <li>{@code /{id}/path/{groupsection1/groupsection2/... }/{project}/{version}/{artifact-file}}
  64  *  is used for accessing artifacts and directories by their repository path</li>
  65  * <li>{@code /{id}/co/{groupid}/{artifactid}/{version} } is used to access Maven artifacts by their coordinates.
  66  *  Which means, {groupid} is a '.' separated string.
  67  * </li>
  68  * </ul>
  69  *
  70  * @author Martin Stockhammer <martin_s@apache.org>
  71  * @since 3.0
  72  */
  73 @Schema( name = "MavenManagedRepositoryService", description = "Managing and configuration of managed maven repositories" )
  74 @Path( "repositories/maven/managed" )
  75 @Tag(name = "v2")
  76 @Tag(name = "v2/Repositories")
  77 public interface MavenManagedRepositoryService
  78 {
  79     @Path( "" )
  80     @GET
  81     @Produces( {APPLICATION_JSON} )
  82     @RedbackAuthorization( permissions = { OPERATION_MANAGE_CONFIGURATION, OPERATION_LIST_REPOSITORIES } )
  83     @Operation( summary = "Returns all managed repositories.",
  84         parameters = {
  85             @Parameter( name = "q", description = "Search term" ),
  86             @Parameter( name = "offset", description = "The offset of the first element returned" ),
  87             @Parameter( name = "limit", description = "Maximum number of items to return in the response" ),
  88             @Parameter( name = "orderBy", description = "List of attribute used for sorting (key, value)" ),
  89             @Parameter( name = "order", description = "The sort order. Either ascending (asc) or descending (desc)" )
  90         },
  91         security = {
  92             @SecurityRequirement(
  93                 name = OPERATION_MANAGE_CONFIGURATION
  94             ),
  95             @SecurityRequirement(
  96                 name = OPERATION_LIST_REPOSITORIES
  97             )
  98
  99         },
 100         responses = {
 101             @ApiResponse( responseCode = "200",
 102                 description = "If the list could be returned",
 103                 content = @Content( mediaType = APPLICATION_JSON, schema = @Schema( implementation = PagedResult.class ) )
 104             ),
 105             @ApiResponse( responseCode = "403", description = "Authenticated user is not permitted to gather the information",
 106                 content = @Content( mediaType = APPLICATION_JSON, schema = @Schema( implementation = ArchivaRestError.class ) ) )
 107         }
 108     )
 109     PagedResult<MavenManagedRepository> getManagedRepositories(
 110         @QueryParam( "q" ) @DefaultValue( "" ) String searchTerm,
 111         @QueryParam( "offset" ) @DefaultValue( "0" ) Integer offset,
 112         @QueryParam( "limit" ) @DefaultValue( value = DEFAULT_PAGE_LIMIT ) Integer limit,
 113         @QueryParam( "orderBy" ) @DefaultValue( "id" ) List<String> orderBy,
 114         @QueryParam( "order" ) @DefaultValue( "asc" ) String order )
 115         throws ArchivaRestServiceException;
 116
 117
 118     @Path( "{id}" )
 119     @GET
 120     @Produces( {MediaType.APPLICATION_JSON} )
 121     @RedbackAuthorization(
 122         permissions = { OPERATION_MANAGE_CONFIGURATION, OPERATION_READ_REPOSITORY},
 123         resource = "{id}"
 124     )
 125     @Operation( summary = "Returns the managed repository with the given id.",
 126         security = {
 127             @SecurityRequirement(
 128                 name = OPERATION_MANAGE_CONFIGURATION
 129             ),
 130             @SecurityRequirement(
 131                 name = OPERATION_READ_REPOSITORY,
 132                 scopes = "{id}"
 133             )
 134         },
 135         responses = {
 136             @ApiResponse( responseCode = "200",
 137                 description = "If the managed repository could be returned",
 138                 content = @Content( mediaType = APPLICATION_JSON, schema = @Schema( implementation = MavenManagedRepository.class ) )
 139             ),
 140             @ApiResponse( responseCode = "403", description = "Authenticated user is not permitted to gather the information",
 141                 content = @Content( mediaType = APPLICATION_JSON, schema = @Schema( implementation = ArchivaRestError.class ) ) ),
 142             @ApiResponse( responseCode = "404", description = "The managed repository with this id does not exist",
 143                 content = @Content( mediaType = APPLICATION_JSON, schema = @Schema( implementation = ArchivaRestError.class ) ) )
 144         }
 145     )
 146     MavenManagedRepository getManagedRepository( @PathParam( "id" ) String repositoryId )
 147         throws ArchivaRestServiceException;
 148
 149
 150     @Path( "{id}" )
 151     @DELETE
 152     @Produces( {MediaType.APPLICATION_JSON} )
 153     @RedbackAuthorization(
 154         permissions = { OPERATION_MANAGE_CONFIGURATION, OPERATION_DELETE_REPOSITORY },
 155         resource = "{id}"
 156     )
 157     @Operation( summary = "Deletes the managed repository with the given id.",
 158         security = {
 159             @SecurityRequirement(
 160                 name = OPERATION_MANAGE_CONFIGURATION
 161             ),
 162             @SecurityRequirement(
 163                 name = OPERATION_DELETE_REPOSITORY,
 164                 scopes = "{id}"
 165             )
 166         },
 167         responses = {
 168             @ApiResponse( responseCode = "200",
 169                 description = "If the managed repository could be returned"
 170             ),
 171             @ApiResponse( responseCode = "403", description = "Authenticated user is not permitted to gather the information",
 172                 content = @Content( mediaType = APPLICATION_JSON, schema = @Schema( implementation = ArchivaRestError.class ) ) ),
 173             @ApiResponse( responseCode = "404", description = "The managed repository with this id does not exist",
 174                 content = @Content( mediaType = APPLICATION_JSON, schema = @Schema( implementation = ArchivaRestError.class ) ) )
 175         }
 176     )
 177     Response deleteManagedRepository( @PathParam( "id" ) String repositoryId,
 178                                       @DefaultValue( "false" )
 179                                       @QueryParam( "deleteContent" ) Boolean deleteContent )
 180         throws ArchivaRestServiceException;
 181
 182
 183     @Path( "" )
 184     @POST
 185     @Consumes( {MediaType.APPLICATION_JSON} )
 186     @Produces( {MediaType.APPLICATION_JSON} )
 187     @RedbackAuthorization(
 188         permissions = { OPERATION_MANAGE_CONFIGURATION, OPERATION_ADD_REPOSITORY },
 189         resource = "{id}"
 190     )
 191     @Operation( summary = "Creates the managed repository",
 192         security = {
 193             @SecurityRequirement(
 194                 name = OPERATION_MANAGE_CONFIGURATION
 195             ),
 196             @SecurityRequirement(
 197                 name = OPERATION_ADD_REPOSITORY,
 198                 scopes = "{id}"
 199             )
 200         },
 201         responses = {
 202             @ApiResponse( responseCode = "201",
 203                 description = "If the managed repository could be created",
 204                 content = @Content( mediaType = APPLICATION_JSON, schema = @Schema( implementation = MavenManagedRepository.class ) )
 205             ),
 206             @ApiResponse( responseCode = "303", description = "The repository exists already",
 207                 headers = {
 208                     @Header( name = "Location", description = "The URL of existing repository ", schema = @Schema( type = "string" ) )
 209                 }
 210             ),
 211             @ApiResponse( responseCode = "403", description = "Authenticated user is not permitted to add repositories",
 212                 content = @Content( mediaType = APPLICATION_JSON, schema = @Schema( implementation = ArchivaRestError.class ) ) ),
 213             @ApiResponse( responseCode = "422", description = "The body data is not valid",
 214                 content = @Content( mediaType = APPLICATION_JSON, schema = @Schema( implementation = ArchivaRestError.class ) ) )
 215         }
 216     )
 217     MavenManagedRepository addManagedRepository( MavenManagedRepository managedRepository )
 218         throws ArchivaRestServiceException;
 219
 220
 221     @Path( "{id}" )
 222     @PUT
 223     @Consumes( {MediaType.APPLICATION_JSON} )
 224     @Produces( {MediaType.APPLICATION_JSON} )
 225     @RedbackAuthorization(
 226         permissions = { OPERATION_MANAGE_CONFIGURATION, OPERATION_EDIT_REPOSITORY },
 227         resource = "{id}"
 228     )
 229     @Operation( summary = "Updates the managed repository with the given id",
 230         security = {
 231             @SecurityRequirement(
 232                 name = OPERATION_MANAGE_CONFIGURATION
 233             ),
 234             @SecurityRequirement(
 235                 name = OPERATION_EDIT_REPOSITORY,
 236                 scopes = "{id}"
 237             )
 238         },
 239         responses = {
 240             @ApiResponse( responseCode = "200",
 241                 description = "If the managed repository could be updated",
 242                 content = @Content( mediaType = APPLICATION_JSON, schema = @Schema( implementation = MavenManagedRepository.class ) )
 243             ),
 244             @ApiResponse( responseCode = "403", description = "Authenticated user is not permitted to add repositories",
 245                 content = @Content( mediaType = APPLICATION_JSON, schema = @Schema( implementation = ArchivaRestError.class ) ) ),
 246             @ApiResponse( responseCode = "422", description = "The body data is not valid",
 247                 content = @Content( mediaType = APPLICATION_JSON, schema = @Schema( implementation = ArchivaRestError.class ) ) ),
 248             @ApiResponse( responseCode = "404", description = "The managed repository with this id does not exist",
 249                 content = @Content( mediaType = APPLICATION_JSON, schema = @Schema( implementation = ArchivaRestError.class ) ) )
 250         }
 251     )
 252     MavenManagedRepository updateManagedRepository( @PathParam( "id" ) String repositoryId,  MavenManagedRepositoryUpdate managedRepository )
 253         throws ArchivaRestServiceException;
 254
 255
 256     @Path( "{id}/path/{filePath: .+}" )
 257     @GET
 258     @Produces( {MediaType.APPLICATION_JSON} )
 259     @RedbackAuthorization(
 260         permissions = { OPERATION_MANAGE_CONFIGURATION, OPERATION_READ_REPOSITORY},
 261         resource = "{id}"
 262     )
 263     @Operation( summary = "Returns the status of a given artifact file in the repository",
 264         security = {
 265             @SecurityRequirement(
 266                 name = OPERATION_MANAGE_CONFIGURATION
 267             ),
 268             @SecurityRequirement(
 269                 name = OPERATION_READ_REPOSITORY,
 270                 scopes = "{id}"
 271             )
 272
 273         },
 274         responses = {
 275             @ApiResponse( responseCode = "200",
 276                 description = "If the file status is returned",
 277                 content = @Content( mediaType = APPLICATION_JSON, schema = @Schema( implementation = FileInfo.class ) )
 278             ),
 279             @ApiResponse( responseCode = "403", description = "Authenticated user is not permitted to add repositories",
 280                 content = @Content( mediaType = APPLICATION_JSON, schema = @Schema( implementation = ArchivaRestError.class ) ) ),
 281             @ApiResponse( responseCode = "404", description = "The managed repository with this id does not exist. Or the file does not exist.",
 282                 content = @Content( mediaType = APPLICATION_JSON, schema = @Schema( implementation = ArchivaRestError.class ) ) )
 283         }
 284     )
 285     FileInfo getFileStatus( @PathParam( "id" ) String repositoryId, @PathParam( "filePath" ) String fileLocation )
 286         throws ArchivaRestServiceException;
 287
 288
 289     /**
 290      * Permissions are checked in impl
 291      * will copy an artifact from the source repository to the target repository
 292      */
 293     @Path ("{srcId}/path/{path: .+}/copyto/{dstId}")
 294     @POST
 295     @Produces({APPLICATION_JSON})
 296     @RedbackAuthorization (noPermission = true)
 297     @Operation( summary = "Copies a artifact from the source repository to the destination repository with the same path",
 298         security = {
 299             @SecurityRequirement(
 300                 name = OPERATION_READ_REPOSITORY,
 301                 scopes = {
 302                     "{srcId}"
 303                 }
 304             ),
 305             @SecurityRequirement(
 306                 name= OPERATION_ADD_ARTIFACT,
 307                 scopes = {
 308                     "{dstId}"
 309                 }
 310             )
 311
 312         },
 313         responses = {
 314             @ApiResponse( responseCode = "200",
 315                 description = "If the artifact was copied"
 316             ),
 317             @ApiResponse( responseCode = "403", description = "Authenticated user is not permitted to gather the information",
 318                 content = @Content( mediaType = APPLICATION_JSON, schema = @Schema( implementation = ArchivaRestError.class ) ) ),
 319             @ApiResponse( responseCode = "404", description = "The repository does not exist, or if the artifact was not found",
 320                 content = @Content( mediaType = APPLICATION_JSON, schema = @Schema( implementation = ArchivaRestError.class ) ) )
 321         }
 322     )
 323     Response copyArtifact( @PathParam( "srcId" ) String srcRepositoryId, @PathParam( "dstId" ) String dstRepositoryId,
 324                            @PathParam( "path" ) String path )
 325         throws ArchivaRestServiceException;
 326
 327
 328     @Path ("{id}/path/{path: .+}")
 329     @DELETE
 330     @Consumes ({ APPLICATION_JSON })
 331     @RedbackAuthorization (
 332         permissions = { OPERATION_MANAGE_CONFIGURATION, OPERATION_DELETE_ARTIFACT },
 333         resource = "{id}"
 334     )
 335     @Operation( summary = "Deletes a artifact from the repository.",
 336         security = {
 337             @SecurityRequirement(
 338                 name = OPERATION_MANAGE_CONFIGURATION
 339             ),
 340             @SecurityRequirement(
 341                 name = OPERATION_DELETE_ARTIFACT,
 342                 scopes = "{id}"
 343             )
 344
 345         },
 346         responses = {
 347             @ApiResponse( responseCode = "200",
 348                 description = "If the artifact was deleted"
 349             ),
 350             @ApiResponse( responseCode = "403", description = "Authenticated user is not permitted to gather the information",
 351                 content = @Content( mediaType = APPLICATION_JSON, schema = @Schema( implementation = ArchivaRestError.class ) ) ),
 352             @ApiResponse( responseCode = "404", description = "The repository or the artifact does not exist",
 353                 content = @Content( mediaType = APPLICATION_JSON, schema = @Schema( implementation = ArchivaRestError.class ) ) )
 354         }
 355     )
 356     Response deleteArtifact( @PathParam( "id" ) String repositoryId, @PathParam( "path" ) String path )
 357         throws ArchivaRestServiceException;
 358
 359     @Path ( "{id}/co/{groupid}/{artifactid}/{version}" )
 360     @DELETE
 361     @Produces ({ MediaType.APPLICATION_JSON })
 362     @RedbackAuthorization (
 363         permissions = { OPERATION_MANAGE_CONFIGURATION, OPERATION_DELETE_VERSION},
 364         resource = "{id}"
 365     )
 366     @Operation( summary = "Removes a version and all its content from the repository",
 367         security = {
 368             @SecurityRequirement(
 369                 name = OPERATION_MANAGE_CONFIGURATION
 370             ),
 371             @SecurityRequirement(
 372                 name = OPERATION_DELETE_VERSION,
 373                 scopes = "{id}"
 374             )
 375
 376         },
 377         responses = {
 378             @ApiResponse( responseCode = "200",
 379                 description = "If the deletion was successful"
 380             ),
 381             @ApiResponse( responseCode = "403", description = "Authenticated user is not permitted to delete in repositories",
 382                 content = @Content( mediaType = APPLICATION_JSON, schema = @Schema( implementation = ArchivaRestError.class ) ) ),
 383             @ApiResponse( responseCode = "404", description = "The managed repository with this id does not exist. Or the version does not exist.",
 384                 content = @Content( mediaType = APPLICATION_JSON, schema = @Schema( implementation = ArchivaRestError.class ) ) )
 385         }
 386     )
 387     Response removeProjectVersion( @PathParam ( "id" ) String repositoryId,
 388                                    @PathParam ( "groupid" ) String namespace, @PathParam ( "artifactid" ) String projectId,
 389                                    @PathParam ( "version" ) String version )
 390         throws org.apache.archiva.rest.api.services.ArchivaRestServiceException;
 391
 392
 393     @Path ( "{id}/co/{groupid}/{artifactid}" )
 394     @DELETE
 395     @Produces ({ MediaType.APPLICATION_JSON })
 396     @RedbackAuthorization (noPermission = true)
 397     @Operation( summary = "Removes a artifact and all its versions from the repository",
 398         security = {
 399             @SecurityRequirement(
 400                 name = OPERATION_MANAGE_CONFIGURATION
 401             ),
 402             @SecurityRequirement(
 403                 name = OPERATION_DELETE_PROJECT,
 404                 scopes = "{id}"
 405             )
 406
 407         },
 408         responses = {
 409             @ApiResponse( responseCode = "200",
 410                 description = "If the deletion was successful"
 411             ),
 412             @ApiResponse( responseCode = "403", description = "Authenticated user is not permitted to delete in repositories",
 413                 content = @Content( mediaType = APPLICATION_JSON, schema = @Schema( implementation = ArchivaRestError.class ) ) ),
 414             @ApiResponse( responseCode = "404", description = "The managed repository with this id does not exist. Or the artifact does not exist.",
 415                 content = @Content( mediaType = APPLICATION_JSON, schema = @Schema( implementation = ArchivaRestError.class ) ) )
 416         }
 417     )
 418     Response deleteProject( @PathParam ("id") String repositoryId, @PathParam ( "groupid" ) String namespace, @PathParam ( "artifactid" ) String projectId )
 419         throws org.apache.archiva.rest.api.services.ArchivaRestServiceException;
 420
 421     @Path ( "{id}/co/{groupid}" )
 422     @DELETE
 423     @Produces ({ MediaType.APPLICATION_JSON })
 424     @RedbackAuthorization (
 425         permissions = { OPERATION_MANAGE_CONFIGURATION, OPERATION_DELETE_NAMESPACE },
 426         resource = "{id}"
 427     )
 428     @Operation( summary = "Removes a group and all subfolders from the repository",
 429         security = {
 430             @SecurityRequirement(
 431                 name = OPERATION_MANAGE_CONFIGURATION
 432             ),
 433             @SecurityRequirement(
 434                 name = OPERATION_DELETE_NAMESPACE,
 435                 scopes = "{id}"
 436             )
 437         },
 438         responses = {
 439             @ApiResponse( responseCode = "200",
 440                 description = "If the deletion was successful"
 441             ),
 442             @ApiResponse( responseCode = "403", description = "Authenticated user is not permitted to delete namespaces in repositories",
 443                 content = @Content( mediaType = APPLICATION_JSON, schema = @Schema( implementation = ArchivaRestError.class ) ) ),
 444             @ApiResponse( responseCode = "404", description = "The managed repository with this id does not exist. Or the groupid does not exist.",
 445                 content = @Content( mediaType = APPLICATION_JSON, schema = @Schema( implementation = ArchivaRestError.class ) ) )
 446         }
 447     )
 448     Response deleteNamespace( @PathParam ("id") String repositoryId, @PathParam ( "groupid" ) String namespace )
 449         throws org.apache.archiva.rest.api.services.ArchivaRestServiceException;
 450
 451 }