@masterportal/masterportalapi 2.7.0 → 2.8.0

package/CHANGELOG.md

@@ -5,13 +5,24 @@
 
 ## Unreleased - in development
 ### Added
+
 ### Changed
 
 ### Deprecated
 
 ### Removed
+
 ### Fixed
 
+---
+
+## 2.8.0 - 2022-10-04
+### Added
+- Issue #814: Adding optional error callbacks and availability detection to layers.
+- Added possibility to set initial features for layer vectorBase.
+
+---
+
 ## 2.7.0 - 2022-09-14
 ### Changed
 - The following packages have been updated:

package/README.md

@@ -10,6 +10,13 @@ If you want to create a 3d map, you have to provide the peer dependency cesium.
 
 By importing the project by module name like ``import ... from "masterportalAPI"``, most bundlers and bundler configurations will include the whole masterportalAPI. If you only need a subset of the provided functions and want to keep your build clean, directly import the needed functions like ``import {createMap} from "masterportalAPI/src/map.js``.
 
+## Error Handling
+
+1. Error event callback: The methods `createMap` and `addLayer` both optionally accept error event callbacks that are called with OpenLayers error events (tileloaderror, imageloaderror, featuresloaderror, error).
+2. Ping: A method that returns a Promise. This resolves to the status code of the layer's GetCapabilities request, which can be used to decide if the service is reachable and usable at all.
+
+Both methods may be required for useful user feedback. For example, a WMS may answer a tile request with 404 if no tile is available for a region, but may be fully available within its specification. This may throw an error while the service itself is available as specified. It is up to the using implementation how to react, how often to ping, and so on.
+
 ## Scripts
 
 |Script|Effect|

package/example/config/services.json

@@ -47,7 +47,7 @@
   {
     "id": "4001",
     "name": "Gelaende",
-    "url": "https://daten-hamburg.de/gdi3d/datasource-data/Gelaende ",
+    "url": "https://daten-hamburg.de/gdi3d/datasource-data/Gelaende",
     "typ": "Terrain3D",
     "cesiumTerrainProviderOptions": {
       "requestVertexNormals": true

package/example/index.js

@@ -11,6 +11,10 @@ import portalConfig from "./config/portal.json";
 import localGeoJSON from "./config/localGeoJSON.js";
 import {load3DScript} from "../src/lib/load3DScript";
 
+function errorCallback (errorEvent) {
+    console.error("This is an error event:", errorEvent);
+}
+
 //* Add elements to window to play with API in console
 window.mpapi = {
     ...mpapi,
@@ -94,7 +98,7 @@ document.getElementById("layer-visibility").addEventListener("click", function (
     });
 });
 
-map2D = mapsAPI.map.createMap(config, "2D");
+map2D = mapsAPI.map.createMap(config, "2D", {errorCallback});
 services.push(localService);
 // */
 
@@ -148,7 +152,18 @@ services.find(({id}) => id === "5001").style = styleOaf;
 //* SYNCHRONOUS EXAMPLE: layerConf is known
 window.mpapi.map = map2D;
 
-["2001", "2002", "1002", "3001", "5001"].forEach(id => window.mpapi.map.addLayer(id));
+["2001", "2002", "1002", "3001", "5001"].forEach(id => window.mpapi.map.addLayer(id, {errorCallback}));
+
+// ping all layers
+services
+    .map(service => ({
+        ping: mpapi.ping(service),
+        service
+    }))
+    .forEach(({ping, service}) => ping
+        // eslint-disable-next-line no-console
+        .then(statusCode => console.log(`Service ${service.id} pinged; returned ${statusCode}.`))
+        .catch(console.error));
 
 // */
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@masterportal/masterportalapi",
   "author": "Implementierungspartnerschaft Masterportal <info@masterportal.org> (https://www.masterportal.org)",
-  "version": "2.7.0",
+  "version": "2.8.0",
   "license": "MIT",
   "description": "Basic functions of the Masterportal as api",
   "repository": {
@@ -58,5 +58,9 @@
   },
   "bugs": {
     "url": "https://bitbucket.org/geowerkstatt-hamburg/masterportalapi/issues"
-  }
+  },
+  "keywords": [
+    "geo",
+    "map"
+  ]
 }

