Merge remote-tracking branch 'origin/development'. v0.3.3

Author: m-mohr

README.md

@@ -4,21 +4,85 @@ JavaScript client for the openEO API.
 
 [![Build Status](https://travis-ci.org/Open-EO/openeo-js-client.svg?branch=master)](https://travis-ci.org/Open-EO/openeo-js-client)
 
-This client is in **version 0.3.2** and supports **openEO API versions 0.3.0 and 0.3.1**. Legacy versions are available as releases.
+This client is in **version 0.3.3** and supports **openEO API versions 0.3.0 and 0.3.1**. Legacy versions are available as releases.
 
 ## Usage
 This library can run in a recent browser supporting ECMAScript 2015 or node.js.
 
 To use it in a browser environment simply add the following code to your HTML file:
-```
+```html
 <script src="https://cdn.jsdelivr.net/npm/axios/dist/axios.min.js"></script>
 <script src="https://cdn.jsdelivr.net/npm/@openeo/js-client/openeo.js"></script>
 ```
 
-To install it with npm: `npm install @openeo/js-client`
+To install it with npm run: `npm install @openeo/js-client`
+
+### Running a job
+
+```js
+// Import the library if running in a nodeJS environment
+// const { OpenEO } = require('@openeo/js-client');
+
+var obj = new OpenEO();
+// Show the client version
+console.log("Client Version: " +obj.version());
+
+try {
+  // Connect to the back-end
+  var con = await obj.connect("https://earthengine.openeo.org/v0.3", "basic", {username: "group1", password: "test123"});
+
+  // Show implemented API version of the back-end
+  var capabilities = await con.capabilities();
+  console.log("Server API version: " +capabilities.version());
+
+  // List collection names
+  var collections = await con.listCollections();
+  console.log("Collections: " +collections.collections.map(c => c.name));
+
+  // List process ids
+  var processes = await con.listProcesses();
+  console.log("Processes: " + processes.processes.map(p => p.name));
+  
+  // List supported file types
+  var fileTypes = await con.listFileTypes();
+  console.log("Files types: " + Object.keys(fileTypes.formats));
+  
+  // Check whether synchronous previews are supported
+  var syncSupport = capabilities.hasFeature("execute");
+  console.log("Synchronous previews: " + (syncSupport ? "supported" : "NOT supported"));
+  
+  // Request a preview synchronously for a process graph
+  if (syncSupport) {
+    // Derives maximum NDVI measurements over pixel time series of Sentinel 2 imagery
+    var processGraph = {
+      "imagery": {
+        "red": "B4",
+        "nir": "B8",
+        "imagery": {
+          "extent": ["2018-12-01T00:00:00Z","2018-12-31T23:59:59Z"],
+          "imagery": {
+            "extent": {"west": 8.265169,"south": 52.453917,"east": 8.42035,"north": 52.576767},
+            "imagery": {
+              "process_id": "get_collection",
+              "name": "COPERNICUS/S2"
+            },
+            "process_id": "filter_bbox"
+          },
+          "process_id": "filter_daterange"
+        },
+        "process_id": "NDVI"
+      },
+      "process_id": "max_time"
+    };
+  	var preview = await con.execute(processGraph, "png");
+  	// This returns a Blob object with data you could further process or show.
+  }
+} catch(e) {
+  console.log(e);
+}
+```
+
 
-Dependencies required to run the openEO JS client:
-* [axios](https://github.com/axios/axios)
 
 ## Interactive JS Editor
 

openeo.js

@@ -15,7 +15,7 @@ class OpenEO {
 		var connection = new Connection(url);
 		return connection.capabilities().then(capabilities => {
 			// Check whether back-end is accessible and supports a correct version.
-			if (capabilities.version().startsWith("0.3")) {
+			if (capabilities.version().startsWith("0.3.")) {
 				if(authType !== null) {
 					switch(authType) {
 						case 'basic':
@@ -35,7 +35,7 @@ class OpenEO {
 	}
 
 	version() {
-		return "0.3.2";
+		return "0.3.3";
 	}
 }
 
@@ -113,22 +113,12 @@ class Connection {
 		return Promise.reject(new Error("Not implemented yet."));
 	}
 
-	_base64encode(str) {
-		var buffer;
-		if (str instanceof Buffer) {
-			buffer = str;
-		} else {
-			buffer = Buffer.from(str.toString(), 'binary');
-		}
-		return buffer.toString('base64');
-	}
-
 	authenticateBasic(username, password) {
 		return this._send({
 			method: 'get',
 			responseType: 'json',
 			url: '/credentials/basic',
-			headers: {'Authorization': 'Basic ' + this._base64encode(username + ':' + password)}  // btoa is JS's ugly name for encodeBase64
+			headers: {'Authorization': 'Basic ' + Util.base64encode(username + ':' + password)}
 		}).then(response => {
 			if (!response.data.user_id) {
 				throw new Error("No user_id returned.");
@@ -403,41 +393,6 @@ class Connection {
 	unsubscribe(topic, parameters, callback) {
 		return this.subscriptionsObject.unsubscribe(topic, parameters, callback);
 	}
-
-	_saveToFileNode(data, filename) {
-		var fs = require('fs');
-		return new Promise((resolve, reject) => {
-			var writeStream = fs.createWriteStream(filename);
-			writeStream.on('close', (err) => {
-				if (err) {
-					return reject(err);
-				}
-				resolve();
-			});
-			data.pipe(writeStream);
-		});
-	}
-
-	/* istanbul ignore next */
-	_saveToFileBrowser(data, filename) {
-		// based on: https://github.com/kennethjiang/js-file-download/blob/master/file-download.js
-		var blob = new Blob([data], {type: 'application/octet-stream'});
-		var blobURL = window.URL.createObjectURL(blob);
-		var tempLink = document.createElement('a');
-		tempLink.style.display = 'none';
-		tempLink.href = blobURL;
-		tempLink.setAttribute('download', filename); 
-		
-		if (typeof tempLink.download === 'undefined') {
-			tempLink.setAttribute('target', '_blank');
-		}
-		
-		document.body.appendChild(tempLink);
-		tempLink.click();
-		document.body.removeChild(tempLink);
-		window.URL.revokeObjectURL(blobURL);
-		return Promise.resolve();
-	}
 }
 
 
@@ -461,7 +416,7 @@ class Subscriptions {
 			if(!this.listeners.has(topic)) {
 				this.listeners.set(topic, new Map());
 			}
-			this.listeners.get(topic).set(JSON.stringify(parameters), callback);
+			this.listeners.get(topic).set(Util.hash(parameters), callback);
 		}
 
 		this._sendSubscription('subscribe', topic, parameters);
@@ -477,7 +432,7 @@ class Subscriptions {
 
 		// remove the applicable sub-callback
 		if(topicListeners instanceof Map) {
-			topicListeners.delete(JSON.stringify(parameters));
+			topicListeners.delete(Util.hash(parameters));
 		} else {
 			return Promise.reject(new Error("this.listeners must be a Map of Maps"));
 		}
@@ -539,8 +494,8 @@ class Subscriptions {
 			var callback;
 			// we should now have a Map in which to look for the correct listener
 			if (topicListeners && topicListeners instanceof Map) {
-				callback = topicListeners.get('{}')   // default: without parameters
-						|| topicListeners.get('{"job_id":"' + json.payload.job_id + '"}');
+				callback = topicListeners.get(Util.hash({}))   // default: without parameters
+						|| topicListeners.get(Util.hash({job_id: json.payload.job_id}));
 						// more parameter checks possible
 			}
 			// if we now have a function, we can call it with the information
@@ -765,11 +720,11 @@ class File extends BaseEntity {
 
 	_saveToFile(data, filename) {
 		if (isNode) {
-			return this.connection._saveToFileNode(data, filename);
+			return Util.saveToFileNode(data, filename);
 		}
 		else {
 			/* istanbul ignore next */
-			return this.connection._saveToFileBrowser(data, filename);
+			return Util.saveToFileBrowser(data, filename);
 		}
 	}
 
@@ -901,7 +856,7 @@ class Job extends BaseEntity {
 					let parsedUrl = url.parse(link);
 					let targetPath = path.join(targetFolder, path.basename(parsedUrl.pathname));
 					let p = this.connection.download(link, false)
-						.then(response => this.connection._saveToFileNode(response.data, targetPath))
+						.then(response => Util.saveToFileNode(response.data, targetPath))
 						.then(() => files.push(targetPath));
 					promises.push(p);
 				}
@@ -976,9 +931,97 @@ class Service extends BaseEntity {
 	}
 }
 
+class Util {
+
+	static base64encode(str) {
+		if (typeof btoa === 'function') {
+			// btoa is JS's ugly name for encodeBase64
+			return btoa(str);
+		}
+		else {
+			var buffer;
+			if (str instanceof Buffer) {
+				buffer = str;
+			} else {
+				buffer = Buffer.from(str.toString(), 'binary');
+			}
+			return buffer.toString('base64');
+		}
+	}
+
+	// Non-crypthographic / unsafe hashing for objects
+	static hash(o) {
+		switch(typeof o) {
+			case 'boolean':
+				return Util.hashString("b:" + o.toString());
+			case 'number':
+				return Util.hashString("n:" + o.toString());
+			case 'string':
+				return Util.hashString("s:" + o);
+			case 'object':
+				if (o === null) {
+					return Util.hashString("n:");
+				}
+				else {
+					return Util.hashString(Object.keys(o).sort().map(k => "o:" + k + ":" + Util.hash(o[k])).join("::"));
+				}
+			default:
+				return Util.hashString(typeof o);
+		}
+	}
+
+	// See: https://en.wikipedia.org/wiki/Jenkins_hash_function
+	static hashString(b) {
+		for(var a=0,c=b.length;c--;) {
+			a+=b.charCodeAt(c);
+			a+=a<<10;
+			a^=a>>6;
+		}
+		a+=a<<3;
+		a^=a>>11;
+		a+=a<<15;
+		return ((a&4294967295)>>>0).toString(16);
+	}
+
+	static saveToFileNode(data, filename) {
+		var fs = require('fs');
+		return new Promise((resolve, reject) => {
+			var writeStream = fs.createWriteStream(filename);
+			writeStream.on('close', (err) => {
+				if (err) {
+					return reject(err);
+				}
+				resolve();
+			});
+			data.pipe(writeStream);
+		});
+	}
+
+	/* istanbul ignore next */
+	static saveToFileBrowser(data, filename) {
+		// based on: https://github.com/kennethjiang/js-file-download/blob/master/file-download.js
+		var blob = new Blob([data], {type: 'application/octet-stream'});
+		var blobURL = window.URL.createObjectURL(blob);
+		var tempLink = document.createElement('a');
+		tempLink.style.display = 'none';
+		tempLink.href = blobURL;
+		tempLink.setAttribute('download', filename); 
+		
+		if (typeof tempLink.download === 'undefined') {
+			tempLink.setAttribute('target', '_blank');
+		}
+		
+		document.body.appendChild(tempLink);
+		tempLink.click();
+		document.body.removeChild(tempLink);
+		window.URL.revokeObjectURL(blobURL);
+		return Promise.resolve();
+	}
+}
 
 let toExport = {
-	OpenEO: OpenEO
+	OpenEO: OpenEO,
+	Util: Util
 };
 
 // explanation: https://www.matteoagosti.com/blog/2013/02/24/writing-javascript-modules-for-both-browser-and-node/

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openeo/js-client",
-  "version": "0.3.2",
+  "version": "0.3.3",
   "author": "openEO Consortium",
   "contributors": [
     {
@@ -22,12 +22,12 @@
   },
   "main": "openeo.js",
   "devDependencies": {
-    "jest": "^23.5.0",
+    "jest": "^24.7.1",
     "jest-html-reporter": "^2.4.2"
   },
   "dependencies": {
     "axios": "^0.18.0",
-    "ws": "^6.1.2"
+    "ws": "^6.2.1"
   },
   "scripts": {
     "test": "jest basic.test.js --env=jsdom",

tests/basic.test.js

@@ -1,7 +1,7 @@
-const { OpenEO } = require('../openeo.js');
+const { OpenEO, Util } = require('../openeo.js');
 const packageInfo = require('../package.json');
 
-describe('Basic client tests', () => {
+describe('Client Basics', () => {
 	var obj = new OpenEO();
 	test('Check that import worked', () => {
 		expect(obj).not.toBeNull();
@@ -10,4 +10,24 @@ describe('Basic client tests', () => {
 	test('Check version number', () => {
 		expect(obj.version()).toBe(packageInfo.version);
 	});
+});
+	
+describe('Utils', () => {
+	test('Base64 encoder', () => {
+		expect(Util.base64encode(Buffer.from("test"))).toBe("dGVzdA==");
+		expect(Util.base64encode("test")).toBe("dGVzdA==");
+	});
+	test('Base64 encoder', () => {
+		expect(Util.base64encode(Buffer.from("test"))).toBe("dGVzdA==");
+		expect(Util.base64encode("test")).toBe("dGVzdA==");
+	});
+	test('String hashing', () => {
+		expect(Util.hashString("a")).toBe("ca2e9442");
+	});
+	test('Object hashing', () => {
+		expect(Util.hash(null)).toBe("40d6be39");
+		expect(Util.hash(123)).toBe("fd895d50");
+		expect(Util.hash({a:"b"})).toBe("2a0a2095");
+		expect(Util.hash([true])).toBe("7f0d24dd");
+	});
 });