Feature/paging

CHANGELOG.md

@@ -12,6 +12,7 @@
 - output includes href property
 
 ### Features
+- #129 provides paging headers if backend supports counting
 - #232 possibility to use `domainId` instead of database id
 - #266 `AbstractValue` can have time intervals
 - #304 flexible prerendering title config via placeholders

docs/_layouts/default.html

@@ -49,6 +49,9 @@
       <p class="header">
         <a href="{{ site.baseurl }}/configuration.html">Configuration</a>
       </p>
+      <p class="header">
+        <a href="{{ site.baseurl }}/paging.html">Paging</a>
+      </p>
       <p class="header">
         <a href="{{ site.baseurl }}/extensions.html">Extensions</a>
       </p>

docs/paging.md

@@ -0,0 +1,64 @@
+---
+layout: page
+title: Paging
+permalink: /paging
+---
+
+
+
+## Overview
+
+{:.n52-callout .n52-callout-info}
+Paging is currently not supported for the Endpoint `/geometries`. All other Endpoints are supported.
+
+The API offers basic Paging support using the Query Parameters `offset` and `limit`. Paging is automatically enabled if at least one of the parameters is present in the query. If only one parameter is provided, the missing parameters default value will be used.
+
+### Parameter Semantics
+
+`limit` describes the maximum amount of Elements in one Page. Except for the last Page, all Pages will always be filled to this maximum capacity.
+
+`offset` describes the Page Number, starting from zero.
+
+{:.n52-callout .n52-callout-info}
+It is **strongly advised** to only specify the `limit` Parameter in the client, and get the `offset` from the Response Headers returned by the API (see examples below). 
+
+### Parameter Values
+The Parameter Values are subject to the following restrictions:
+
+{:.table}
+parameter     | MIN_VALUE  | MAX_VALUE  | default      |
+--------------|------------|---------------------------|
+`limit`       | 1          | 1000000    | 10000        | 
+`offset`      | 0          | 2147483647 | 0            | 
+
+{:.n52-callout .n52-callout-info}
+Both `limit` and `offset` are integers and are programmatically limited to not exceed the value of 2147483647. If higher Numbers are provided the Request will fail and the API will throw an Error.
+
+If an invalid `limit` (i.e. exceeding MAX_VALUE) is supplied, `limit` will default to the closest valid value (e.g. MIN_VALUE or MAX_VALUE). 
+If no `limit` is supplied the default value will be used.
+
+If no offset or an invalid `offset` is supplied, `offset` will default to its default value. 
+
+### Response Headers
+Paging Information is returned by the API in the Response Header. An Example of the returned Headers can be found below:
+
+**Example Request URL**
+```
+http://example.com/api/stations?offset=2&limit=10
+```
+
+**Example Response Header [partial]:**
+```
+[...]
+Link : <http://example.com/api/stations?offset=2&limit=10> rel="self"
+Link : <http://example.com/api/stations?offset=3&limit=10> rel="next"
+Link : <http://example.com/api/stations?offset=1&limit=10> rel="previous"
+Link : <http://example.com/api/stations?offset=0&limit=10> rel="first"
+Link : <http://example.com/api/stations?offset=7&limit=10> rel="last"
+[...]
+```
+The Presence of the Links in the Response Header varies on the specific circumstances:
+
+ - The Link to `self` is always present.
+ - The Links to `first` and `last` are present if a valid offset was provided.
+ - The Links to `next` and `previous` are present if the pages exist and a valid offset was provided.

rest/pom.xml

@@ -18,7 +18,6 @@
             <groupId>${project.groupId}</groupId>
             <artifactId>spi</artifactId>
         </dependency>
-
         <dependency>
             <groupId>com.fasterxml.jackson.core</groupId>
             <artifactId>jackson-core</artifactId>

rest/src/main/java/org/n52/web/ctrl/CategoriesParameterController.java

@@ -29,6 +29,7 @@
 package org.n52.web.ctrl;
 
 
+import org.n52.io.request.IoParameters;
 import org.n52.io.response.CategoryOutput;
 import org.springframework.web.bind.annotation.RequestMapping;
 import org.springframework.web.bind.annotation.RestController;
