@masterportal/masterportalapi 2.6.0 → 2.8.0

package/CHANGELOG.md

@@ -3,6 +3,35 @@
 
  The [Semantic Versioning](https://semver.org/spec/v2.0.0.html) is used.
 
+## 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:
+    - dependencies:
+        - ol: 6.15.1 to 7.1.0
+        - olcs: 2.13.0 to 2.13.1
+
+---
+
 ## 2.6.0 - 2022-09-06
 ### Added
 - Added possibility to set initial features for layer vectorBase.

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.6.0",
+  "version": "2.8.0",
   "license": "MIT",
   "description": "Basic functions of the Masterportal as api",
   "repository": {
@@ -20,8 +20,8 @@
   },
   "dependencies": {
     "core-js": "^3.24.0",
-    "ol": "6.15.1",
-    "olcs": "^2.13.0",
+    "ol": "7.1.0",
+    "olcs": "^2.13.1",
     "proj4": "^2.8.0",
     "xml2js": "^0.4.23"
   },
@@ -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/layer/vectorTile.js

@@ -21,7 +21,7 @@ const OL_DEFAULT_VECTOR_TILE_GRID_CRS = "EPSG:3857";
  * @property {number[]} [extent] - extent
  * @property {number} [maxZoom=22] - min zoom level
  * @property {number} [minZoom] - max zoom level
- * @property {function} [olAttribution] - optional function that takes a module:ol/PluggableMap~FrameState and returns a string or an array of strings representing source attributions
+ * @property {function} [olAttribution] - optional function that takes a module:ol/Map~FrameState and returns a string or an array of strings representing source attributions
  * @property {number[]} [origin] - The tile grid origin, i.e. where the x and y axes meet ([z, 0, 0]). Tile coordinates increase left to right and downwards
  * @property {number[][]} [origins] - Tile grid origins, i.e. where the x and y axes meet ([z, 0, 0]), for each zoom level. If given, the array length should match the length of the resolutions array, i.e. each resolution can have a different origin. Tile coordinates increase left to right and downwards. If not specified, extent or origin must be provided.
  * @property {number[]} [resolutions] - Resolutions. The array index of each resolution needs to match the zoom level. This means that even if a minZoom is configured, the resolutions array will have a length of maxZoom + 1.

package/src/layer/wms.js

@@ -80,7 +80,7 @@ export function makeParams (rawLayer) {
  * @param {string} [rawLayer.url] - WMS service URL
  * @param {string} [rawLayer.serverType] - optional servertype definition: "geoserver" or "mapserver" or "qgis"
  * @param {string} [rawLayer.gutter] - optional the size in pixels of the gutter around image tiles to ignore
- * @param {function} [rawLayer.olAttribution] - optional function that takes a module:ol/PluggableMap~FrameState and returns a string or an array of strings representing source attributions
+ * @param {function} [rawLayer.olAttribution] - optional function that takes a module:ol/Map~FrameState and returns a string or an array of strings representing source attributions
  * @param {string|number} [rawLayer.tilesize] - optional needed to create the tileGrid
  * @param {object} options - optional resolutions and origin to create the TileGrid
  * @param {Array} [options.resolutions] - optional resolutions to create the TileGrid, must be in descending order
@@ -128,7 +128,7 @@ export function createLayerSource (rawLayer, options) {
  * @param {string} [rawLayer.maxScale] - optional the maximal resolution
  * @param {string} [rawLayer.serverType] - optional servertype definition: "geoserver" or "mapserver" or "qgis"
  * @param {string} [rawLayer.gutter] - optional the size in pixels of the gutter around image tiles to ignore
- * @param {function} [rawLayer.olAttribution] - optional function that takes a module:ol/PluggableMap~FrameState and returns a string or an array of strings representing source attributions
+ * @param {function} [rawLayer.olAttribution] - optional function that takes a module:ol/Map~FrameState and returns a string or an array of strings representing source attributions
  * @param {string|number} [rawLayer.tilesize] - optional needed to create the tileGrid
  * @param {object} layerParams - additional layer params
  * @param {object} options - optional resolutions and origin to create the TileGrid

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,7 +20,8 @@ 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
-    * @returns {module:ol/PluggableMap~PluggableMap} The map.
+    * @param {function} [settings.errorCallback] - optional callback for layer error events
+    * @returns {module:ol/Map~Map} The map.
     */
     createMap: function (config, mapMode = "2D", settings = {}) {
         const createMapFunctions = {

package/src/maps/ol/olMap.js

@@ -1,4 +1,4 @@
-import {Map, PluggableMap} from "ol";
+import {Map} from "ol";
 import {defaults as olDefaultInteractions} from "ol/interaction.js";
 import setBackgroundImage from "../../lib/setBackgroundImage";
 import getInitialLayers from "../../lib/getInitialLayers";
@@ -30,7 +30,49 @@ const layerBuilderMap = {
         vectortile,
         oaf
     },
-    originalAddLayer = PluggableMap.prototype.addLayer;
+    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.
@@ -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,15 +111,17 @@ 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);
 }
 
-PluggableMap.prototype.addLayer = addLayer;
+Map.prototype.addLayer = addLayer;
 
 /**
  * Creates an openlayers map according to configuration. Does not set many default values itself, but uses function that do.
@@ -93,10 +141,11 @@ PluggableMap.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/src/maps/olcs/olcsMap.js

@@ -99,7 +99,7 @@ export function setCameraParameter (params, map3D, cesium) {
 /**
  * Creates a 3D-map.
  * @param {object} [settings] The settings for the 3D-map.
- * @param {module:ol/PluggableMap~PluggableMap} [settings.map2D] The 2D-Map
+ * @param {module:ol/Map~Map} [settings.map2D] The 2D-Map
  * @param {Cesium.JulianDate} [settings.shadowTime] The shadow time in julian date format if undefined olcs default is Cesium.JulianDate.now().
  * @returns {module:OLCesium} the 3d-map
  */

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"});
+        });
+    });
+});

