001/*
002 * Copyright 2020 Global Biodiversity Information Facility (GBIF)
003 *
004 * Licensed under the Apache License, Version 2.0 (the "License");
005 * you may not use this file except in compliance with the License.
006 * You may obtain a copy of the License at
007 *
008 *     http://www.apache.org/licenses/LICENSE-2.0
009 *
010 * Unless required by applicable law or agreed to in writing, software
011 * distributed under the License is distributed on an "AS IS" BASIS,
012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013 * See the License for the specific language governing permissions and
014 * limitations under the License.
015 */
016package org.gbif.api.model.common.paging;
017
018import javax.validation.constraints.Min;
019
020import io.swagger.v3.oas.annotations.Parameter;
021import io.swagger.v3.oas.annotations.enums.ParameterIn;
022import io.swagger.v3.oas.annotations.media.Schema;
023
024import java.lang.annotation.Inherited;
025import java.lang.annotation.Retention;
026import java.lang.annotation.RetentionPolicy;
027import java.lang.annotation.Target;
028
029import static java.lang.annotation.ElementType.ANNOTATION_TYPE;
030import static java.lang.annotation.ElementType.FIELD;
031import static java.lang.annotation.ElementType.METHOD;
032import static java.lang.annotation.ElementType.PARAMETER;
033
034/**
035 * Most simple paging interface for both request and responses.
036 */
037public interface Pageable {
038
039  /**
040   * Maximum number of records to be returned.
041   *
042   * @return the limit.
043   */
044  @Parameter(
045    name = "limit",
046    description = "Controls the number of results in the page.\n\n" +
047      "A value above the maximum allowed for the service will be replaced with " +
048      "the maximum, which varies depending on the service. Sensible defaults " +
049      "are used.",
050    schema = @Schema(implementation = Integer.class, minimum = "0"),
051    in = ParameterIn.QUERY)
052  @Min(0)
053  int getLimit();
054
055  /**
056   * Defines how many items to skip before beginning to return records.
057   *
058   * @return the offset with 0 being no offset at all.
059   */
060  @Parameter(
061    name = "offset",
062    description = "Determines the offset for the search results.\n\n" +
063      "A limit of 20 and offset of 40 will retrieve the third page of 20 " +
064      "results. Some services have a maximum offset.",
065    schema = @Schema(implementation = Integer.class, minimum = "0"),
066    in = ParameterIn.QUERY)
067  @Min(0)
068  long getOffset();
069
070  /**
071   * The usual (search) limit and offset parameters
072   */
073  @Target({PARAMETER, METHOD, FIELD, ANNOTATION_TYPE})
074  @Retention(RetentionPolicy.RUNTIME)
075  @Inherited
076  @io.swagger.v3.oas.annotations.Parameters(
077    value = {
078      @Parameter(
079        name = "limit",
080        description = "Controls the number of results in the page. Using too high a value will be overwritten with the default maximum threshold, depending on the service. Sensible defaults are used so this may be omitted.",
081        schema = @Schema(implementation = Integer.class, minimum = "0"),
082        in = ParameterIn.QUERY),
083      @Parameter(
084        name = "offset",
085        description = "Determines the offset for the search results. A limit of 20 and offset of 40 will get the third page of 20 results. Some services have a maximum offset.",
086        schema = @Schema(implementation = Integer.class, minimum = "0"),
087        in = ParameterIn.QUERY),
088      @Parameter(
089        name = "page",
090        hidden = true
091      )
092    }
093  )
094  @interface OffsetLimitParameters {}
095}