@@ -37,4 +38,14 @@
 @RequestMapping(UrlSettings.COLLECTION_CATEGORIES)
 public class CategoriesParameterController extends ParameterRequestMappingAdapter<CategoryOutput> {
 
+    @Override
+    public String getCollectionPath(String hrefBase) {
+        UrlHelper urlhelper = new UrlHelper();
+        return urlhelper.constructHref(hrefBase, UrlSettings.COLLECTION_CATEGORIES);
+    }
+
+    @Override
+    protected int getElementCount(IoParameters queryMap) {
+        return super.getEntityCounter().getCategoryCount(IoParameters.ensureBackwardsCompatibility(queryMap));
+    }
 }

rest/src/main/java/org/n52/web/ctrl/DatasetController.java

@@ -28,6 +28,7 @@
  */
 package org.n52.web.ctrl;
 
+import org.n52.io.request.IoParameters;
 import org.n52.io.response.dataset.DatasetOutput;
 import org.springframework.web.bind.annotation.RequestMapping;
 import org.springframework.web.bind.annotation.RequestMethod;
@@ -37,4 +38,15 @@
 @RequestMapping(path = UrlSettings.COLLECTION_DATASETS, method = RequestMethod.GET)
 public class DatasetController extends ParameterRequestMappingAdapter<DatasetOutput> {
 
+    @Override
+    public String getCollectionPath(String hrefBase) {
+        UrlHelper urlhelper = new UrlHelper();
+        return urlhelper.constructHref(hrefBase, UrlSettings.COLLECTION_DATASETS);
+    }
+
+    @Override
+    protected int getElementCount(IoParameters queryMap) {
+        return super.getEntityCounter().getDatasetCount(queryMap);
+    }
+
 }

rest/src/main/java/org/n52/web/ctrl/FeaturesParameterController.java

@@ -29,6 +29,7 @@
 package org.n52.web.ctrl;
 
 
+import org.n52.io.request.IoParameters;
 import org.n52.io.response.FeatureOutput;
 import org.springframework.web.bind.annotation.RequestMapping;
 import org.springframework.web.bind.annotation.RestController;
@@ -37,4 +38,14 @@
 @RequestMapping(path = UrlSettings.COLLECTION_FEATURES)
 public class FeaturesParameterController extends ParameterRequestMappingAdapter<FeatureOutput> {
 
+    @Override
+    public String getCollectionPath(String hrefBase) {
+        UrlHelper urlhelper = new UrlHelper();
+        return urlhelper.constructHref(hrefBase, UrlSettings.COLLECTION_FEATURES);
+    }
+
+    @Override
+    protected int getElementCount(IoParameters queryMap) {
+        return super.getEntityCounter().getFeatureCount(IoParameters.ensureBackwardsCompatibility(queryMap));
+    }
 }

rest/src/main/java/org/n52/web/ctrl/GeometriesController.java

@@ -28,6 +28,7 @@
  */
 package org.n52.web.ctrl;
 
+import org.n52.io.request.IoParameters;
 import org.n52.io.response.GeometryInfo;
 import org.n52.series.spi.geo.TransformingGeometryOutputService;
 import org.n52.series.spi.srv.ParameterService;
@@ -43,4 +44,16 @@ public void setParameterService(ParameterService<GeometryInfo> parameterService)
         super.setParameterService(new TransformingGeometryOutputService(parameterService));
     }
 
+    @Override
+    public String getCollectionPath(String hrefBase) {
+        UrlHelper urlhelper = new UrlHelper();
+        return urlhelper.constructHref(hrefBase, UrlSettings.COLLECTION_GEOMETRIES);
+    }
+
+    @Override
+    protected int getElementCount(IoParameters queryMap) {
+        //TODO(specki): Implementation of getCount  for Geometries in EntityCounter
+        return -1;
+    }
+
 }

rest/src/main/java/org/n52/web/ctrl/OfferingsParameterController.java

@@ -28,6 +28,7 @@
  */
 package org.n52.web.ctrl;
 
+import org.n52.io.request.IoParameters;
 import org.n52.io.response.OfferingOutput;
 import org.springframework.web.bind.annotation.RequestMapping;
 import org.springframework.web.bind.annotation.RestController;
