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  * 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.media.Content;
  23 import io.swagger.v3.oas.annotations.media.Schema;
  24 import io.swagger.v3.oas.annotations.responses.ApiResponse;
  25 import io.swagger.v3.oas.annotations.security.SecurityRequirement;
  26 import io.swagger.v3.oas.annotations.tags.Tag;
  27 import org.apache.archiva.components.rest.model.PagedResult;
  28 import org.apache.archiva.redback.authorization.RedbackAuthorization;
  29 import org.apache.archiva.rest.api.model.v2.Repository;
  30 import org.apache.archiva.rest.api.model.v2.RepositoryStatistics;
  31 import org.apache.archiva.rest.api.model.v2.ScanStatus;
  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.Path;
  40 import javax.ws.rs.PathParam;
  41 import javax.ws.rs.Produces;
  42 import javax.ws.rs.QueryParam;
  43 import javax.ws.rs.core.Context;
  44 import javax.ws.rs.core.Response;
  45 import javax.ws.rs.core.UriInfo;
  46 import java.util.List;
  47
  48 import static javax.ws.rs.core.MediaType.APPLICATION_JSON;
  49 import static org.apache.archiva.rest.api.services.v2.RestConfiguration.DEFAULT_PAGE_LIMIT;
  50
  51 /**
  52  * @author Martin Stockhammer <martin_s@apache.org>
  53  * @since 3.0
  54  */
  55 @Path( "repositories" )
  56 @Tag(name = "v2")
  57 @Tag(name = "v2/Repositories")
  58 @Schema(name="RepositoryService",description = "Manage repositories of all types")
  59 public interface RepositoryService
  60 {
  61
  62     @Path( "" )
  63     @GET
  64     @Produces( {APPLICATION_JSON} )
  65     @RedbackAuthorization( permissions = ArchivaRoleConstants.OPERATION_MANAGE_CONFIGURATION )
  66     @Operation( summary = "Returns all managed repositories.",
  67         parameters = {
  68             @Parameter( name = "q", description = "Search term" ),
  69             @Parameter( name = "offset", description = "The offset of the first element returned" ),
  70             @Parameter( name = "limit", description = "Maximum number of items to return in the response" ),
  71             @Parameter( name = "orderBy", description = "List of attribute used for sorting (key, value)" ),
  72             @Parameter( name = "order", description = "The sort order. Either ascending (asc) or descending (desc)" ),
  73             @Parameter( name = "locale", description = "The locale for name and description" )
  74         },
  75         security = {
  76             @SecurityRequirement(
  77                 name = ArchivaRoleConstants.OPERATION_MANAGE_CONFIGURATION
  78             )
  79         },
  80         responses = {
  81             @ApiResponse( responseCode = "200",
  82                 description = "If the list could be returned",
  83                 content = @Content( mediaType = APPLICATION_JSON, schema = @Schema( implementation = PagedResult.class ) )
  84             ),
  85             @ApiResponse( responseCode = "403", description = "Authenticated user is not permitted to gather the information",
  86                 content = @Content( mediaType = APPLICATION_JSON, schema = @Schema( implementation = ArchivaRestError.class ) ) )
  87         }
  88     )
  89     PagedResult<Repository> getRepositories( @QueryParam( "q" ) @DefaultValue( "" ) String searchTerm,
  90                                              @QueryParam( "offset" ) @DefaultValue( "0" ) Integer offset,
  91                                              @QueryParam( "limit" ) @DefaultValue( value = DEFAULT_PAGE_LIMIT ) Integer limit,
  92                                              @QueryParam( "orderBy" ) @DefaultValue( "id" ) List<String> orderBy,
  93                                              @QueryParam( "order" ) @DefaultValue( "asc" ) String order,
  94                                              @QueryParam( "locale" ) String localeString) throws ArchivaRestServiceException;
  95
  96     @Path( "managed/{id}/statistics" )
  97     @GET
  98     @Produces( {APPLICATION_JSON} )
  99     @RedbackAuthorization( permissions = ArchivaRoleConstants.OPERATION_MANAGE_CONFIGURATION )
 100     @Operation( summary = "Returns repository statistic data.",
 101         security = {
 102             @SecurityRequirement(
 103                 name = ArchivaRoleConstants.OPERATION_MANAGE_CONFIGURATION
 104             )
 105         },
 106         responses = {
 107             @ApiResponse( responseCode = "200",
 108                 description = "If the statistics could be returned",
 109                 content = @Content( mediaType = APPLICATION_JSON, schema = @Schema( implementation = RepositoryStatistics.class ) )
 110             ),
 111             @ApiResponse( responseCode = "403", description = "Authenticated user is not permitted to gather the information",
 112                 content = @Content( mediaType = APPLICATION_JSON, schema = @Schema( implementation = ArchivaRestError.class ) ) ),
 113             @ApiResponse( responseCode = "404", description = "The repository does not exist",
 114                 content = @Content( mediaType = APPLICATION_JSON, schema = @Schema( implementation = ArchivaRestError.class ) ) )
 115         }
 116     )
 117     RepositoryStatistics getManagedRepositoryStatistics( @PathParam( "id" ) String repositoryId )
 118         throws ArchivaRestServiceException;
 119
 120     @Path ("managed/{id}/scan/schedule")
 121     @POST
 122     @Produces ({ APPLICATION_JSON })
 123     @Consumes({ APPLICATION_JSON })
 124     @RedbackAuthorization (permissions = ArchivaRoleConstants.OPERATION_RUN_INDEXER)
 125     @Operation( summary = "Returns repository statistic data.",
 126         security = {
 127             @SecurityRequirement(
 128                 name = ArchivaRoleConstants.OPERATION_RUN_INDEXER
 129             )
 130         },
 131         responses = {
 132             @ApiResponse( responseCode = "200",
 133                 description = "If the statistics could be returned"
 134             ),
 135             @ApiResponse( responseCode = "403", description = "Authenticated user is not permitted to gather the information",
 136                 content = @Content( mediaType = APPLICATION_JSON, schema = @Schema( implementation = ArchivaRestError.class ) ) ),
 137             @ApiResponse( responseCode = "404", description = "The repository does not exist",
 138                 content = @Content( mediaType = APPLICATION_JSON, schema = @Schema( implementation = ArchivaRestError.class ) ) )
 139         }
 140     )
 141     Response scheduleRepositoryScan( @PathParam ("id") String repositoryId,
 142                                      @QueryParam ("fullScan") boolean fullScan )
 143         throws ArchivaRestServiceException;
 144
 145
 146     @Path ("managed/{id}/scan/now")
 147     @POST
 148     @Produces ({ APPLICATION_JSON })
 149     @Consumes({ APPLICATION_JSON })
 150     @RedbackAuthorization (permissions = ArchivaRoleConstants.OPERATION_RUN_INDEXER)
 151     @Operation( summary = "Runs a repository scan instantly and waits for the response.",
 152         security = {
 153             @SecurityRequirement(
 154                 name = ArchivaRoleConstants.OPERATION_RUN_INDEXER
 155             )
 156         },
 157         responses = {
 158             @ApiResponse( responseCode = "200",
 159                 description = "If the statistics could be returned",
 160                 content = @Content( mediaType = APPLICATION_JSON, schema = @Schema( implementation = RepositoryStatistics.class ) )
 161             ),
 162             @ApiResponse( responseCode = "403", description = "Authenticated user is not permitted to gather the information",
 163                 content = @Content( mediaType = APPLICATION_JSON, schema = @Schema( implementation = ArchivaRestError.class ) ) ),
 164             @ApiResponse( responseCode = "404", description = "The repository does not exist",
 165                 content = @Content( mediaType = APPLICATION_JSON, schema = @Schema( implementation = ArchivaRestError.class ) ) )
 166         }
 167     )
 168     RepositoryStatistics scanRepositoryImmediately( @PathParam ("id") String repositoryId )
 169         throws ArchivaRestServiceException;
 170
 171
 172     @Path ("managed/{id}/scan/status")
 173     @GET
 174     @Produces ({ APPLICATION_JSON })
 175     @RedbackAuthorization (permissions = ArchivaRoleConstants.OPERATION_RUN_INDEXER)
 176     @Operation( summary = "Returns status of running and scheduled scans.",
 177         security = {
 178             @SecurityRequirement(
 179                 name = ArchivaRoleConstants.OPERATION_RUN_INDEXER
 180             )
 181         },
 182         responses = {
 183             @ApiResponse( responseCode = "200",
 184                 description = "If the status could be returned",
 185                 content = @Content( mediaType = APPLICATION_JSON, schema = @Schema( implementation = ScanStatus.class ) )
 186             ),
 187             @ApiResponse( responseCode = "403", description = "Authenticated user is not permitted to gather the information",
 188                 content = @Content( mediaType = APPLICATION_JSON, schema = @Schema( implementation = ArchivaRestError.class ) ) ),
 189             @ApiResponse( responseCode = "404", description = "The repository does not exist",
 190                 content = @Content( mediaType = APPLICATION_JSON, schema = @Schema( implementation = ArchivaRestError.class ) ) )
 191         }
 192     )
 193     ScanStatus getScanStatus( @PathParam ("id") String repositoryId )
 194         throws ArchivaRestServiceException;
 195
 196     @Path ("managed/{id}/scan")
 197     @DELETE
 198     @Produces ({ APPLICATION_JSON })
 199     @RedbackAuthorization (permissions = ArchivaRoleConstants.OPERATION_RUN_INDEXER)
 200     @Operation( summary = "Cancels and removes all tasks for the given repository.",
 201         security = {
 202             @SecurityRequirement(
 203                 name = ArchivaRoleConstants.OPERATION_RUN_INDEXER
 204             )
 205         },
 206         responses = {
 207             @ApiResponse( responseCode = "200",
 208                 description = "If the task was removed successfully"
 209             ),
 210             @ApiResponse( responseCode = "403", description = "Authenticated user is not permitted to gather the information",
 211                 content = @Content( mediaType = APPLICATION_JSON, schema = @Schema( implementation = ArchivaRestError.class ) ) ),
 212             @ApiResponse( responseCode = "404", description = "The repository does not exist",
 213                 content = @Content( mediaType = APPLICATION_JSON, schema = @Schema( implementation = ArchivaRestError.class ) ) )
 214         }
 215     )
 216     Response removeScanningTaskFromQueue( @PathParam ("id") String repositoryId )
 217         throws ArchivaRestServiceException;
 218
 219
 220
 221     @Path ("remote/{id}/index/download/start")
 222     @POST
 223     @Produces ({ APPLICATION_JSON })
 224     @Consumes({ APPLICATION_JSON })
 225     @RedbackAuthorization (permissions = ArchivaRoleConstants.OPERATION_RUN_INDEXER)
 226     @Operation( summary = "Schedules a task for remote index download.",
 227         parameters = {
 228             @Parameter( name = "full", description = "If true, download the full index, otherwise try a update download." )
 229         },
 230         security = {
 231             @SecurityRequirement(
 232                 name = ArchivaRoleConstants.OPERATION_RUN_INDEXER
 233             )
 234         },
 235         responses = {
 236             @ApiResponse( responseCode = "200",
 237                 description = "If the task was scheduled"
 238             ),
 239             @ApiResponse( responseCode = "403", description = "Authenticated user is not permitted to gather the information",
 240                 content = @Content( mediaType = APPLICATION_JSON, schema = @Schema( implementation = ArchivaRestError.class ) ) ),
 241             @ApiResponse( responseCode = "404", description = "The repository does not exist",
 242                 content = @Content( mediaType = APPLICATION_JSON, schema = @Schema( implementation = ArchivaRestError.class ) ) )
 243         }
 244     )
 245     Response scheduleDownloadRemoteIndex( @PathParam ("id") String repositoryId,
 246                                               @QueryParam( "immediate" ) boolean immediately,
 247                                               @QueryParam ("full") boolean full, @Context UriInfo uriInfo )
 248         throws ArchivaRestServiceException;
 249
 250
 251     @Path ("remote/index/downloads")
 252     @GET
 253     @Produces ({ APPLICATION_JSON })
 254     @RedbackAuthorization (permissions = ArchivaRoleConstants.OPERATION_RUN_INDEXER)
 255     @Operation( summary = "Returns a list of running downloads from the remote repository.",
 256         security = {
 257             @SecurityRequirement(
 258                 name = ArchivaRoleConstants.OPERATION_RUN_INDEXER
 259             )
 260         },
 261         responses = {
 262             @ApiResponse( responseCode = "200",
 263                 description = "If the artifact was deleted"
 264             ),
 265             @ApiResponse( responseCode = "403", description = "Authenticated user is not permitted to gather the information",
 266                 content = @Content( mediaType = APPLICATION_JSON, schema = @Schema( implementation = ArchivaRestError.class ) ) )
 267         }
 268     )
 269     List<String> getRunningRemoteDownloads();
 270
 271
 272 }