package/src/index.js

@@ -14,6 +14,7 @@ import Tileset from "./layer/tileset";
 import * as layerLib from "./layer/lib";
 import {search, setGazetteerUrl} from "./searchAddress";
 import setBackgroundImage from "./lib/setBackgroundImage";
+import ping from "./lib/ping";
 
 export {
     createMapView,
@@ -31,6 +32,7 @@ export {
     setBackgroundImage,
     setGazetteerUrl,
     rawLayerList,
+    ping,
     search,
     crs
 };

package/src/lib/ping.js

@@ -0,0 +1,63 @@
+/**
+ * Helper function to detect layer availability/usability. Depending on layer
+ * type, the method to infer availability broadly varies.
+ * @param {Object} layerSpecification services.json layer specification
+ * @returns {Promise} resolves to status code of a layer-specific default
+ * request as Number, or null if no request could be made, which should
+ * indicate misconfiguration; defaults to 900 if the request itself failed for
+ * arbitrary reasons (usually CORS-related)
+ */
+export default function ({url, typ, capabilitiesUrl, ...rest}) {
+    const statusCheckUrls = [];
+
+    if (capabilitiesUrl) {
+        statusCheckUrls.push(capabilitiesUrl);
+    }
+    else if (typ === "OAF") {
+        statusCheckUrls.push(url);
+    }
+    else if (typ === "Entities3D") {
+        rest.entities
+            .forEach(entity => entity.url ? statusCheckUrls.push(entity.url) : null);
+    }
+    else if (typ === "TileSet3D" || typ === "Terrain3D") {
+        statusCheckUrls.push(url);
+    }
+    else if (typ === "GeoJSON") {
+        if (!url && rest.features) {
+            // may be a local layer without source url – that's equal to 200
+            return Promise.resolve(200);
+        }
+        if (url) {
+            statusCheckUrls.push(url);
+        }
+    }
+    else if (typ === "VectorTile") {
+        statusCheckUrls.push(url.replaceAll(/\{[xyz]\}/ig, "0"));
+    }
+    else if (typ === "WMTS") {
+        const arbitraryTileRequests = (url ? [url] : rest.urls)
+            .map(entry => entry
+                .replace(/\{Style\}/ig, rest.style)
+                .replace(/\{TileMatrixSet\}/ig, rest.tileMatrixSet)
+                .replaceAll(/\{(TileMatrix|TileRow|TileCol)\}/ig, "0"));
+
+        statusCheckUrls.push(...arbitraryTileRequests);
+    }
+    else if (url) {
+        statusCheckUrls.push(`${url}?service=${typ}&request=GetCapabilities`);
+    }
+
+    if (!statusCheckUrls.length) {
+        return Promise.resolve(null);
+    }
+
+    return Promise
+        .allSettled(statusCheckUrls
+            .map(statusCheckUrl => new Promise((resolve) => fetch(statusCheckUrl, {method: "HEAD"})
+                .then(({status}) => resolve(status))
+                // usually from CORS, treated as 900 here ("proprietary" status code)
+                .catch(() => resolve(900)))))
+        // return highest status code (will indicate erroneous behaviour)
+        .then(codes => Math.max(...codes.map(({value}) => value)));
+}

package/src/maps/map.js

@@ -20,6 +20,7 @@ export default {
     * @param {object}  [settings={}] - settings object
     * @param {object} [settings.mapParams] - additional parameter object that is spread into the ol.Map constructor object
     * @param {function} [settings.callback] - optional callback for layer list loading
+    * @param {function} [settings.errorCallback] - optional callback for layer error events
     * @returns {module:ol/Map~Map} The map.
     */
     createMap: function (config, mapMode = "2D", settings = {}) {

package/src/maps/ol/olMap.js

@@ -32,6 +32,48 @@ const layerBuilderMap = {
     },
     originalAddLayer = Map.prototype.addLayer;
 
+/**
+ * Flattens a Layer/LayerGroup to an array of non-group instances.
+ * @param {ol/layer/Base} layer any layer, possibly a LayerGroup
+ * @returns {ol/layer/Base[]} array of all given layers
+ */
+function flattenLayerGroups (layer) {
+    return layer.getLayers
+        ? layer
+            .getLayers()
+            .getArray()
+            .map(l => flattenLayerGroups(l))
+            .flat(1)
+        : [layer];
+}
+
+/**
+ * Adds an error handling function to an arbitrary layer. The event will be
+ * registered to the tileloaderror, imageloaderror, featuresloaderror, and
+ * generic error event. Depending on the type of layer and error, only one of
+ * these events will fire.
+ * @param {ol/layer/Base} layer Any type of layer implemented.
+ * @param {Function} errorCallback Error callback, called from OL event.
+ * @returns {void} side-effect to layer
+ */
+function injectErrorCallback (layer, errorCallback) {
+    const layers = flattenLayerGroups(layer);
+
+    layers.forEach(l => {
+        const source = l.getSource?.();
+
+        if (source) {
+            source.on?.("tileloaderror", errorCallback);
+            source.on?.("imageloaderror", errorCallback);
+            source.on?.("featuresloaderror", errorCallback);
+            source.on?.("error", errorCallback);
+        }
+        else {
+            console.error("Could not register error callback on layer:", l);
+        }
+    });
+}
+
 /**
  * Adds a layer to the map, or adds a layer to the map by id.
  * This id is looked up within the array of all known services.
@@ -40,14 +82,18 @@ const layerBuilderMap = {
  * if you request the services from the internet.
  *
  * This function is available on all ol/Map instances.
- * @param {(string|ol/Layer)} layerOrId - if of layer to add to map
+ * @param {(string|ol/layer/Base)} layerOrId - if of layer to add to map
  * @param {object} [params] - optional parameter object
  * @param {boolean} [params.visibility=true] - whether added layer is initially visible
  * @param {Number} [params.transparency=0] - how visible the layer is initially
+ * @param {Function} [params.errorCallback=console.error] - callback for layer source error events
  * @returns {?ol.Layer} added layer
  */
-function addLayer (layerOrId, params = {visibility: true, transparency: 0}) {
-    var layer, layerBuilder;
+function addLayer (layerOrId, params = {visibility: true, transparency: 0, errorCallback: console.error}) {
+    const errorCallback = typeof params.errorCallback === "function"
+        ? params.errorCallback
+        : console.error;
+    let layer, layerBuilder;
 
     // if parameter is id, create and add layer with masterportalAPI mechanisms
     if (typeof layerOrId === "string") {
@@ -65,11 +111,13 @@ function addLayer (layerOrId, params = {visibility: true, transparency: 0}) {
         layer = layerBuilder.createLayer(rawLayer, {}, {map: this});
         layer.setVisible(typeof params.visibility === "boolean" ? params.visibility : true);
         layer.setOpacity(typeof params.transparency === "number" ? (100 - params.transparency) / 100 : 1);
+        injectErrorCallback(layer, errorCallback);
         originalAddLayer.call(this, layer);
         return layer;
     }
 
     // else use original function
+    injectErrorCallback(layerOrId, errorCallback);
     return originalAddLayer.call(this, layerOrId);
 }
 
@@ -93,10 +141,11 @@ Map.prototype.addLayer = addLayer;
  * @param {object}  [settings={}] - setings object
  * @param {object} [settings.mapParams] - additional parameter object that is spread into the ol.Map constructor object
  * @param {function} [settings.callback] - optional callback for layer list loading
+ * @param {function} [settings.errorCallback] – method called on error events
  * @param {String} [mapMode = "2D"] The map mode. '2D' to craete a 2D-map and '3D' to create a 3D-map.
  * @returns {object} map object from ol
  */
-export function createMap (config = defaults, {mapParams, callback} = {}) {
+export function createMap (config = defaults, {mapParams, callback, errorCallback} = {}) {
     registerProjections(config.namedProjections);
     setBackgroundImage(config);
     setGazetteerUrl(config.gazetteerUrl);
@@ -114,7 +163,7 @@ export function createMap (config = defaults, {mapParams, callback} = {}) {
     initializeLayerList(config.layerConf, (param, error) => {
         getInitialLayers(config)
             .forEach(layer => {
-                map.addLayer(layer.id, layer);
+                map.addLayer(layer.id, {errorCallback});
             });
 
         if (typeof callback === "function") {

package/test/layer/wmts.test.js

@@ -3,7 +3,7 @@ import {getWidth} from "ol/extent";
 
 import * as wmts from "../../src/layer/wmts";
 
-describe.only("wmts.js", function () {
+describe("wmts.js", function () {
     describe("generateArrays", function () {
         it("should fill the arrays resolutions and matrixIds with numbers", function () {
             const size = getWidth(getProjection("EPSG:3857").getExtent()) / 256,

package/test/lib/ping.test.js

@@ -0,0 +1,69 @@
+import ping from "../../src/lib/ping";
+
+const originalFetch = global.fetch;
+
+describe("ping.js", function () {
+    let mockFetch;
+
+    beforeEach(() => {
+        mockFetch = jest.fn(() => Promise.resolve({
+            status: 200
+        }));
+        global.fetch = mockFetch;
+    });
+
+    afterAll(() => {
+        global.fetch = originalFetch;
+    });
+
+    describe("ping", function () {
+        it("calls an url from the service definition", async function () {
+            const status = await ping({url: "www.example.com", typ: "WMS"});
+
+            expect(status).toBe(200);
+            expect(mockFetch).toHaveBeenCalledWith("www.example.com?service=WMS&request=GetCapabilities", {method: "HEAD"});
+        });
+
+        it("calls 0/0/0 tile for VectorTile services", async function () {
+            const status = await ping({url: "www.example.com/{x}/{y}/{z}", typ: "VectorTile"});
+
+            expect(status).toBe(200);
+            expect(mockFetch).toHaveBeenCalledWith("www.example.com/0/0/0", {method: "HEAD"});
+        });
+
+        it("calls the URL directly for OAF services", async function () {
+            const status = await ping({url: "www.example.com", typ: "OAF"});
+
+            expect(status).toBe(200);
+            expect(mockFetch).toHaveBeenCalledWith("www.example.com", {method: "HEAD"});
+        });
+
+        it("returns 900 on network errors", async function () {
+            mockFetch = jest.fn(() => Promise.resolve({status: 900}));
+            global.fetch = mockFetch;
+
+            const status = await ping({url: "www.example.com", typ: "OAF"});
+
+            expect(status).toBe(900);
+            expect(mockFetch).toHaveBeenCalledWith("www.example.com", {method: "HEAD"});
+        });
+
+        it("returns highest status code on multiple urls", async function () {
+            let counter = 200;
+
+            mockFetch = jest.fn(() => Promise.resolve({status: counter++}));
+            global.fetch = mockFetch;
+
+            const status = await ping({urls: [
+                "www.example.com",
+                "www.example.com/but"
+            ], typ: "WMTS"});
+
+            expect(status).toBe(201);
+            expect(mockFetch)
+                .toHaveBeenCalledWith("www.example.com", {method: "HEAD"});
+            expect(mockFetch)
+                .toHaveBeenCalledWith("www.example.com/but", {method: "HEAD"});
+        });
+    });
+});