@@ -36,4 +37,14 @@
 @RequestMapping(path = UrlSettings.COLLECTION_OFFERINGS)
 public class OfferingsParameterController extends ParameterRequestMappingAdapter<OfferingOutput> {
 
+    @Override
+    public String getCollectionPath(String hrefBase) {
+        UrlHelper urlhelper = new UrlHelper();
+        return urlhelper.constructHref(hrefBase, UrlSettings.COLLECTION_OFFERINGS);
+    }
+
+    @Override
+    protected int getElementCount(IoParameters queryMap) {
+        return super.getEntityCounter().getOfferingCount(IoParameters.ensureBackwardsCompatibility(queryMap));
+    }
 }

rest/src/main/java/org/n52/web/ctrl/ParameterController.java

@@ -132,20 +132,22 @@ private Collection<String> checkForOverridingData(Map<String, Object> data, Map<
     }
 
     @Override
-    public ModelAndView getCollection(String locale, MultiValueMap<String, String> query) {
+    public ModelAndView getCollection(HttpServletResponse response,
+                                      String locale,
+                                      MultiValueMap<String, String> query) {
         RequestUtils.overrideQueryLocaleWhenSet(locale, query);
         IoParameters queryMap = QueryParameters.createFromQuery(query);
         LOGGER.debug("getCollection() with query '{}'", queryMap);
+        OutputCollection<T> result;
 
         if (queryMap.isExpanded()) {
             Stopwatch stopwatch = Stopwatch.startStopwatch();
-            OutputCollection<T> result = addExtensionInfos(parameterService.getExpandedParameters(queryMap));
+            result = addExtensionInfos(parameterService.getExpandedParameters(queryMap));
             LOGGER.debug("Processing request took {} seconds.", stopwatch.stopInSeconds());
-            return createModelAndView(result);
         } else {
-            OutputCollection<T> results = parameterService.getCondensedParameters(queryMap);
-            return createModelAndView(results);
+            result = parameterService.getCondensedParameters(queryMap);
         }
+        return createModelAndView(result);
     }
 
     @Override

rest/src/main/java/org/n52/web/ctrl/ParameterRequestMappingAdapter.java

@@ -31,13 +31,23 @@
 
 import java.util.Collections;
 import java.util.Map;
+import java.util.Optional;
 
 import javax.servlet.http.HttpServletResponse;
 
+import org.n52.io.request.IoParameters;
+
 import org.n52.io.request.Parameters;
+import org.n52.io.request.QueryParameters;
 import org.n52.io.response.ParameterOutput;
+import org.n52.io.response.pagination.OffsetBasedPagination;
+import org.n52.io.response.pagination.Paginated;
+import org.n52.io.response.pagination.Pagination;
+import org.n52.series.spi.srv.CountingMetadataService;
 import org.n52.series.spi.srv.RawFormats;
 import org.n52.web.common.RequestUtils;
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.beans.factory.annotation.Qualifier;
 import org.springframework.util.MultiValueMap;
 import org.springframework.web.bind.annotation.PathVariable;
 import org.springframework.web.bind.annotation.RequestHeader;
@@ -51,12 +61,27 @@
 })
 public abstract class ParameterRequestMappingAdapter<T extends ParameterOutput> extends ParameterController<T> {
 
+    @Autowired
+    @Qualifier("metadataService")
+    private CountingMetadataService counter;
+
     @Override
     @RequestMapping(path = "")
-    public ModelAndView getCollection(@RequestHeader(value = Parameters.HttpHeader.ACCEPT_LANGUAGE,
-        required = false) String locale,
+    public ModelAndView getCollection(HttpServletResponse response,
+                                      @RequestHeader(value = Parameters.HttpHeader.ACCEPT_LANGUAGE,
+                                          required = false) String locale,
                                       @RequestParam MultiValueMap<String, String> query) {
-        return super.getCollection(locale, addHrefBase(query));
+        IoParameters queryMap = QueryParameters.createFromQuery(query);
+        if (queryMap.containsParameter(Parameters.LIMIT) || queryMap.containsParameter(Parameters.OFFSET)) {
+            Integer elementcount = this.getElementCount(queryMap.removeAllOf(Parameters.LIMIT)
+                                                                .removeAllOf(Parameters.OFFSET));
+            if (0 >= elementcount) {
+                OffsetBasedPagination obp = new OffsetBasedPagination(queryMap.getOffset(), queryMap.getLimit());
+                Paginated<T> paginated = new Paginated<>(obp, elementcount.longValue());
+                this.addPagingHeaders(this.getCollectionPath(this.getHrefBase()), response, paginated);
+            }
+        }
+        return super.getCollection(null, locale, addHrefBase(query));
     }
 
     @Override
@@ -92,9 +117,46 @@ public Map<String, Object> getExtras(@PathVariable("item") String resourceId,
     }
 
     protected MultiValueMap<String, String> addHrefBase(MultiValueMap<String, String> query) {
-        String externalUrl = getExternalUrl();
-        String hrefBase = RequestUtils.resolveQueryLessRequestUrl(externalUrl);
-        query.put(Parameters.HREF_BASE, Collections.singletonList(hrefBase));
+        query.put(Parameters.HREF_BASE, Collections.singletonList(getHrefBase()));
         return query;
     }
+
+    private String getHrefBase() {
+        return RequestUtils.resolveQueryLessRequestUrl(getExternalUrl());
+    }
+
+    /**
+     * @param queryMap
+     *        the query map
+     * @return the number of elements available, or negative number if paging is not supported.
+     */
+    protected abstract int getElementCount(IoParameters queryMap);
+
+    protected CountingMetadataService getEntityCounter() {
+        return counter;
+    }
+
+    private HttpServletResponse addPagingHeaders(String href, HttpServletResponse response, Paginated<T> paginated) {
+        addLinkHeader("self", href, paginated.getCurrent(), response);
+        addLinkHeader("previous", href, paginated.getPrevious(), response);
+        addLinkHeader("next", href, paginated.getNext(), response);
+        addLinkHeader("first", href, paginated.getFirst(), response);
+        addLinkHeader("last", href, paginated.getLast(), response);
+        return response;
+    }
+
+    private void addLinkHeader(String rel, String href, Optional<Pagination> pagination, HttpServletResponse response) {
+        if (pagination.isPresent()) {
+            String header = "Link";
+            String value = "<"
+                    + href
+                    + "?"
+                    + pagination.get()
+                                .toString()
+                    + "> rel=\""
+                    + rel
+                    + "\"";
+            response.addHeader(header, value);
+        }
+    }
 }

rest/src/main/java/org/n52/web/ctrl/PhenomenaParameterController.java

@@ -29,6 +29,7 @@
 package org.n52.web.ctrl;
 
 
+import org.n52.io.request.IoParameters;
 import org.n52.io.response.PhenomenonOutput;
 import org.springframework.web.bind.annotation.RequestMapping;
 import org.springframework.web.bind.annotation.RestController;
@@ -37,4 +38,14 @@
 @RequestMapping(path = UrlSettings.COLLECTION_PHENOMENA)
 public class PhenomenaParameterController extends ParameterRequestMappingAdapter<PhenomenonOutput> {
 
+    @Override
+    public String getCollectionPath(String hrefBase) {
+        UrlHelper urlhelper = new UrlHelper();
+        return urlhelper.constructHref(hrefBase, UrlSettings.COLLECTION_PHENOMENA);
+    }
+
+    @Override
+    protected int getElementCount(IoParameters queryMap) {
+        return super.getEntityCounter().getPhenomenaCount(IoParameters.ensureBackwardsCompatibility(queryMap));
+    }
 }

rest/src/main/java/org/n52/web/ctrl/PlatformsParameterController.java

@@ -28,6 +28,7 @@
  */
 package org.n52.web.ctrl;
 
+import org.n52.io.request.IoParameters;
 import org.n52.io.response.PlatformOutput;
 import org.springframework.web.bind.annotation.RequestMapping;
 import org.springframework.web.bind.annotation.RestController;
@@ -36,4 +37,14 @@
 @RequestMapping(path = UrlSettings.COLLECTION_PLATFORMS)
 public class PlatformsParameterController extends ParameterRequestMappingAdapter<PlatformOutput> {
 
+    @Override
+    public String getCollectionPath(String hrefBase) {
+        UrlHelper urlhelper = new UrlHelper();
+        return urlhelper.constructHref(hrefBase, UrlSettings.COLLECTION_PLATFORMS);
+    }
+
+    @Override
+    protected int getElementCount(IoParameters queryMap) {
+        return super.getEntityCounter().getPlatformCount(queryMap);
+    }
 }