package/test/map.test.js

@@ -1,4 +1,4 @@
-import {PluggableMap, Map} from "ol";
+import {Map} from "ol";
 import TileLayer from "ol/layer/Tile";
 import map from "../src/maps/map.js";
 import {createMap as create3DMap} from "../src/maps/olcs/olcsMap.js";
@@ -86,12 +86,12 @@ describe("map.js", function () {
         });
     });
 
-    // NOTE: loading map.js monkey patches PluggableMap.prototype.addLayer - testing result here
+    // NOTE: loading map.js monkey patches Map.prototype.addLayer - testing result here
     describe("addLayer", function () {
         it("logs an error for unknown ids", function () {
             console.error = jest.fn();
             const consoleError = console.error,
-                result = PluggableMap.prototype.addLayer("999999999999999");
+                result = Map.prototype.addLayer("999999999999999");
 
             expect(console.error).toHaveBeenCalled();
             expect(result).toBeNull();
@@ -101,7 +101,7 @@ describe("map.js", function () {
         it("logs an error for unknown types", function () {
             console.error = jest.fn();
             const consoleError = console.error,
-                result = PluggableMap.prototype.addLayer("exists");
+                result = Map.prototype.addLayer("exists");
 
             expect(result).toBeNull();
             expect(console.error).toHaveBeenCalledWith("Layer with id 'exists' has unknown type 'doesntExist'. No layer added to map.");
@@ -109,17 +109,17 @@ describe("map.js", function () {
         });
 
         it("creates existing layers that have a known builder", function () {
-            const result = PluggableMap.prototype.addLayer("works");
+            const result = Map.prototype.addLayer("works");
 
             expect(result).toBeInstanceOf(TileLayer);
         });
 
         it("sets visibility and transparency", function () {
-            const result1 = PluggableMap.prototype.addLayer("works"),
-                result2 = PluggableMap.prototype.addLayer("works", {}),
-                result3 = PluggableMap.prototype.addLayer("works", {visibility: false}),
-                result4 = PluggableMap.prototype.addLayer("works", {transparency: 50}),
-                result5 = PluggableMap.prototype.addLayer("works", {visibility: false, transparency: 20});
+            const result1 = Map.prototype.addLayer("works"),
+                result2 = Map.prototype.addLayer("works", {}),
+                result3 = Map.prototype.addLayer("works", {visibility: false}),
+                result4 = Map.prototype.addLayer("works", {transparency: 50}),
+                result5 = Map.prototype.addLayer("works", {visibility: false, transparency: 20});
 
             expect(result1.getOpacity()).toBe(1);
             expect(result1.getVisible()).toBe(true);