From e8fc6bd96ac02e3ac7e1781db6cdeaa7c7a0103e Mon Sep 17 00:00:00 2001
From: Johannes Visintini <johannes.visintini@heigit.org>
Date: Fri, 4 Nov 2022 11:59:56 +0100
Subject: [PATCH 01/15] Import oshdb-database-driver project

source: https://gitlab.gistools.geog.uni-heidelberg.de/giscience/big-data/ohsome/helpers/oshdb-database-driver/-/tree/prepare_release/
---
 .../oshdb-application-template/pom.xml        |  30 ++++
 .../applicationtemplate/OSHDBApplication.java | 101 ++++++++++++++
 .../applicationtemplate/PropsUtil.java        |  39 ++++++
 oshdb-helpers/oshdb-database-driver/pom.xml   |  27 ++++
 .../oshdb/helpers/db/OSHDBConnection.java     |  52 +++++++
 .../ohsome/oshdb/helpers/db/OSHDBDriver.java  | 130 ++++++++++++++++++
 .../heigit/ohsome/oshdb/helpers/db/Util.java  |  26 ++++
 oshdb-helpers/pom.xml                         |  24 ++++
 pom.xml                                       |   1 +
 9 files changed, 430 insertions(+)
 create mode 100644 oshdb-helpers/oshdb-application-template/pom.xml
 create mode 100644 oshdb-helpers/oshdb-application-template/src/main/java/org/heigit/ohsome/oshdb/helpers/applicationtemplate/OSHDBApplication.java
 create mode 100644 oshdb-helpers/oshdb-application-template/src/main/java/org/heigit/ohsome/oshdb/helpers/applicationtemplate/PropsUtil.java
 create mode 100644 oshdb-helpers/oshdb-database-driver/pom.xml
 create mode 100644 oshdb-helpers/oshdb-database-driver/src/main/java/org/heigit/ohsome/oshdb/helpers/db/OSHDBConnection.java
 create mode 100644 oshdb-helpers/oshdb-database-driver/src/main/java/org/heigit/ohsome/oshdb/helpers/db/OSHDBDriver.java
 create mode 100644 oshdb-helpers/oshdb-database-driver/src/main/java/org/heigit/ohsome/oshdb/helpers/db/Util.java
 create mode 100644 oshdb-helpers/pom.xml

diff --git a/oshdb-helpers/oshdb-application-template/pom.xml b/oshdb-helpers/oshdb-application-template/pom.xml
new file mode 100644
index 000000000..935597a99
--- /dev/null
+++ b/oshdb-helpers/oshdb-application-template/pom.xml
@@ -0,0 +1,30 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+  <modelVersion>4.0.0</modelVersion>
+
+  <parent>
+    <groupId>org.heigit.ohsome</groupId>
+    <artifactId>oshdb-helpers</artifactId>
+    <version>1.0.0-SNAPSHOT</version>
+  </parent>
+
+  <artifactId>oshdb-application-template</artifactId>
+  <name>OSHDB Application Template</name>
+  <description>TODO</description>
+  
+  <properties>
+  </properties>
+
+  <dependencies>
+    <dependency>
+      <groupId>${project.groupId}</groupId>
+      <artifactId>oshdb-database-driver</artifactId>
+      <version>${project.version}</version>
+    </dependency>
+    <dependency>
+      <groupId>info.picocli</groupId>
+      <artifactId>picocli</artifactId>
+      <version>4.6.3</version>
+    </dependency>
+  </dependencies>
+</project>
diff --git a/oshdb-helpers/oshdb-application-template/src/main/java/org/heigit/ohsome/oshdb/helpers/applicationtemplate/OSHDBApplication.java b/oshdb-helpers/oshdb-application-template/src/main/java/org/heigit/ohsome/oshdb/helpers/applicationtemplate/OSHDBApplication.java
new file mode 100644
index 000000000..96f6a17ac
--- /dev/null
+++ b/oshdb-helpers/oshdb-application-template/src/main/java/org/heigit/ohsome/oshdb/helpers/applicationtemplate/OSHDBApplication.java
@@ -0,0 +1,101 @@
+package org.heigit.ohsome.oshdb.helpers.applicationtemplate;
+
+import java.nio.file.Path;
+import java.util.Properties;
+import java.util.concurrent.Callable;
+import org.heigit.ohsome.oshdb.helpers.db.OSHDBConnection;
+import org.heigit.ohsome.oshdb.helpers.db.OSHDBDriver;
+import picocli.CommandLine;
+import picocli.CommandLine.ArgGroup;
+import picocli.CommandLine.Command;
+import picocli.CommandLine.Option;
+
+/**
+ * Class that can be used to bootstrap and launch a OSHDB application from a Java main method. By
+ * default will perform the following steps to bootstrap your application:
+ * <ul>
+ * <li>parse command line parameters</li>
+ * <li>connect to specified oshdb</li>
+ * </ul>
+ * In most circumstances the static run(Class, String[]) method can be called directly from your
+ * main method to bootstrap your application:
+ *
+ * <pre>
+ * {@code
+ * public class MyApplication extends OSHDBApplication {
+ *
+ *    public static void main(String[] args){
+ *      OSHDBApplication.run(MyApplication.class, args);
+ *    }
+ *
+ *    protected int run(OSHDBConnection oshdb){
+ *     oshdb.getSnapshotView()
+ *         .areaOfInterest((Geometry & Polygonal) areaOfInterest)
+ *         .timestamps(tstamps)
+ *         .osmTag(key)
+ *         ...
+ *     return 0; // exitCode
+ *    }
+ * }}
+ * </pre>
+ */
+@Command(mixinStandardHelpOptions = true, sortOptions = false)
+public abstract class OSHDBApplication implements Callable<Integer> {
+
+  @ArgGroup(exclusive=false, multiplicity= "1")
+  ConfigOrUrl configOrUrl;
+
+  static class ConfigOrUrl{
+    @Option(names = {"--props"}, description = ".properties file path")
+    protected Path config;
+
+    @Option(names = {"--oshdb"}, description = "oshdbUrl (ignite:...|h2:...)")
+    protected String oshdbUrl;
+  }
+
+  @Option(names = {"--keytables"}, description = "keytablesUrl jdbc:...")
+  protected String keytableUrl;
+
+  @Option(names = {"--prefix"}, description = "prefix to use")
+  protected String prefix;
+
+  @Option(names = {"--multithreading"}, description = "for jdbc based connections", negatable=true)
+  protected Boolean multithreading = null;
+
+  protected Properties props;
+
+  protected abstract int run(OSHDBConnection oshdb) throws Exception;
+
+  public static void run(Class<? extends OSHDBApplication> clazz, String[] args) {
+    try {
+      var app = clazz.getDeclaredConstructor().newInstance();
+      int exit = new CommandLine(app).execute(args);
+      System.exit(exit);
+    } catch (Exception e) {
+      e.printStackTrace();
+      System.exit(1);
+    }
+  }
+
+  @Override
+  public Integer call() throws Exception {
+    props = new Properties();
+    PropsUtil.load(props, configOrUrl.config);
+    PropsUtil.set(props, "oshdb", configOrUrl.oshdbUrl);
+    PropsUtil.set(props, "keytables", keytableUrl);
+    PropsUtil.set(props, "prefix", prefix);
+    PropsUtil.set(props, "multithreading", multithreading);
+    return OSHDBDriver.connect(props, this::setAndRun);
+  }
+
+  private int setAndRun(OSHDBConnection connection) throws Exception {
+    configOrUrl.oshdbUrl = PropsUtil.get(props, "oshdb").orElseThrow();
+    keytableUrl = PropsUtil.get(props, "keytables").orElse(null);
+    prefix = PropsUtil.get(props, "prefix").orElse("");
+    multithreading = Boolean.valueOf(PropsUtil.get(props, "multithreading").orElse("false"));
+    return run(connection);
+  }
+
+
+
+}
diff --git a/oshdb-helpers/oshdb-application-template/src/main/java/org/heigit/ohsome/oshdb/helpers/applicationtemplate/PropsUtil.java b/oshdb-helpers/oshdb-application-template/src/main/java/org/heigit/ohsome/oshdb/helpers/applicationtemplate/PropsUtil.java
new file mode 100644
index 000000000..981dbd666
--- /dev/null
+++ b/oshdb-helpers/oshdb-application-template/src/main/java/org/heigit/ohsome/oshdb/helpers/applicationtemplate/PropsUtil.java
@@ -0,0 +1,39 @@
+package org.heigit.ohsome.oshdb.helpers.applicationtemplate;
+
+import java.io.IOException;
+import java.nio.file.Files;
+import java.nio.file.Path;
+import java.nio.file.StandardOpenOption;
+import java.util.Optional;
+import java.util.Properties;
+
+public class PropsUtil {
+
+  private PropsUtil() {
+  }
+
+  public static void load(Properties props, Path path) throws IOException {
+    if (path != null && Files.exists(path)) {
+      try (var in = Files.newInputStream(path, StandardOpenOption.READ)) {
+        props.load(in);
+      }
+    }
+  }
+
+  public static void set(Properties props, String key, String value) {
+    if (value != null) {
+      props.put(key, value);
+    }
+  }
+
+  public static void set(Properties props, String key, Boolean value) {
+    if (value != null) {
+      props.setProperty(key, Boolean.toString(value));
+    }
+  }
+
+  public static Optional<String> get(Properties props, String key) {
+    return Optional.ofNullable(props.getProperty(key));
+  }
+
+}
diff --git a/oshdb-helpers/oshdb-database-driver/pom.xml b/oshdb-helpers/oshdb-database-driver/pom.xml
new file mode 100644
index 000000000..bbbd34a00
--- /dev/null
+++ b/oshdb-helpers/oshdb-database-driver/pom.xml
@@ -0,0 +1,27 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+  <modelVersion>4.0.0</modelVersion>
+
+  <parent>
+    <groupId>org.heigit.ohsome</groupId>
+    <artifactId>oshdb-helpers</artifactId>
+    <version>1.0.0-SNAPSHOT</version>
+  </parent>
+
+  <artifactId>oshdb-database-driver</artifactId>
+  <name>OSHDB Database Driver</name>
+  <description>TODO</description>
+
+  <properties>
+  </properties>
+
+  <dependencies>
+    <dependency>
+      <groupId>${project.groupId}</groupId>
+      <artifactId>oshdb-api-ignite</artifactId>
+      <version>${project.version}</version>
+      <scope>compile</scope>
+    </dependency>
+  </dependencies>
+
+</project>
diff --git a/oshdb-helpers/oshdb-database-driver/src/main/java/org/heigit/ohsome/oshdb/helpers/db/OSHDBConnection.java b/oshdb-helpers/oshdb-database-driver/src/main/java/org/heigit/ohsome/oshdb/helpers/db/OSHDBConnection.java
new file mode 100644
index 000000000..ff984595e
--- /dev/null
+++ b/oshdb-helpers/oshdb-database-driver/src/main/java/org/heigit/ohsome/oshdb/helpers/db/OSHDBConnection.java
@@ -0,0 +1,52 @@
+package org.heigit.ohsome.oshdb.helpers.db;
+
+import java.util.Properties;
+import org.heigit.ohsome.oshdb.api.db.OSHDBDatabase;
+import org.heigit.ohsome.oshdb.api.db.OSHDBJdbc;
+import org.heigit.ohsome.oshdb.api.mapreducer.MapReducer;
+import org.heigit.ohsome.oshdb.api.mapreducer.OSMContributionView;
+import org.heigit.ohsome.oshdb.api.mapreducer.OSMEntitySnapshotView;
+import org.heigit.ohsome.oshdb.util.exceptions.OSHDBKeytablesNotFoundException;
+import org.heigit.ohsome.oshdb.util.mappable.OSMContribution;
+import org.heigit.ohsome.oshdb.util.mappable.OSMEntitySnapshot;
+import org.heigit.ohsome.oshdb.util.tagtranslator.TagTranslator;
+
+public class OSHDBConnection {
+
+  private final Properties props;
+  private final OSHDBDatabase oshdb;
+  private final OSHDBJdbc keytables;
+  private final TagTranslator tagTranslator;
+
+  public OSHDBConnection(Properties props, OSHDBDatabase oshdb, OSHDBJdbc keytables)
+      throws OSHDBKeytablesNotFoundException {
+    this.props = props;
+    this.oshdb = oshdb;
+    this.keytables = keytables;
+    this.tagTranslator = new TagTranslator(keytables.getConnection());
+  }
+
+  public MapReducer<OSMContribution> getContributionView() {
+    return OSMContributionView.on(oshdb).keytables(keytables);
+  }
+
+  public MapReducer<OSMEntitySnapshot> getSnapshotView() {
+    return OSMEntitySnapshotView.on(oshdb).keytables(keytables);
+  }
+
+  public Properties getProps() {
+    return props;
+  }
+
+  public OSHDBDatabase getOSHDB() {
+    return oshdb;
+  }
+
+  public OSHDBJdbc getKeytables() {
+    return keytables;
+  }
+
+  public TagTranslator getTagTranslator() {
+    return tagTranslator;
+  }
+}
diff --git a/oshdb-helpers/oshdb-database-driver/src/main/java/org/heigit/ohsome/oshdb/helpers/db/OSHDBDriver.java b/oshdb-helpers/oshdb-database-driver/src/main/java/org/heigit/ohsome/oshdb/helpers/db/OSHDBDriver.java
new file mode 100644
index 000000000..b10108d4a
--- /dev/null
+++ b/oshdb-helpers/oshdb-database-driver/src/main/java/org/heigit/ohsome/oshdb/helpers/db/OSHDBDriver.java
@@ -0,0 +1,130 @@
+package org.heigit.ohsome.oshdb.helpers.db;
+
+import static org.heigit.ohsome.oshdb.helpers.db.Util.getInterpolated;
+
+import java.sql.DriverManager;
+import java.util.Properties;
+import org.apache.ignite.Ignite;
+import org.apache.ignite.Ignition;
+import org.heigit.ohsome.oshdb.api.db.OSHDBH2;
+import org.heigit.ohsome.oshdb.api.db.OSHDBIgnite;
+import org.heigit.ohsome.oshdb.api.db.OSHDBJdbc;
+
+/**
+ * A basic OSHDBDriver class for connecting to h2 or ignite oshdb instances.
+ *
+ * <pre>
+ * {@code
+ *     OSHDBDriver.connect(props, (oshdb) -> {
+ *         oshdb.getSnapshotView()
+ *         .areaOfInterest((Geometry & Polygonal) areaOfInterest)
+ *         .timestamps(tstamps)
+ *         .osmTag(key)
+ *          ...
+ *     });
+ * }
+ * </pre>
+ *
+ */
+public class OSHDBDriver {
+
+  private OSHDBDriver() {
+    throw new IllegalStateException("Driver class");
+  }
+
+  /**
+   * open connection to oshdb instance.
+   *
+   * @param props
+   *     <p>
+   *        props example:
+   *     </p>
+   *
+   *     <pre>
+   *     {@code
+   *       oshdb="ignite:Path_To_Config" \ "h2:Path_To_Database"
+   *       keytables="jdbc:postgresql://IP_OR_URL/keytables\${prefix}?user=ohsome&password=secret"
+   *       #multithreading default false, only used by h2 connections
+   *       multithreading=true
+   *     }
+   *     </pre>
+   * @param connect A Consumer for a OSHDBConnection e.g. a lambda
+   * @return exit code
+   * @throws java.lang.Exception
+   */
+  public static int connect(Properties props, Execute connect) throws Exception {
+    var oshdb = getInterpolated(props, "oshdb")
+        .orElseThrow(() ->  new IllegalArgumentException("need to have to specifiy oshdb!"));
+    if (oshdb.toLowerCase().startsWith("ignite:")) {
+      return connectToIgnite(props, connect);
+    } else if (oshdb.toLowerCase().startsWith("h2:")) {
+      return connectToH2(props, connect);
+    } else {
+      throw new IllegalArgumentException("unknown oshdb value! " + oshdb);
+    }
+  }
+
+  public static int connectToH2(Properties props, Execute connect)
+      throws Exception {
+    var prefix = getInterpolated(props, "prefix").orElse("");
+    props.put("prefix", prefix);
+    var h2 =
+        getInterpolated(props, "oshdb")
+        .map(value -> value.substring("h2:".length())).orElseThrow();
+    var multithreading =
+        getInterpolated(props, "multithreading").filter("true"::equalsIgnoreCase).isPresent();
+    return connectToH2(h2, prefix, multithreading, connect);
+  }
+
+  public static int connectToH2(String url, String prefix, Execute connect)
+      throws Exception {
+    return connectToH2(url, prefix, true, connect);
+  }
+
+  // OSHDBJdbc throws "Exception"
+  @SuppressWarnings("java:S112")
+  public static int connectToH2(String h2, String prefix, boolean multithreading,
+      Execute connect) throws Exception {
+    try (final var oshdb = new OSHDBH2(h2);
+        final var keyTables = new OSHDBJdbc(oshdb.getConnection())) {
+      oshdb.prefix(prefix);
+      oshdb.multithreading(multithreading);
+      var props = new Properties();
+      props.setProperty("oshdb", h2);
+      props.setProperty("prefix", prefix);
+      final var connection = new OSHDBConnection(props, oshdb, keyTables);
+      return connect.apply(connection);
+    }
+  }
+
+  // OSHDBJdbc throws "Exception"
+  @SuppressWarnings("java:S112")
+  private static int connectToIgnite(Properties props, Execute connect)
+      throws Exception {
+    var cfg = getInterpolated(props, "oshdb").filter(value -> value.toLowerCase().startsWith("ignite:"))
+        .map(value -> value.substring("ignite:".length())).orElseThrow();
+    try (var ignite = Ignition.start(cfg)) {
+      var prefix = getInterpolated(props, "prefix").orElseGet(() -> getActive(ignite));
+      props.put("prefix", prefix);
+      var keyTablesUrl = getInterpolated(props, "keytables")
+          .orElseThrow(() -> new IllegalArgumentException("missing keytables"));
+      props.put("keytables", keyTablesUrl);
+      try (var ktConnection = DriverManager.getConnection(keyTablesUrl);
+          var keytables = new OSHDBJdbc(ktConnection);
+          var oshdb = new OSHDBIgnite(ignite)) {
+        oshdb.prefix(prefix);
+        var connection = new OSHDBConnection(props, oshdb, keytables);
+        return connect.apply(connection);
+      }
+    }
+  }
+
+  private static String getActive(Ignite ignite) {
+    return ignite.<String, String>cache("ohsome").get("active");
+  }
+
+  @FunctionalInterface
+  public interface Execute {
+    int apply(OSHDBConnection oshdb) throws Exception;
+  }
+}
diff --git a/oshdb-helpers/oshdb-database-driver/src/main/java/org/heigit/ohsome/oshdb/helpers/db/Util.java b/oshdb-helpers/oshdb-database-driver/src/main/java/org/heigit/ohsome/oshdb/helpers/db/Util.java
new file mode 100644
index 000000000..8a9bcd8ae
--- /dev/null
+++ b/oshdb-helpers/oshdb-database-driver/src/main/java/org/heigit/ohsome/oshdb/helpers/db/Util.java
@@ -0,0 +1,26 @@
+package org.heigit.ohsome.oshdb.helpers.db;
+
+import java.util.Optional;
+import java.util.Properties;
+import java.util.regex.Pattern;
+
+public class Util {
+
+  private static final Pattern SUBSTITUTE = Pattern.compile("\\$\\{(\\w+)\\}");
+
+  private Util() {}
+  public static Optional<String> getInterpolated(Properties props, String key) {
+    return Optional.ofNullable(props.getProperty(key)).map(value -> interpolate(props, value));
+  }
+
+  private static String interpolate(Properties props, String value) {
+    var matcher = SUBSTITUTE.matcher(value);
+    var sb = new StringBuffer();
+    while (matcher.find()) {
+      var sub = matcher.group(1);
+      matcher.appendReplacement(sb, getInterpolated(props, sub).orElse("\\${" + sub + "}"));
+    }
+    matcher.appendTail(sb);
+    return sb.toString();
+  }
+}
diff --git a/oshdb-helpers/pom.xml b/oshdb-helpers/pom.xml
new file mode 100644
index 000000000..93af4514e
--- /dev/null
+++ b/oshdb-helpers/pom.xml
@@ -0,0 +1,24 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+  <modelVersion>4.0.0</modelVersion>
+
+  <parent>
+    <groupId>org.heigit.ohsome</groupId>
+    <artifactId>oshdb-parent</artifactId>
+    <version>1.0.0-SNAPSHOT</version>
+  </parent>
+
+  <artifactId>oshdb-helpers</artifactId>
+  <name>OSHDB Helpers</name>
+  <description>A collection of helpers to ease the usage of OSHDB in your own code.</description>
+  <packaging>pom</packaging>
+
+  <properties>
+  </properties>
+
+  <modules>
+    <module>oshdb-application-template</module>
+    <module>oshdb-database-driver</module>
+  </modules>
+
+</project>
\ No newline at end of file
diff --git a/pom.xml b/pom.xml
index 132a3a906..6856123b1 100644
--- a/pom.xml
+++ b/pom.xml
@@ -27,6 +27,7 @@
     <module>oshdb-api</module>
     <module>oshdb-api-ignite</module>
     <module>oshdb-tool</module>
+    <module>oshdb-helpers</module>
   </modules>
 
   <properties>

From 3e172ea30a56cc14d224bedc9f22d9802e17cd56 Mon Sep 17 00:00:00 2001
From: Johannes Visintini <johannes.visintini@heigit.org>
Date: Fri, 4 Nov 2022 13:54:44 +0100
Subject: [PATCH 02/15] integrate helper docs

source: https://gitlab.gistools.geog.uni-heidelberg.de/giscience/big-data/ohsome/helpers/oshdb-database-driver/-/tree/prepare_release/

Co-authored-by: Moritz Schott <moritz.schott@uni-heidelberg.de>
---
 .../manual/helpers/OSHDBApplication.md        | 84 +++++++++++++++++++
 documentation/manual/helpers/OSHDBDriver.md   | 71 ++++++++++++++++
 oshdb-helpers/README.md                       | 54 ++++++++++++
 3 files changed, 209 insertions(+)
 create mode 100644 documentation/manual/helpers/OSHDBApplication.md
 create mode 100644 documentation/manual/helpers/OSHDBDriver.md
 create mode 100644 oshdb-helpers/README.md

diff --git a/documentation/manual/helpers/OSHDBApplication.md b/documentation/manual/helpers/OSHDBApplication.md
new file mode 100644
index 000000000..e06f9a63f
--- /dev/null
+++ b/documentation/manual/helpers/OSHDBApplication.md
@@ -0,0 +1,84 @@
+# OSHDB Application
+
+Create a main Class extending on the `OSHDBApplication`
+
+```java
+public class MyApplication extends OSHDBApplication{
+
+    public static void main(String[] args) {}
+    
+    @Override
+    protected int run(OSHDBConnection oshdb) throws Exception {return 0;}
+    
+}
+```
+
+Activate you application by executing it in the `main` method
+
+```java
+    public static void main(String[] args) {
+        OSHDBApplication.run(MyApplication.class, args);
+    }
+```
+
+The `run` method now replaces your `main` method. You can add any functionality starting from there. The return value represents the status code. 0 signals a successful execution and should be the default.
+
+```java
+    @Override
+    protected int run(OSHDBConnection oshdb) throws Exception {
+        //your code goes here
+        return 0;
+    }
+```
+
+Other output (e.g. from the OSHDB query itself), needs to be handled within the method like writing it to a file, storing it in a database or printing it to the screen.
+
+To provide input to your application or query you can equally use the methods' body. Alternatively you can extend the predefined [picocli](https://picocli.info/) -based CLI with your own arguments
+
+```java
+    @CommandLine.Option(names = {"--myInput"}, description = "custom CLI input")
+    protected String input;
+
+    @Override
+    protected int run(OSHDBConnection oshdb) throws Exception {
+        System.out.println(this.input);
+```
+
+To run your application/query execute it in a command line. To configure the oshdb connection (see the [README.md](../../../README.md)) you can either use the provided CLI options (--oshdb, --prefix, --keytables), provide a '.properties' file (--props), or both. Any given CLI option will overwrite the properties provided in the file (if both paramters are present).
+
+## Example
+
+```java
+package mypackage;
+
+import org.heigit.ohsome.oshdb.OSHDBBoundingBox;
+import picocli.CommandLine;
+
+public class MyApplication extends OSHDBApplication {
+
+    public static void main(String[] args) {
+        OSHDBApplication.run(MyApplication.class, args);
+    }
+
+    @CommandLine.Option(defaultValue="2018-05-01", names = {"--ts"}, description = "target timestamp, default=${DEFAULT-VALUE}")
+    protected String ts;
+
+    @Override
+    protected int run(OSHDBConnection oshdb) throws Exception {
+        OSHDBBoundingBox bbox = OSHDBBoundingBox.bboxWgs84Coordinates(8.651133, 49.387611, 8.6561, 49.390513);
+        
+        Integer result = oshdb.getSnapshotView()
+                .areaOfInterest(bbox)
+                .filter("type:node")
+                .timestamps(this.ts)
+                .count();
+        
+        System.out.println(result);
+        
+        return 0;
+    }
+
+}
+```
+
+Run it e.g. with `mvn exec:java -Dexec.mainClass="mypackage.MyApplication" -Dexec.args="--oshdb h2:/path/to/file.oshdb.mv.db"`.
diff --git a/documentation/manual/helpers/OSHDBDriver.md b/documentation/manual/helpers/OSHDBDriver.md
new file mode 100644
index 000000000..c0738cac7
--- /dev/null
+++ b/documentation/manual/helpers/OSHDBDriver.md
@@ -0,0 +1,71 @@
+# OSHDBDriver
+
+To connect to the OSHDB using the OSHDBDriver you first have to define the configuration like
+
+```java
+   Properties props = new Properties();
+    //props.put("oshdb", "h2:PATH_TO_H2");
+    props.setProperty("oshdb","ignite:PATH_TO_CFG");
+    props.setProperty("keytables","jdbc:postgresql://localhost/keytables-${prefix}?user=ohsome&password=secret");
+```
+
+Alternatively you can read-in a .properties file with this information e.g. like so
+
+```java
+    Properties props = new Properties();
+    try(Reader reader = new FileReader("filename")){
+          props.load(reader);
+    }
+```
+
+Then connect to OSHDB using the driver like
+
+```java
+    OSHDBDriver.connect(props, (OSHDBConnection oshdb) -> {
+        //your oshdb code goes here
+        return 0;
+    });
+```
+
+Alternatively you can connect using one of the specific type-bound methods such as 
+
+```java
+    OSHDBDriver.connectToIgnite("PATH_TO_CFG", "KEYTABLES_CONNCTION_URL", oshdb -> {
+        //your oshdb code goes here
+        return 0;
+    );
+```
+
+## Example
+
+```java
+package mypackage;
+
+import java.util.Properties;
+import org.heigit.ohsome.oshdb.OSHDBBoundingBox;
+import org.heigit.ohsome.oshdb.helpers.OSHDBDriver;
+
+public class OSHDBDriverExample {
+
+    public static void main(String[] args) throws Exception {
+        Properties props = new Properties();
+        props.put("oshdb", "h2:PATH_TO_H2");
+        //props.setProperty("oshdb", "ignite:PATH_TO_CFG");
+        props.setProperty("keytables", "jdbc:postgresql://localhost/keytables-global?user=ohsome&password=secret");
+
+        OSHDBDriver.connect(props, oshdb -> {
+            OSHDBBoundingBox bbox = OSHDBBoundingBox.bboxWgs84Coordinates(8.651133, 49.387611, 8.6561, 49.390513);
+
+            Integer result = oshdb.getSnapshotView()
+                    .areaOfInterest(bbox)
+                    .filter("type:node")
+                    .timestamps("2018-05-01")
+                    .count();
+
+            System.out.println(result);
+            return 0;
+        });
+    }
+
+}
+```
diff --git a/oshdb-helpers/README.md b/oshdb-helpers/README.md
new file mode 100644
index 000000000..d0e12106c
--- /dev/null
+++ b/oshdb-helpers/README.md
@@ -0,0 +1,54 @@
+# OSHDB Driver and Application
+
+[![build status](https://jenkins.ohsome.org/buildStatus/icon?job=oshdb-database-driver/master)](https://jenkins.ohsome.org/blue/organizations/jenkins/oshdb-database-driver/activity/?branch=master)
+[![JavaDocs](https://img.shields.io/badge/Java-docs-blue.svg)](https://docs.ohsome.org/java/oshdb-database-driver)
+[![status: experimental](https://github.com/GIScience/badges/raw/master/status/experimental.svg)](https://github.com/GIScience/badges#experimental)
+
+Simple [OSHDB](https://github.com/GIScience/oshdb) connection helpers that automatically open an Ignite or H2 connection, depending on the input.
+
+Two functionalities are available:
+
+ - The [OSHDBApplication](doc/OSHDBApplication.md) (recommended usage) provides a full [Spring boot](https://spring.io/projects/spring-boot) -like application including a CLI. "Just add" your OSHDB functionality to create a usage-ready application. 
+ - The [OSHDBDriver](doc/OSHDBDriver.md) provides a static method that exhibits an OSHDB connection to a respective `Consumer`. It leaves you with all setup work for your application and will only handle the OSHDB connection part.
+
+## Installation
+
+The tool is not (yet) available on Maven central. To add it to your project add our public repository in addition to the dependency:
+
+```xml
+<project>
+   [...]
+   <repositories>
+      <repository>
+         <id>oshdb-repository</id>
+         <name>Heigit/GIScience maven repository</name>
+         <url>https://repo.heigit.org/artifactory/main</url>
+      </repository>
+   </repositories>
+
+   <dependencies>
+      <dependency>
+         <groupId>org.heigit.ohsome.oshdb.helpers</groupId>
+         <artifactId>OSHDBDriver</artifactId>
+         <version>1.0-SNAPSHOT</version>
+      </dependency>
+      [...]
+   </dependencies>
+</project>
+```
+
+##  Configuration
+
+Both functionalities will need the following configuraiton options. The details how to specify them will be discussed in the respective subsection.
+
+ - oshdb
+    - for a connection to an H2-file this is the absolute path to the H2-file prefixed by "h2:" like "h2:/path/to/file.oshdb.mv.db"
+    - for a connection to an Ignite cluster this is the absolute path to an ignite-config.xml file prefixed by "ignite:" like "ignite:/path/to/file.xml"
+ - prefix (optional)
+    - a string prefixed to database objects to allow multiple data versions to co-exist in the backend. It is (only) necessary if you want to access a legacy OSHDB ignite cluster. You will be notified about this once you get access to an H2-file or the Ignite cluster. If it is defined, it is mostly something like "global-xxxx" where xxxx is the sequence number from http://api.ohsome.org/v1/metadata
+ - keytables (optional)
+    - a JDBC string defining a connection to the [keytables](https://github.com/GIScience/oshdb/blob/83d337fbb5b2f923b29b8c56f182a883e922029b/documentation/manual/data-model.md#keytables) linked to the targeted OSHDB. It is (only) necessary if you want to access a legacy OSHDB ignite cluster. H2 files normally self contain the keytables where the tools are able to find them. The same is true for standard Ignite cluster backends.
+ - multithreading (optional)
+    - a boolean parameter for jdbc based connections (i.e. H2) if multithreading should be enabled during processing. 
+ 
+ Note that any `${some-property}` (e.g. `${prefix}`) within these property strings will be automatically replaced by the respective property value. So you can safely include these placeholders into your keytables URL (or any other property), if needed.

From 2148c5136ce230e9b84cdf463f3fcfa3c54a778f Mon Sep 17 00:00:00 2001
From: Johannes Visintini <johannes.visintini@heigit.org>
Date: Fri, 4 Nov 2022 14:39:31 +0100
Subject: [PATCH 03/15] refine helpers documentation

Co-authored-by: Moritz Schott <moritz.schott@uni-heidelberg.de>
---
 .../manual/helpers/OSHDBApplication.md        | 32 +++++++----
 documentation/manual/helpers/OSHDBDriver.md   | 37 +++++++++----
 documentation/manual/helpers/README.md        | 25 +++++++++
 oshdb-helpers/README.md                       | 54 -------------------
 4 files changed, 75 insertions(+), 73 deletions(-)
 create mode 100644 documentation/manual/helpers/README.md
 delete mode 100644 oshdb-helpers/README.md

diff --git a/documentation/manual/helpers/OSHDBApplication.md b/documentation/manual/helpers/OSHDBApplication.md
index e06f9a63f..827648a76 100644
--- a/documentation/manual/helpers/OSHDBApplication.md
+++ b/documentation/manual/helpers/OSHDBApplication.md
@@ -1,19 +1,33 @@
-# OSHDB Application
+# OSHDB Application Template
+## Installation
 
-Create a main Class extending on the `OSHDBApplication`
+Replace your OSHDB dependency with the following:
+
+```xml
+<dependency>
+   <groupId>org.heigit.ohsome</groupId>
+   <artifactId>oshdb-application-template</artifactId>
+   <version>0.7.2</version>
+</dependency>
+```
+
+## Usage
+
+Create a main Class extending on the `OSHDBApplication`:
 
 ```java
-public class MyApplication extends OSHDBApplication{
+public class MyApplication extends OSHDBApplication {
 
     public static void main(String[] args) {}
     
     @Override
-    protected int run(OSHDBConnection oshdb) throws Exception {return 0;}
-    
+    protected int run(OSHDBConnection oshdb) throws Exception {
+      return 0;
+    }
 }
 ```
 
-Activate you application by executing it in the `main` method
+Activate you application by executing it in the `main` method:
 
 ```java
     public static void main(String[] args) {
@@ -26,14 +40,14 @@ The `run` method now replaces your `main` method. You can add any functionality
 ```java
     @Override
     protected int run(OSHDBConnection oshdb) throws Exception {
-        //your code goes here
+        // your code goes here
         return 0;
     }
 ```
 
 Other output (e.g. from the OSHDB query itself), needs to be handled within the method like writing it to a file, storing it in a database or printing it to the screen.
 
-To provide input to your application or query you can equally use the methods' body. Alternatively you can extend the predefined [picocli](https://picocli.info/) -based CLI with your own arguments
+To provide input to your application or query you can equally use the methods' body. Alternatively you can extend the predefined [picocli](https://picocli.info/)-based CLI with your own arguments
 
 ```java
     @CommandLine.Option(names = {"--myInput"}, description = "custom CLI input")
@@ -44,7 +58,7 @@ To provide input to your application or query you can equally use the methods' b
         System.out.println(this.input);
 ```
 
-To run your application/query execute it in a command line. To configure the oshdb connection (see the [README.md](../../../README.md)) you can either use the provided CLI options (--oshdb, --prefix, --keytables), provide a '.properties' file (--props), or both. Any given CLI option will overwrite the properties provided in the file (if both paramters are present).
+To run your application/query execute it in a command line. To configure the oshdb connection (see the [README.md](README.md)) you can either use the provided CLI options (`--oshdb`, `--prefix`, `--keytables`), provide a `.properties` file (`--props`), or both. Any given CLI option will overwrite the properties provided in the file (if both parameters are present).
 
 ## Example
 
diff --git a/documentation/manual/helpers/OSHDBDriver.md b/documentation/manual/helpers/OSHDBDriver.md
index c0738cac7..23ea81a45 100644
--- a/documentation/manual/helpers/OSHDBDriver.md
+++ b/documentation/manual/helpers/OSHDBDriver.md
@@ -1,28 +1,43 @@
 # OSHDBDriver
+## Installation
 
-To connect to the OSHDB using the OSHDBDriver you first have to define the configuration like
+Replace your OSHDB dependency with the following:
+
+```xml
+<dependency>
+   <groupId>org.heigit.ohsome</groupId>
+   <artifactId>oshdb-database-driver</artifactId>
+   <version>0.7.2</version>
+</dependency>
+```
+
+## Usage
+
+To connect to the OSHDB using the OSHDBDriver you first have to define the configuration like:
 
 ```java
-   Properties props = new Properties();
-    //props.put("oshdb", "h2:PATH_TO_H2");
+    Properties props = new Properties();
+    // For H2:
+    props.setProperty("oshdb", "h2:PATH_TO_H2");
+    // Or for Ignite:
     props.setProperty("oshdb","ignite:PATH_TO_CFG");
     props.setProperty("keytables","jdbc:postgresql://localhost/keytables-${prefix}?user=ohsome&password=secret");
 ```
 
-Alternatively you can read-in a .properties file with this information e.g. like so
+Alternatively you can read-in a `….properties` file with this information e.g. like so:
 
 ```java
     Properties props = new Properties();
-    try(Reader reader = new FileReader("filename")){
+    try(Reader reader = new FileReader("oshdb.properties")){
           props.load(reader);
     }
 ```
 
-Then connect to OSHDB using the driver like
+Then connect to OSHDB using the driver like:
 
 ```java
     OSHDBDriver.connect(props, (OSHDBConnection oshdb) -> {
-        //your oshdb code goes here
+        // your oshdb code goes here
         return 0;
     });
 ```
@@ -31,7 +46,7 @@ Alternatively you can connect using one of the specific type-bound methods such
 
 ```java
     OSHDBDriver.connectToIgnite("PATH_TO_CFG", "KEYTABLES_CONNCTION_URL", oshdb -> {
-        //your oshdb code goes here
+        // your oshdb code goes here
         return 0;
     );
 ```
@@ -49,8 +64,10 @@ public class OSHDBDriverExample {
 
     public static void main(String[] args) throws Exception {
         Properties props = new Properties();
-        props.put("oshdb", "h2:PATH_TO_H2");
-        //props.setProperty("oshdb", "ignite:PATH_TO_CFG");
+        // For H2:
+        props.setProperty("oshdb", "h2:PATH_TO_H2");
+        // Or for Ignite:
+        props.setProperty("oshdb", "ignite:PATH_TO_CFG");
         props.setProperty("keytables", "jdbc:postgresql://localhost/keytables-global?user=ohsome&password=secret");
 
         OSHDBDriver.connect(props, oshdb -> {
diff --git a/documentation/manual/helpers/README.md b/documentation/manual/helpers/README.md
new file mode 100644
index 000000000..7ec20afaa
--- /dev/null
+++ b/documentation/manual/helpers/README.md
@@ -0,0 +1,25 @@
+# OSHDB Helpers
+
+Simple OSHDB connection helpers that automatically open an Ignite or H2 connection, depending on the input.
+
+Two functionalities are available:
+
+ - The [OSHDBApplication](OSHDBApplication.md) (recommended usage) provides a full [Spring boot](https://spring.io/projects/spring-boot)-like application including a CLI. "Just add" your OSHDB functionality to create a usage-ready application.
+ - The [OSHDBDriver](OSHDBDriver.md) provides a static method that exhibits an OSHDB connection to a respective `Consumer`. It leaves you with all setup work for your application and will only handle the OSHDB connection part.
+
+
+##  Configuration
+
+Both functionalities will need the following configuration options. The details how to specify them will be discussed in the respective subsection.
+
+ - `oshdb`
+    - for a connection to an H2-file this is the absolute path to the H2-file prefixed by `h2:` like `h2:/path/to/file.oshdb.mv.db`
+    - for a connection to an Ignite cluster this is the absolute path to an ignite-config.xml file prefixed by `ignite:` like `ignite:/path/to/file.xml`
+ - `prefix` (optional)
+    - a string prefixed to database objects to allow multiple data versions to co-exist in the backend. It is (only) necessary if you want to access a legacy OSHDB ignite cluster. You will be notified about this once you get access to an H2-file or the Ignite cluster.
+ - `keytables` (optional for H2)
+    - a JDBC string defining a connection to the [keytables](../data-model.md#keytables) linked to the targeted OSHDB. H2 files normally self contain the keytables where the tools are able to find them.
+ - `multithreading` (optional for H2)
+    - a boolean parameter for jdbc based connections (i.e. H2) if multithreading should be enabled during processing. 
+ 
+ Note that any `${some-property}` (e.g. `${prefix}`) within these property strings will be automatically replaced by the respective property value. So you can safely include these placeholders into your keytables URL (or any other property), if needed.
diff --git a/oshdb-helpers/README.md b/oshdb-helpers/README.md
deleted file mode 100644
index d0e12106c..000000000
--- a/oshdb-helpers/README.md
+++ /dev/null
@@ -1,54 +0,0 @@
-# OSHDB Driver and Application
-
-[![build status](https://jenkins.ohsome.org/buildStatus/icon?job=oshdb-database-driver/master)](https://jenkins.ohsome.org/blue/organizations/jenkins/oshdb-database-driver/activity/?branch=master)
-[![JavaDocs](https://img.shields.io/badge/Java-docs-blue.svg)](https://docs.ohsome.org/java/oshdb-database-driver)
-[![status: experimental](https://github.com/GIScience/badges/raw/master/status/experimental.svg)](https://github.com/GIScience/badges#experimental)
-
-Simple [OSHDB](https://github.com/GIScience/oshdb) connection helpers that automatically open an Ignite or H2 connection, depending on the input.
-
-Two functionalities are available:
-
- - The [OSHDBApplication](doc/OSHDBApplication.md) (recommended usage) provides a full [Spring boot](https://spring.io/projects/spring-boot) -like application including a CLI. "Just add" your OSHDB functionality to create a usage-ready application. 
- - The [OSHDBDriver](doc/OSHDBDriver.md) provides a static method that exhibits an OSHDB connection to a respective `Consumer`. It leaves you with all setup work for your application and will only handle the OSHDB connection part.
-
-## Installation
-
-The tool is not (yet) available on Maven central. To add it to your project add our public repository in addition to the dependency:
-
-```xml
-<project>
-   [...]
-   <repositories>
-      <repository>
-         <id>oshdb-repository</id>
-         <name>Heigit/GIScience maven repository</name>
-         <url>https://repo.heigit.org/artifactory/main</url>
-      </repository>
-   </repositories>
-
-   <dependencies>
-      <dependency>
-         <groupId>org.heigit.ohsome.oshdb.helpers</groupId>
-         <artifactId>OSHDBDriver</artifactId>
-         <version>1.0-SNAPSHOT</version>
-      </dependency>
-      [...]
-   </dependencies>
-</project>
-```
-
-##  Configuration
-
-Both functionalities will need the following configuraiton options. The details how to specify them will be discussed in the respective subsection.
-
- - oshdb
-    - for a connection to an H2-file this is the absolute path to the H2-file prefixed by "h2:" like "h2:/path/to/file.oshdb.mv.db"
-    - for a connection to an Ignite cluster this is the absolute path to an ignite-config.xml file prefixed by "ignite:" like "ignite:/path/to/file.xml"
- - prefix (optional)
-    - a string prefixed to database objects to allow multiple data versions to co-exist in the backend. It is (only) necessary if you want to access a legacy OSHDB ignite cluster. You will be notified about this once you get access to an H2-file or the Ignite cluster. If it is defined, it is mostly something like "global-xxxx" where xxxx is the sequence number from http://api.ohsome.org/v1/metadata
- - keytables (optional)
-    - a JDBC string defining a connection to the [keytables](https://github.com/GIScience/oshdb/blob/83d337fbb5b2f923b29b8c56f182a883e922029b/documentation/manual/data-model.md#keytables) linked to the targeted OSHDB. It is (only) necessary if you want to access a legacy OSHDB ignite cluster. H2 files normally self contain the keytables where the tools are able to find them. The same is true for standard Ignite cluster backends.
- - multithreading (optional)
-    - a boolean parameter for jdbc based connections (i.e. H2) if multithreading should be enabled during processing. 
- 
- Note that any `${some-property}` (e.g. `${prefix}`) within these property strings will be automatically replaced by the respective property value. So you can safely include these placeholders into your keytables URL (or any other property), if needed.

From 82196b413e4653f1cf63fda0197a1c07de49b4f1 Mon Sep 17 00:00:00 2001
From: Johannes Visintini <johannes.visintini@heigit.org>
Date: Fri, 4 Nov 2022 14:52:44 +0100
Subject: [PATCH 04/15] link helpers manual in existing documentation

Co-authored-by: Moritz Schott <moritz.schott@uni-heidelberg.de>
---
 documentation/first-steps/README.md | 5 ++++-
 documentation/manual/README.md      | 2 ++
 documentation/manual/data-model.md  | 2 +-
 3 files changed, 7 insertions(+), 2 deletions(-)

diff --git a/documentation/first-steps/README.md b/documentation/first-steps/README.md
index cdc7d8bcd..e5d933943 100644
--- a/documentation/first-steps/README.md
+++ b/documentation/first-steps/README.md
@@ -41,6 +41,9 @@ Now, we're ready to go and use the OSHDB to query the OSM history data. If we're
 OSHDBDatabase oshdb = new OSHDBH2("path/to/extract.oshdb");
 ```
 
+| 🛈 | Alternatively, we provide simple [connection helper](../manual/helpers). |
+|----|----------------------------------|
+
 ## 4. Select OSHDB view
 
 The next step is to decide which kind of analysis we want to perform on the OSM history data. Two different analysis views are provided by the OSHDB:
@@ -148,4 +151,4 @@ The result from this query is visualized in the following graph:
 
 ## 12. Next steps
 
-That's it for our first-steps tutorial. Of course there are many more options and features to explore in the OSHDB. For example how the contribution [view](../manual/views.md) lets you analyze each modification to the OSM objects individually, more advanced [filtering](../manual/filters.md) options, or other concepts like the [`flatMap`](../manual/map-reduce.md#flatmap) function, custom [`aggregateBy`](../manual/aggregation.md) and [`reduce`](../manual/map-reduce.md#reduce) operations, etc.
+That's it for our first-steps tutorial. Of course there are many more options and features to explore in the OSHDB. For example how the contribution [view](../manual/views.md) lets you analyze each modification to the OSM objects individually, more advanced [filtering](../manual/filters.md) options, or other concepts like the [`flatMap`](../manual/map-reduce.md#flatmap) function, custom [`aggregateBy`](../manual/aggregation.md) and [`reduce`](../manual/map-reduce.md#reduce) operations, etc.
\ No newline at end of file
diff --git a/documentation/manual/README.md b/documentation/manual/README.md
index 3d9509c3a..21997d1b0 100644
--- a/documentation/manual/README.md
+++ b/documentation/manual/README.md
@@ -26,6 +26,8 @@ Contents
   Explains the design of the OSHDB data model.
 * [Installation](installation.md) <br>
   A guide for how to install the OSHDB from sources.
+* [Helpers](helpers) <br>
+  Documentation for helpers that reduce complexity in connection setup for OSHDB.
 
 See also
 --------
diff --git a/documentation/manual/data-model.md b/documentation/manual/data-model.md
index f2da046a0..f39d7f588 100644
--- a/documentation/manual/data-model.md
+++ b/documentation/manual/data-model.md
@@ -29,6 +29,6 @@ The global OSM history data set is divided into a set of partitions (grid cells)
 Keytables
 ---------
 
-In order to minimize memory needed to store the key and value strings of OSM tags, the OSHDB uses so called “keytables” that assign every string (e.g. the tag key `builing`) to a number. More often used strings are assigned to lower numbers compared to rarely used strings which are assigned to higher numbers.
+In order to minimize memory needed to store the key and value strings of OSM tags, the OSHDB uses so called “keytables” that assign every string (e.g. the tag key `building`) to a number. More often used strings are assigned to lower numbers compared to rarely used strings which are assigned to higher numbers.
 
 This allows the data stored in the OSH entities to be more compact compared to storing each complete string with each entity.
\ No newline at end of file

From 23ab3493f6d2115da8f656226040536972e92d96 Mon Sep 17 00:00:00 2001
From: Johannes Visintini <johannes.visintini@heigit.org>
Date: Fri, 4 Nov 2022 15:16:04 +0100
Subject: [PATCH 05/15] replace string constants with static variables in
 helpers

Co-authored-by: Moritz Schott <moritz.schott@uni-heidelberg.de>
---
 .../applicationtemplate/OSHDBApplication.java | 16 ++++-----
 .../ohsome/oshdb/helpers/db/OSHDBDriver.java  | 36 +++++++++++--------
 2 files changed, 30 insertions(+), 22 deletions(-)

diff --git a/oshdb-helpers/oshdb-application-template/src/main/java/org/heigit/ohsome/oshdb/helpers/applicationtemplate/OSHDBApplication.java b/oshdb-helpers/oshdb-application-template/src/main/java/org/heigit/ohsome/oshdb/helpers/applicationtemplate/OSHDBApplication.java
index 96f6a17ac..508fa00eb 100644
--- a/oshdb-helpers/oshdb-application-template/src/main/java/org/heigit/ohsome/oshdb/helpers/applicationtemplate/OSHDBApplication.java
+++ b/oshdb-helpers/oshdb-application-template/src/main/java/org/heigit/ohsome/oshdb/helpers/applicationtemplate/OSHDBApplication.java
@@ -81,18 +81,18 @@ public static void run(Class<? extends OSHDBApplication> clazz, String[] args) {
   public Integer call() throws Exception {
     props = new Properties();
     PropsUtil.load(props, configOrUrl.config);
-    PropsUtil.set(props, "oshdb", configOrUrl.oshdbUrl);
-    PropsUtil.set(props, "keytables", keytableUrl);
-    PropsUtil.set(props, "prefix", prefix);
-    PropsUtil.set(props, "multithreading", multithreading);
+    PropsUtil.set(props, OSHDBDriver.OSHDB_PROPERTY_NAME, configOrUrl.oshdbUrl);
+    PropsUtil.set(props, OSHDBDriver.KEYTABLES_PROPERTY_NAME, keytableUrl);
+    PropsUtil.set(props, OSHDBDriver.PREFIX_PROPERTY_NAME, prefix);
+    PropsUtil.set(props, OSHDBDriver.MULTITHREADING_PROPERTY_NAME, multithreading);
     return OSHDBDriver.connect(props, this::setAndRun);
   }
 
   private int setAndRun(OSHDBConnection connection) throws Exception {
-    configOrUrl.oshdbUrl = PropsUtil.get(props, "oshdb").orElseThrow();
-    keytableUrl = PropsUtil.get(props, "keytables").orElse(null);
-    prefix = PropsUtil.get(props, "prefix").orElse("");
-    multithreading = Boolean.valueOf(PropsUtil.get(props, "multithreading").orElse("false"));
+    configOrUrl.oshdbUrl = PropsUtil.get(props, OSHDBDriver.OSHDB_PROPERTY_NAME).orElseThrow();
+    keytableUrl = PropsUtil.get(props, OSHDBDriver.KEYTABLES_PROPERTY_NAME).orElse(null);
+    prefix = PropsUtil.get(props, OSHDBDriver.PREFIX_PROPERTY_NAME).orElse("");
+    multithreading = Boolean.valueOf(PropsUtil.get(props, OSHDBDriver.MULTITHREADING_PROPERTY_NAME).orElse("false"));
     return run(connection);
   }
 
diff --git a/oshdb-helpers/oshdb-database-driver/src/main/java/org/heigit/ohsome/oshdb/helpers/db/OSHDBDriver.java b/oshdb-helpers/oshdb-database-driver/src/main/java/org/heigit/ohsome/oshdb/helpers/db/OSHDBDriver.java
index b10108d4a..1cf10b04c 100644
--- a/oshdb-helpers/oshdb-database-driver/src/main/java/org/heigit/ohsome/oshdb/helpers/db/OSHDBDriver.java
+++ b/oshdb-helpers/oshdb-database-driver/src/main/java/org/heigit/ohsome/oshdb/helpers/db/OSHDBDriver.java
@@ -28,6 +28,12 @@
  */
 public class OSHDBDriver {
 
+  public static final String OSHDB_PROPERTY_NAME = "oshdb";
+  public static final String KEYTABLES_PROPERTY_NAME = "keytables";
+  public static final String PREFIX_PROPERTY_NAME = "prefix";
+  public static final String MULTITHREADING_PROPERTY_NAME = "multithreading";
+  public static final String IGNITE_URI_PREFIX = "ignite:";
+
   private OSHDBDriver() {
     throw new IllegalStateException("Driver class");
   }
@@ -53,9 +59,9 @@ private OSHDBDriver() {
    * @throws java.lang.Exception
    */
   public static int connect(Properties props, Execute connect) throws Exception {
-    var oshdb = getInterpolated(props, "oshdb")
+    var oshdb = getInterpolated(props, OSHDBDriver.OSHDB_PROPERTY_NAME)
         .orElseThrow(() ->  new IllegalArgumentException("need to have to specifiy oshdb!"));
-    if (oshdb.toLowerCase().startsWith("ignite:")) {
+    if (oshdb.toLowerCase().startsWith(IGNITE_URI_PREFIX)) {
       return connectToIgnite(props, connect);
     } else if (oshdb.toLowerCase().startsWith("h2:")) {
       return connectToH2(props, connect);
@@ -66,13 +72,13 @@ public static int connect(Properties props, Execute connect) throws Exception {
 
   public static int connectToH2(Properties props, Execute connect)
       throws Exception {
-    var prefix = getInterpolated(props, "prefix").orElse("");
-    props.put("prefix", prefix);
+    var prefix = getInterpolated(props, PREFIX_PROPERTY_NAME).orElse("");
+    props.put(PREFIX_PROPERTY_NAME, prefix);
     var h2 =
-        getInterpolated(props, "oshdb")
+        getInterpolated(props, OSHDB_PROPERTY_NAME)
         .map(value -> value.substring("h2:".length())).orElseThrow();
     var multithreading =
-        getInterpolated(props, "multithreading").filter("true"::equalsIgnoreCase).isPresent();
+        getInterpolated(props, MULTITHREADING_PROPERTY_NAME).filter("true"::equalsIgnoreCase).isPresent();
     return connectToH2(h2, prefix, multithreading, connect);
   }
 
@@ -90,8 +96,8 @@ public static int connectToH2(String h2, String prefix, boolean multithreading,
       oshdb.prefix(prefix);
       oshdb.multithreading(multithreading);
       var props = new Properties();
-      props.setProperty("oshdb", h2);
-      props.setProperty("prefix", prefix);
+      props.setProperty(OSHDBDriver.OSHDB_PROPERTY_NAME, h2);
+      props.setProperty(PREFIX_PROPERTY_NAME, prefix);
       final var connection = new OSHDBConnection(props, oshdb, keyTables);
       return connect.apply(connection);
     }
@@ -101,14 +107,14 @@ public static int connectToH2(String h2, String prefix, boolean multithreading,
   @SuppressWarnings("java:S112")
   private static int connectToIgnite(Properties props, Execute connect)
       throws Exception {
-    var cfg = getInterpolated(props, "oshdb").filter(value -> value.toLowerCase().startsWith("ignite:"))
-        .map(value -> value.substring("ignite:".length())).orElseThrow();
+    var cfg = getInterpolated(props, OSHDB_PROPERTY_NAME).filter(value -> value.toLowerCase().startsWith(IGNITE_URI_PREFIX))
+        .map(value -> value.substring(IGNITE_URI_PREFIX.length())).orElseThrow();
     try (var ignite = Ignition.start(cfg)) {
-      var prefix = getInterpolated(props, "prefix").orElseGet(() -> getActive(ignite));
-      props.put("prefix", prefix);
-      var keyTablesUrl = getInterpolated(props, "keytables")
+      var prefix = getInterpolated(props, PREFIX_PROPERTY_NAME).orElseGet(() -> getActive(ignite));
+      props.put(PREFIX_PROPERTY_NAME, prefix);
+      var keyTablesUrl = getInterpolated(props, OSHDBDriver.KEYTABLES_PROPERTY_NAME)
           .orElseThrow(() -> new IllegalArgumentException("missing keytables"));
-      props.put("keytables", keyTablesUrl);
+      props.put(OSHDBDriver.KEYTABLES_PROPERTY_NAME, keyTablesUrl);
       try (var ktConnection = DriverManager.getConnection(keyTablesUrl);
           var keytables = new OSHDBJdbc(ktConnection);
           var oshdb = new OSHDBIgnite(ignite)) {
@@ -120,6 +126,8 @@ private static int connectToIgnite(Properties props, Execute connect)
   }
 
   private static String getActive(Ignite ignite) {
+    // TODO: extract "ohsome" string
+    //       one possible solution: https://github.com/GIScience/oshdb/issues/108
     return ignite.<String, String>cache("ohsome").get("active");
   }
 

From d82a7e48bfd24b8fc4e4f7dee9bde4eca394f732 Mon Sep 17 00:00:00 2001
From: Johannes Visintini <johannes.visintini@heigit.org>
Date: Fri, 4 Nov 2022 15:52:24 +0100
Subject: [PATCH 06/15] solve code smells in helpers

Co-authored-by: Moritz Schott <moritz.schott@uni-heidelberg.de>
---
 .../applicationtemplate/OSHDBApplication.java | 26 +++++++++----------
 .../applicationtemplate/PropsUtil.java        | 10 +++----
 .../ohsome/oshdb/helpers/db/OSHDBDriver.java  | 12 ++++++---
 .../heigit/ohsome/oshdb/helpers/db/Util.java  |  5 ++--
 4 files changed, 29 insertions(+), 24 deletions(-)

diff --git a/oshdb-helpers/oshdb-application-template/src/main/java/org/heigit/ohsome/oshdb/helpers/applicationtemplate/OSHDBApplication.java b/oshdb-helpers/oshdb-application-template/src/main/java/org/heigit/ohsome/oshdb/helpers/applicationtemplate/OSHDBApplication.java
index 508fa00eb..f08230f90 100644
--- a/oshdb-helpers/oshdb-application-template/src/main/java/org/heigit/ohsome/oshdb/helpers/applicationtemplate/OSHDBApplication.java
+++ b/oshdb-helpers/oshdb-application-template/src/main/java/org/heigit/ohsome/oshdb/helpers/applicationtemplate/OSHDBApplication.java
@@ -42,10 +42,10 @@
 @Command(mixinStandardHelpOptions = true, sortOptions = false)
 public abstract class OSHDBApplication implements Callable<Integer> {
 
-  @ArgGroup(exclusive=false, multiplicity= "1")
+  @ArgGroup(exclusive = false, multiplicity = "1")
   ConfigOrUrl configOrUrl;
 
-  static class ConfigOrUrl{
+  static class ConfigOrUrl {
     @Option(names = {"--props"}, description = ".properties file path")
     protected Path config;
 
@@ -59,22 +59,21 @@ static class ConfigOrUrl{
   @Option(names = {"--prefix"}, description = "prefix to use")
   protected String prefix;
 
-  @Option(names = {"--multithreading"}, description = "for jdbc based connections", negatable=true)
+  @Option(names = {
+      "--multithreading"}, description = "for jdbc based connections", negatable = true)
   protected Boolean multithreading = null;
 
   protected Properties props;
 
+  @SuppressWarnings("java:S112")
   protected abstract int run(OSHDBConnection oshdb) throws Exception;
 
-  public static void run(Class<? extends OSHDBApplication> clazz, String[] args) {
-    try {
-      var app = clazz.getDeclaredConstructor().newInstance();
-      int exit = new CommandLine(app).execute(args);
-      System.exit(exit);
-    } catch (Exception e) {
-      e.printStackTrace();
-      System.exit(1);
-    }
+  @SuppressWarnings("java:S112")
+  public static void run(Class<? extends OSHDBApplication> clazz, String[] args)
+      throws Exception {
+    var app = clazz.getDeclaredConstructor().newInstance();
+    int exit = new CommandLine(app).execute(args);
+    System.exit(exit);
   }
 
   @Override
@@ -92,7 +91,8 @@ private int setAndRun(OSHDBConnection connection) throws Exception {
     configOrUrl.oshdbUrl = PropsUtil.get(props, OSHDBDriver.OSHDB_PROPERTY_NAME).orElseThrow();
     keytableUrl = PropsUtil.get(props, OSHDBDriver.KEYTABLES_PROPERTY_NAME).orElse(null);
     prefix = PropsUtil.get(props, OSHDBDriver.PREFIX_PROPERTY_NAME).orElse("");
-    multithreading = Boolean.valueOf(PropsUtil.get(props, OSHDBDriver.MULTITHREADING_PROPERTY_NAME).orElse("false"));
+    multithreading = Boolean.valueOf(
+        PropsUtil.get(props, OSHDBDriver.MULTITHREADING_PROPERTY_NAME).orElse("false"));
     return run(connection);
   }
 
diff --git a/oshdb-helpers/oshdb-application-template/src/main/java/org/heigit/ohsome/oshdb/helpers/applicationtemplate/PropsUtil.java b/oshdb-helpers/oshdb-application-template/src/main/java/org/heigit/ohsome/oshdb/helpers/applicationtemplate/PropsUtil.java
index 981dbd666..c465153ae 100644
--- a/oshdb-helpers/oshdb-application-template/src/main/java/org/heigit/ohsome/oshdb/helpers/applicationtemplate/PropsUtil.java
+++ b/oshdb-helpers/oshdb-application-template/src/main/java/org/heigit/ohsome/oshdb/helpers/applicationtemplate/PropsUtil.java
@@ -7,12 +7,12 @@
 import java.util.Optional;
 import java.util.Properties;
 
-public class PropsUtil {
+class PropsUtil {
 
   private PropsUtil() {
   }
 
-  public static void load(Properties props, Path path) throws IOException {
+  static void load(Properties props, Path path) throws IOException {
     if (path != null && Files.exists(path)) {
       try (var in = Files.newInputStream(path, StandardOpenOption.READ)) {
         props.load(in);
@@ -20,19 +20,19 @@ public static void load(Properties props, Path path) throws IOException {
     }
   }
 
-  public static void set(Properties props, String key, String value) {
+  static void set(Properties props, String key, String value) {
     if (value != null) {
       props.put(key, value);
     }
   }
 
-  public static void set(Properties props, String key, Boolean value) {
+  static void set(Properties props, String key, Boolean value) {
     if (value != null) {
       props.setProperty(key, Boolean.toString(value));
     }
   }
 
-  public static Optional<String> get(Properties props, String key) {
+  static Optional<String> get(Properties props, String key) {
     return Optional.ofNullable(props.getProperty(key));
   }
 
diff --git a/oshdb-helpers/oshdb-database-driver/src/main/java/org/heigit/ohsome/oshdb/helpers/db/OSHDBDriver.java b/oshdb-helpers/oshdb-database-driver/src/main/java/org/heigit/ohsome/oshdb/helpers/db/OSHDBDriver.java
index 1cf10b04c..18ef3c498 100644
--- a/oshdb-helpers/oshdb-database-driver/src/main/java/org/heigit/ohsome/oshdb/helpers/db/OSHDBDriver.java
+++ b/oshdb-helpers/oshdb-database-driver/src/main/java/org/heigit/ohsome/oshdb/helpers/db/OSHDBDriver.java
@@ -56,7 +56,7 @@ private OSHDBDriver() {
    *     </pre>
    * @param connect A Consumer for a OSHDBConnection e.g. a lambda
    * @return exit code
-   * @throws java.lang.Exception
+   * @throws Exception when an Exception is thrown in the underlying classes
    */
   public static int connect(Properties props, Execute connect) throws Exception {
     var oshdb = getInterpolated(props, OSHDBDriver.OSHDB_PROPERTY_NAME)
@@ -78,7 +78,8 @@ public static int connectToH2(Properties props, Execute connect)
         getInterpolated(props, OSHDB_PROPERTY_NAME)
         .map(value -> value.substring("h2:".length())).orElseThrow();
     var multithreading =
-        getInterpolated(props, MULTITHREADING_PROPERTY_NAME).filter("true"::equalsIgnoreCase).isPresent();
+        getInterpolated(props, MULTITHREADING_PROPERTY_NAME).filter("true"::equalsIgnoreCase)
+            .isPresent();
     return connectToH2(h2, prefix, multithreading, connect);
   }
 
@@ -107,8 +108,10 @@ public static int connectToH2(String h2, String prefix, boolean multithreading,
   @SuppressWarnings("java:S112")
   private static int connectToIgnite(Properties props, Execute connect)
       throws Exception {
-    var cfg = getInterpolated(props, OSHDB_PROPERTY_NAME).filter(value -> value.toLowerCase().startsWith(IGNITE_URI_PREFIX))
-        .map(value -> value.substring(IGNITE_URI_PREFIX.length())).orElseThrow();
+    var cfg = getInterpolated(props, OSHDB_PROPERTY_NAME)
+        .filter(value -> value.toLowerCase().startsWith(IGNITE_URI_PREFIX))
+        .map(value -> value.substring(IGNITE_URI_PREFIX.length()))
+        .orElseThrow();
     try (var ignite = Ignition.start(cfg)) {
       var prefix = getInterpolated(props, PREFIX_PROPERTY_NAME).orElseGet(() -> getActive(ignite));
       props.put(PREFIX_PROPERTY_NAME, prefix);
@@ -132,6 +135,7 @@ private static String getActive(Ignite ignite) {
   }
 
   @FunctionalInterface
+  @SuppressWarnings("java:S112")
   public interface Execute {
     int apply(OSHDBConnection oshdb) throws Exception;
   }
diff --git a/oshdb-helpers/oshdb-database-driver/src/main/java/org/heigit/ohsome/oshdb/helpers/db/Util.java b/oshdb-helpers/oshdb-database-driver/src/main/java/org/heigit/ohsome/oshdb/helpers/db/Util.java
index 8a9bcd8ae..a260879cc 100644
--- a/oshdb-helpers/oshdb-database-driver/src/main/java/org/heigit/ohsome/oshdb/helpers/db/Util.java
+++ b/oshdb-helpers/oshdb-database-driver/src/main/java/org/heigit/ohsome/oshdb/helpers/db/Util.java
@@ -4,12 +4,13 @@
 import java.util.Properties;
 import java.util.regex.Pattern;
 
-public class Util {
+class Util {
 
   private static final Pattern SUBSTITUTE = Pattern.compile("\\$\\{(\\w+)\\}");
 
   private Util() {}
-  public static Optional<String> getInterpolated(Properties props, String key) {
+
+  static Optional<String> getInterpolated(Properties props, String key) {
     return Optional.ofNullable(props.getProperty(key)).map(value -> interpolate(props, value));
   }
 

From e1a9838cbc943b82bc084ff79a52c0769ac23de3 Mon Sep 17 00:00:00 2001
From: Johannes Visintini <johannes.visintini@heigit.org>
Date: Fri, 4 Nov 2022 15:53:39 +0100
Subject: [PATCH 07/15] add Javadoc for OSHDBApplication

Co-authored-by: Moritz Schott <moritz.schott@uni-heidelberg.de>
---
 .../helpers/applicationtemplate/OSHDBApplication.java    | 9 ++++++---
 1 file changed, 6 insertions(+), 3 deletions(-)

diff --git a/oshdb-helpers/oshdb-application-template/src/main/java/org/heigit/ohsome/oshdb/helpers/applicationtemplate/OSHDBApplication.java b/oshdb-helpers/oshdb-application-template/src/main/java/org/heigit/ohsome/oshdb/helpers/applicationtemplate/OSHDBApplication.java
index f08230f90..02489a249 100644
--- a/oshdb-helpers/oshdb-application-template/src/main/java/org/heigit/ohsome/oshdb/helpers/applicationtemplate/OSHDBApplication.java
+++ b/oshdb-helpers/oshdb-application-template/src/main/java/org/heigit/ohsome/oshdb/helpers/applicationtemplate/OSHDBApplication.java
@@ -68,6 +68,12 @@ static class ConfigOrUrl {
   @SuppressWarnings("java:S112")
   protected abstract int run(OSHDBConnection oshdb) throws Exception;
 
+  /**
+   * Method to be called from the implemented application.
+   * @param clazz Class that will be started.
+   * @param args main args
+   * @throws Exception from application
+   */
   @SuppressWarnings("java:S112")
   public static void run(Class<? extends OSHDBApplication> clazz, String[] args)
       throws Exception {
@@ -95,7 +101,4 @@ private int setAndRun(OSHDBConnection connection) throws Exception {
         PropsUtil.get(props, OSHDBDriver.MULTITHREADING_PROPERTY_NAME).orElse("false"));
     return run(connection);
   }
-
-
-
 }

From 1d956539811586e72bdf8d98bfa96f4df459439c Mon Sep 17 00:00:00 2001
From: Johannes Visintini <johannes.visintini@heigit.org>
Date: Fri, 4 Nov 2022 16:06:00 +0100
Subject: [PATCH 08/15] fix minor issues in OSHDBDriver code

Co-authored-by: Moritz Schott <moritz.schott@uni-heidelberg.de>
---
 documentation/manual/helpers/OSHDBDriver.md      |  9 ---------
 .../applicationtemplate/OSHDBApplication.java    |  1 +
 .../ohsome/oshdb/helpers/db/OSHDBDriver.java     | 16 +++++++---------
 3 files changed, 8 insertions(+), 18 deletions(-)

diff --git a/documentation/manual/helpers/OSHDBDriver.md b/documentation/manual/helpers/OSHDBDriver.md
index 23ea81a45..e029e3ad3 100644
--- a/documentation/manual/helpers/OSHDBDriver.md
+++ b/documentation/manual/helpers/OSHDBDriver.md
@@ -42,15 +42,6 @@ Then connect to OSHDB using the driver like:
     });
 ```
 
-Alternatively you can connect using one of the specific type-bound methods such as 
-
-```java
-    OSHDBDriver.connectToIgnite("PATH_TO_CFG", "KEYTABLES_CONNCTION_URL", oshdb -> {
-        // your oshdb code goes here
-        return 0;
-    );
-```
-
 ## Example
 
 ```java
diff --git a/oshdb-helpers/oshdb-application-template/src/main/java/org/heigit/ohsome/oshdb/helpers/applicationtemplate/OSHDBApplication.java b/oshdb-helpers/oshdb-application-template/src/main/java/org/heigit/ohsome/oshdb/helpers/applicationtemplate/OSHDBApplication.java
index 02489a249..8f16cb04e 100644
--- a/oshdb-helpers/oshdb-application-template/src/main/java/org/heigit/ohsome/oshdb/helpers/applicationtemplate/OSHDBApplication.java
+++ b/oshdb-helpers/oshdb-application-template/src/main/java/org/heigit/ohsome/oshdb/helpers/applicationtemplate/OSHDBApplication.java
@@ -70,6 +70,7 @@ static class ConfigOrUrl {
 
   /**
    * Method to be called from the implemented application.
+   *
    * @param clazz Class that will be started.
    * @param args main args
    * @throws Exception from application
diff --git a/oshdb-helpers/oshdb-database-driver/src/main/java/org/heigit/ohsome/oshdb/helpers/db/OSHDBDriver.java b/oshdb-helpers/oshdb-database-driver/src/main/java/org/heigit/ohsome/oshdb/helpers/db/OSHDBDriver.java
index 18ef3c498..23d26a122 100644
--- a/oshdb-helpers/oshdb-database-driver/src/main/java/org/heigit/ohsome/oshdb/helpers/db/OSHDBDriver.java
+++ b/oshdb-helpers/oshdb-database-driver/src/main/java/org/heigit/ohsome/oshdb/helpers/db/OSHDBDriver.java
@@ -60,7 +60,7 @@ private OSHDBDriver() {
    */
   public static int connect(Properties props, Execute connect) throws Exception {
     var oshdb = getInterpolated(props, OSHDBDriver.OSHDB_PROPERTY_NAME)
-        .orElseThrow(() ->  new IllegalArgumentException("need to have to specifiy oshdb!"));
+        .orElseThrow(() ->  new IllegalArgumentException("need to have to specify oshdb!"));
     if (oshdb.toLowerCase().startsWith(IGNITE_URI_PREFIX)) {
       return connectToIgnite(props, connect);
     } else if (oshdb.toLowerCase().startsWith("h2:")) {
@@ -70,7 +70,7 @@ public static int connect(Properties props, Execute connect) throws Exception {
     }
   }
 
-  public static int connectToH2(Properties props, Execute connect)
+  private static int connectToH2(Properties props, Execute connect)
       throws Exception {
     var prefix = getInterpolated(props, PREFIX_PROPERTY_NAME).orElse("");
     props.put(PREFIX_PROPERTY_NAME, prefix);
@@ -83,14 +83,9 @@ public static int connectToH2(Properties props, Execute connect)
     return connectToH2(h2, prefix, multithreading, connect);
   }
 
-  public static int connectToH2(String url, String prefix, Execute connect)
-      throws Exception {
-    return connectToH2(url, prefix, true, connect);
-  }
-
   // OSHDBJdbc throws "Exception"
   @SuppressWarnings("java:S112")
-  public static int connectToH2(String h2, String prefix, boolean multithreading,
+  private static int connectToH2(String h2, String prefix, boolean multithreading,
       Execute connect) throws Exception {
     try (final var oshdb = new OSHDBH2(h2);
         final var keyTables = new OSHDBJdbc(oshdb.getConnection())) {
@@ -134,9 +129,12 @@ private static String getActive(Ignite ignite) {
     return ignite.<String, String>cache("ohsome").get("active");
   }
 
+  /**
+   * Internally used execute interface that applies the given connection.
+   */
   @FunctionalInterface
-  @SuppressWarnings("java:S112")
   public interface Execute {
+    @SuppressWarnings("java:S112")
     int apply(OSHDBConnection oshdb) throws Exception;
   }
 }

From 22d666f7f7a0a4433e471ed9ffdb9c226d0e8364 Mon Sep 17 00:00:00 2001
From: Johannes Visintini <johannes.visintini@heigit.org>
Date: Fri, 4 Nov 2022 17:06:23 +0100
Subject: [PATCH 09/15] fix regex pattern for props substitution

Co-authored-by: Moritz Schott <moritz.schott@uni-heidelberg.de>
---
 .../src/main/java/org/heigit/ohsome/oshdb/helpers/db/Util.java  | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/oshdb-helpers/oshdb-database-driver/src/main/java/org/heigit/ohsome/oshdb/helpers/db/Util.java b/oshdb-helpers/oshdb-database-driver/src/main/java/org/heigit/ohsome/oshdb/helpers/db/Util.java
index a260879cc..2c38dc1c4 100644
--- a/oshdb-helpers/oshdb-database-driver/src/main/java/org/heigit/ohsome/oshdb/helpers/db/Util.java
+++ b/oshdb-helpers/oshdb-database-driver/src/main/java/org/heigit/ohsome/oshdb/helpers/db/Util.java
@@ -6,7 +6,7 @@
 
 class Util {
 
-  private static final Pattern SUBSTITUTE = Pattern.compile("\\$\\{(\\w+)\\}");
+  private static final Pattern SUBSTITUTE = Pattern.compile("\\$\\{([^\\}]+)\\}");
 
   private Util() {}
 

From 41dfddc8e8ad70fb13018d79776d86bf84b90988 Mon Sep 17 00:00:00 2001
From: Johannes Visintini <johannes.visintini@heigit.org>
Date: Fri, 4 Nov 2022 17:06:49 +0100
Subject: [PATCH 10/15] Add tests for OSHDBDriver

Co-authored-by: Moritz Schott <moritz.schott@uni-heidelberg.de>
---
 .../oshdb/helpers/db/OSHDBDriverH2Test.java   | 61 +++++++++++++++++++
 1 file changed, 61 insertions(+)
 create mode 100644 oshdb-helpers/oshdb-database-driver/src/test/java/org/heigit/ohsome/oshdb/helpers/db/OSHDBDriverH2Test.java

diff --git a/oshdb-helpers/oshdb-database-driver/src/test/java/org/heigit/ohsome/oshdb/helpers/db/OSHDBDriverH2Test.java b/oshdb-helpers/oshdb-database-driver/src/test/java/org/heigit/ohsome/oshdb/helpers/db/OSHDBDriverH2Test.java
new file mode 100644
index 000000000..062bd36a9
--- /dev/null
+++ b/oshdb-helpers/oshdb-database-driver/src/test/java/org/heigit/ohsome/oshdb/helpers/db/OSHDBDriverH2Test.java
@@ -0,0 +1,61 @@
+package org.heigit.ohsome.oshdb.helpers.db;
+
+import static org.heigit.ohsome.oshdb.OSHDBBoundingBox.bboxWgs84Coordinates;
+import static org.junit.jupiter.api.Assertions.*;
+
+import java.util.Properties;
+import org.junit.jupiter.api.DisplayName;
+import org.junit.jupiter.api.Test;
+
+class OSHDBDriverH2Test {
+
+  private static final Properties props = new Properties();
+
+  public OSHDBDriverH2Test() {
+    props.setProperty("oshdb", "h2:../../data/${test-file}");
+    // relevant for getter test
+    props.setProperty("test-file", "test-data");
+  }
+
+  @Test
+  @DisplayName("OSHDBConnection getSnapshotView")
+  void getSnapshotView() throws Exception {
+    int queryResult = OSHDBDriver.connect(props, oshdb -> {
+      var bbox = bboxWgs84Coordinates(8.651133, 49.387611, 8.6561, 49.390513);
+
+      return oshdb.getSnapshotView()
+          .areaOfInterest(bbox)
+          .filter("type:node")
+          .timestamps("2018-05-01")
+          .count();
+    });
+    assertEquals(7, queryResult);
+  }
+
+  @Test
+  @DisplayName("OSHDBConnection getContributionView")
+  void getContributionView() throws Exception {
+    int queryResult = OSHDBDriver.connect(props, oshdb -> {
+      var bbox = bboxWgs84Coordinates(8.651133, 49.387611, 8.6561, 49.390513);
+
+      return oshdb.getContributionView()
+          .areaOfInterest(bbox)
+          .filter("type:node")
+          .timestamps("2007-11-01", "2019-01-01")
+          .count();
+    });
+    assertEquals(16, queryResult);
+  }
+
+  @Test
+  @DisplayName("OSHDBConnection Getter")
+  void getter() throws Exception {
+    OSHDBDriver.connect(props, oshdb -> {
+      assertNotNull(oshdb.getProps());
+      assertNotNull(oshdb.getOSHDB());
+      assertNotNull(oshdb.getKeytables());
+      assertNotNull(oshdb.getTagTranslator());
+      return 0;
+    });
+  }
+}
\ No newline at end of file

From d12e7b540b2752cb1d41eb4674bce4ff8c7df84e Mon Sep 17 00:00:00 2001
From: Johannes Visintini <johannes.visintini@heigit.org>
Date: Fri, 4 Nov 2022 17:39:25 +0100
Subject: [PATCH 11/15] improve OSHDBDriverH2 Tests

---
 .../oshdb/helpers/db/OSHDBDriverH2Test.java   | 23 ++++++++++++-------
 1 file changed, 15 insertions(+), 8 deletions(-)

diff --git a/oshdb-helpers/oshdb-database-driver/src/test/java/org/heigit/ohsome/oshdb/helpers/db/OSHDBDriverH2Test.java b/oshdb-helpers/oshdb-database-driver/src/test/java/org/heigit/ohsome/oshdb/helpers/db/OSHDBDriverH2Test.java
index 062bd36a9..43026edbe 100644
--- a/oshdb-helpers/oshdb-database-driver/src/test/java/org/heigit/ohsome/oshdb/helpers/db/OSHDBDriverH2Test.java
+++ b/oshdb-helpers/oshdb-database-driver/src/test/java/org/heigit/ohsome/oshdb/helpers/db/OSHDBDriverH2Test.java
@@ -1,9 +1,13 @@
 package org.heigit.ohsome.oshdb.helpers.db;
 
 import static org.heigit.ohsome.oshdb.OSHDBBoundingBox.bboxWgs84Coordinates;
-import static org.junit.jupiter.api.Assertions.*;
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertTrue;
 
 import java.util.Properties;
+import org.heigit.ohsome.oshdb.api.db.OSHDBDatabase;
+import org.heigit.ohsome.oshdb.api.db.OSHDBJdbc;
+import org.heigit.ohsome.oshdb.util.tagtranslator.TagTranslator;
 import org.junit.jupiter.api.DisplayName;
 import org.junit.jupiter.api.Test;
 
@@ -17,6 +21,15 @@ public OSHDBDriverH2Test() {
     props.setProperty("test-file", "test-data");
   }
 
+  @SuppressWarnings("ConstantConditions")
+  private static int testGetters(OSHDBConnection oshdb) {
+    assertTrue(oshdb.getProps() instanceof Properties);
+    assertTrue(oshdb.getOSHDB() instanceof OSHDBDatabase);
+    assertTrue(oshdb.getKeytables() instanceof OSHDBJdbc);
+    assertTrue(oshdb.getTagTranslator() instanceof TagTranslator);
+    return 0;
+  }
+
   @Test
   @DisplayName("OSHDBConnection getSnapshotView")
   void getSnapshotView() throws Exception {
@@ -50,12 +63,6 @@ void getContributionView() throws Exception {
   @Test
   @DisplayName("OSHDBConnection Getter")
   void getter() throws Exception {
-    OSHDBDriver.connect(props, oshdb -> {
-      assertNotNull(oshdb.getProps());
-      assertNotNull(oshdb.getOSHDB());
-      assertNotNull(oshdb.getKeytables());
-      assertNotNull(oshdb.getTagTranslator());
-      return 0;
-    });
+    OSHDBDriver.connect(props, OSHDBDriverH2Test::testGetters);
   }
 }
\ No newline at end of file

From 430bd7940d27779daa70203a9e1e682353679d2f Mon Sep 17 00:00:00 2001
From: Moritz Schott <moritz.schott@uni-heidelberg.de>
Date: Mon, 7 Nov 2022 09:58:42 +0100
Subject: [PATCH 12/15] update changelog

---
 CHANGELOG.md | 1 +
 1 file changed, 1 insertion(+)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index c4c2a6a5f..064de3463 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -18,6 +18,7 @@ Changelog
 
 * allow to flexibly combine (automatic) aggregation methods (like `aggregateByGeometry(…)` or `aggregateByTimestamp()`) with each other and with `filter` or `map`/`flatMap`, regardless of the order of the applied operations ([#451])
 * add new OSHDB filters: `perimeter`, `geometry.vertices`, `geometry.outers`, `geometry.inners`, `geometry.roundness` and `geometry.squareness` ([#436])
+* add OSHDB-helpers module providing two helpers (OSHDBDriver and OSHDBApplication) to simplify database setup ([#474])
 
 ### bugfixes
 

From 53d7a03571e2f4f208f13379bd8132233e46bdfb Mon Sep 17 00:00:00 2001
From: Johannes Visintini <johannes.visintini@heigit.org>
Date: Thu, 10 Nov 2022 13:23:36 +0100
Subject: [PATCH 13/15] apply changes of #470 to oshdb-database-driver

new Dependency hikaricp
---
 oshdb-helpers/oshdb-database-driver/pom.xml    |  7 +++++++
 .../oshdb/helpers/db/OSHDBConnection.java      | 15 ++++-----------
 .../ohsome/oshdb/helpers/db/OSHDBDriver.java   | 18 +++++++++---------
 .../oshdb/helpers/db/OSHDBDriverH2Test.java    |  2 --
 4 files changed, 20 insertions(+), 22 deletions(-)

diff --git a/oshdb-helpers/oshdb-database-driver/pom.xml b/oshdb-helpers/oshdb-database-driver/pom.xml
index bbbd34a00..bd1664f62 100644
--- a/oshdb-helpers/oshdb-database-driver/pom.xml
+++ b/oshdb-helpers/oshdb-database-driver/pom.xml
@@ -13,6 +13,7 @@
   <description>TODO</description>
 
   <properties>
+    <hikaricp.version>5.0.1</hikaricp.version>
   </properties>
 
   <dependencies>
@@ -22,6 +23,12 @@
       <version>${project.version}</version>
       <scope>compile</scope>
     </dependency>
+    <!-- hikari database connection pool -->
+    <dependency>
+      <groupId>com.zaxxer</groupId>
+      <artifactId>HikariCP</artifactId>
+      <version>${hikaricp.version}</version>
+    </dependency>
   </dependencies>
 
 </project>
diff --git a/oshdb-helpers/oshdb-database-driver/src/main/java/org/heigit/ohsome/oshdb/helpers/db/OSHDBConnection.java b/oshdb-helpers/oshdb-database-driver/src/main/java/org/heigit/ohsome/oshdb/helpers/db/OSHDBConnection.java
index ff984595e..02cbdeea1 100644
--- a/oshdb-helpers/oshdb-database-driver/src/main/java/org/heigit/ohsome/oshdb/helpers/db/OSHDBConnection.java
+++ b/oshdb-helpers/oshdb-database-driver/src/main/java/org/heigit/ohsome/oshdb/helpers/db/OSHDBConnection.java
@@ -2,7 +2,6 @@
 
 import java.util.Properties;
 import org.heigit.ohsome.oshdb.api.db.OSHDBDatabase;
-import org.heigit.ohsome.oshdb.api.db.OSHDBJdbc;
 import org.heigit.ohsome.oshdb.api.mapreducer.MapReducer;
 import org.heigit.ohsome.oshdb.api.mapreducer.OSMContributionView;
 import org.heigit.ohsome.oshdb.api.mapreducer.OSMEntitySnapshotView;
@@ -15,23 +14,21 @@ public class OSHDBConnection {
 
   private final Properties props;
   private final OSHDBDatabase oshdb;
-  private final OSHDBJdbc keytables;
   private final TagTranslator tagTranslator;
 
-  public OSHDBConnection(Properties props, OSHDBDatabase oshdb, OSHDBJdbc keytables)
+  public OSHDBConnection(Properties props, OSHDBDatabase oshdb)
       throws OSHDBKeytablesNotFoundException {
     this.props = props;
     this.oshdb = oshdb;
-    this.keytables = keytables;
-    this.tagTranslator = new TagTranslator(keytables.getConnection());
+    this.tagTranslator = oshdb.getTagTranslator();
   }
 
   public MapReducer<OSMContribution> getContributionView() {
-    return OSMContributionView.on(oshdb).keytables(keytables);
+    return OSMContributionView.on(oshdb);
   }
 
   public MapReducer<OSMEntitySnapshot> getSnapshotView() {
-    return OSMEntitySnapshotView.on(oshdb).keytables(keytables);
+    return OSMEntitySnapshotView.on(oshdb);
   }
 
   public Properties getProps() {
@@ -42,10 +39,6 @@ public OSHDBDatabase getOSHDB() {
     return oshdb;
   }
 
-  public OSHDBJdbc getKeytables() {
-    return keytables;
-  }
-
   public TagTranslator getTagTranslator() {
     return tagTranslator;
   }
diff --git a/oshdb-helpers/oshdb-database-driver/src/main/java/org/heigit/ohsome/oshdb/helpers/db/OSHDBDriver.java b/oshdb-helpers/oshdb-database-driver/src/main/java/org/heigit/ohsome/oshdb/helpers/db/OSHDBDriver.java
index 23d26a122..cb03ad02a 100644
--- a/oshdb-helpers/oshdb-database-driver/src/main/java/org/heigit/ohsome/oshdb/helpers/db/OSHDBDriver.java
+++ b/oshdb-helpers/oshdb-database-driver/src/main/java/org/heigit/ohsome/oshdb/helpers/db/OSHDBDriver.java
@@ -2,13 +2,12 @@
 
 import static org.heigit.ohsome.oshdb.helpers.db.Util.getInterpolated;
 
-import java.sql.DriverManager;
+import com.zaxxer.hikari.HikariDataSource;
 import java.util.Properties;
 import org.apache.ignite.Ignite;
 import org.apache.ignite.Ignition;
 import org.heigit.ohsome.oshdb.api.db.OSHDBH2;
 import org.heigit.ohsome.oshdb.api.db.OSHDBIgnite;
-import org.heigit.ohsome.oshdb.api.db.OSHDBJdbc;
 
 /**
  * A basic OSHDBDriver class for connecting to h2 or ignite oshdb instances.
@@ -87,14 +86,13 @@ private static int connectToH2(Properties props, Execute connect)
   @SuppressWarnings("java:S112")
   private static int connectToH2(String h2, String prefix, boolean multithreading,
       Execute connect) throws Exception {
-    try (final var oshdb = new OSHDBH2(h2);
-        final var keyTables = new OSHDBJdbc(oshdb.getConnection())) {
+    try (final var oshdb = new OSHDBH2(h2)) {
       oshdb.prefix(prefix);
       oshdb.multithreading(multithreading);
       var props = new Properties();
       props.setProperty(OSHDBDriver.OSHDB_PROPERTY_NAME, h2);
       props.setProperty(PREFIX_PROPERTY_NAME, prefix);
-      final var connection = new OSHDBConnection(props, oshdb, keyTables);
+      final var connection = new OSHDBConnection(props, oshdb);
       return connect.apply(connection);
     }
   }
@@ -107,17 +105,19 @@ private static int connectToIgnite(Properties props, Execute connect)
         .filter(value -> value.toLowerCase().startsWith(IGNITE_URI_PREFIX))
         .map(value -> value.substring(IGNITE_URI_PREFIX.length()))
         .orElseThrow();
+    // start ignite
     try (var ignite = Ignition.start(cfg)) {
       var prefix = getInterpolated(props, PREFIX_PROPERTY_NAME).orElseGet(() -> getActive(ignite));
       props.put(PREFIX_PROPERTY_NAME, prefix);
       var keyTablesUrl = getInterpolated(props, OSHDBDriver.KEYTABLES_PROPERTY_NAME)
           .orElseThrow(() -> new IllegalArgumentException("missing keytables"));
       props.put(OSHDBDriver.KEYTABLES_PROPERTY_NAME, keyTablesUrl);
-      try (var ktConnection = DriverManager.getConnection(keyTablesUrl);
-          var keytables = new OSHDBJdbc(ktConnection);
-          var oshdb = new OSHDBIgnite(ignite)) {
+      // initialize data source for keytables
+      try (var dsKeytables = new HikariDataSource();
+          var oshdb = new OSHDBIgnite(ignite, dsKeytables)) {
+        dsKeytables.setJdbcUrl(keyTablesUrl);
         oshdb.prefix(prefix);
-        var connection = new OSHDBConnection(props, oshdb, keytables);
+        var connection = new OSHDBConnection(props, oshdb);
         return connect.apply(connection);
       }
     }
diff --git a/oshdb-helpers/oshdb-database-driver/src/test/java/org/heigit/ohsome/oshdb/helpers/db/OSHDBDriverH2Test.java b/oshdb-helpers/oshdb-database-driver/src/test/java/org/heigit/ohsome/oshdb/helpers/db/OSHDBDriverH2Test.java
index 43026edbe..b3c4f6ece 100644
--- a/oshdb-helpers/oshdb-database-driver/src/test/java/org/heigit/ohsome/oshdb/helpers/db/OSHDBDriverH2Test.java
+++ b/oshdb-helpers/oshdb-database-driver/src/test/java/org/heigit/ohsome/oshdb/helpers/db/OSHDBDriverH2Test.java
@@ -6,7 +6,6 @@
 
 import java.util.Properties;
 import org.heigit.ohsome.oshdb.api.db.OSHDBDatabase;
-import org.heigit.ohsome.oshdb.api.db.OSHDBJdbc;
 import org.heigit.ohsome.oshdb.util.tagtranslator.TagTranslator;
 import org.junit.jupiter.api.DisplayName;
 import org.junit.jupiter.api.Test;
@@ -25,7 +24,6 @@ public OSHDBDriverH2Test() {
   private static int testGetters(OSHDBConnection oshdb) {
     assertTrue(oshdb.getProps() instanceof Properties);
     assertTrue(oshdb.getOSHDB() instanceof OSHDBDatabase);
-    assertTrue(oshdb.getKeytables() instanceof OSHDBJdbc);
     assertTrue(oshdb.getTagTranslator() instanceof TagTranslator);
     return 0;
   }

From 50629e7c453201bca400277b4e77bd5bac6fc05d Mon Sep 17 00:00:00 2001
From: Johannes Visintini <johannes.visintini@heigit.org>
Date: Thu, 10 Nov 2022 16:00:32 +0100
Subject: [PATCH 14/15] OSHDBDriver: set JDBC URL before initializing
 DataSource

---
 .../org/heigit/ohsome/oshdb/helpers/db/OSHDBDriver.java     | 6 ++++--
 1 file changed, 4 insertions(+), 2 deletions(-)

diff --git a/oshdb-helpers/oshdb-database-driver/src/main/java/org/heigit/ohsome/oshdb/helpers/db/OSHDBDriver.java b/oshdb-helpers/oshdb-database-driver/src/main/java/org/heigit/ohsome/oshdb/helpers/db/OSHDBDriver.java
index cb03ad02a..48555fc5b 100644
--- a/oshdb-helpers/oshdb-database-driver/src/main/java/org/heigit/ohsome/oshdb/helpers/db/OSHDBDriver.java
+++ b/oshdb-helpers/oshdb-database-driver/src/main/java/org/heigit/ohsome/oshdb/helpers/db/OSHDBDriver.java
@@ -2,6 +2,7 @@
 
 import static org.heigit.ohsome.oshdb.helpers.db.Util.getInterpolated;
 
+import com.zaxxer.hikari.HikariConfig;
 import com.zaxxer.hikari.HikariDataSource;
 import java.util.Properties;
 import org.apache.ignite.Ignite;
@@ -113,9 +114,10 @@ private static int connectToIgnite(Properties props, Execute connect)
           .orElseThrow(() -> new IllegalArgumentException("missing keytables"));
       props.put(OSHDBDriver.KEYTABLES_PROPERTY_NAME, keyTablesUrl);
       // initialize data source for keytables
-      try (var dsKeytables = new HikariDataSource();
+      var hcKeytables = new HikariConfig();
+      hcKeytables.setJdbcUrl(keyTablesUrl);
+      try (var dsKeytables = new HikariDataSource(hcKeytables);
           var oshdb = new OSHDBIgnite(ignite, dsKeytables)) {
-        dsKeytables.setJdbcUrl(keyTablesUrl);
         oshdb.prefix(prefix);
         var connection = new OSHDBConnection(props, oshdb);
         return connect.apply(connection);

From c2cdf3553f5aad12b13729503668dce22d3354c8 Mon Sep 17 00:00:00 2001
From: Johannes Visintini <johannes.visintini@heigit.org>
Date: Thu, 10 Nov 2022 18:37:47 +0100
Subject: [PATCH 15/15] remove H2 prefix usage in OSHDB(Application|Driver)

---
 .../helpers/applicationtemplate/OSHDBApplication.java    | 2 +-
 .../org/heigit/ohsome/oshdb/helpers/db/OSHDBDriver.java  | 9 +++------
 2 files changed, 4 insertions(+), 7 deletions(-)

diff --git a/oshdb-helpers/oshdb-application-template/src/main/java/org/heigit/ohsome/oshdb/helpers/applicationtemplate/OSHDBApplication.java b/oshdb-helpers/oshdb-application-template/src/main/java/org/heigit/ohsome/oshdb/helpers/applicationtemplate/OSHDBApplication.java
index 8f16cb04e..92505bea3 100644
--- a/oshdb-helpers/oshdb-application-template/src/main/java/org/heigit/ohsome/oshdb/helpers/applicationtemplate/OSHDBApplication.java
+++ b/oshdb-helpers/oshdb-application-template/src/main/java/org/heigit/ohsome/oshdb/helpers/applicationtemplate/OSHDBApplication.java
@@ -56,7 +56,7 @@ static class ConfigOrUrl {
   @Option(names = {"--keytables"}, description = "keytablesUrl jdbc:...")
   protected String keytableUrl;
 
-  @Option(names = {"--prefix"}, description = "prefix to use")
+  @Option(names = {"--prefix"}, description = "prefix to use for ignite")
   protected String prefix;
 
   @Option(names = {
diff --git a/oshdb-helpers/oshdb-database-driver/src/main/java/org/heigit/ohsome/oshdb/helpers/db/OSHDBDriver.java b/oshdb-helpers/oshdb-database-driver/src/main/java/org/heigit/ohsome/oshdb/helpers/db/OSHDBDriver.java
index 48555fc5b..6afc815f9 100644
--- a/oshdb-helpers/oshdb-database-driver/src/main/java/org/heigit/ohsome/oshdb/helpers/db/OSHDBDriver.java
+++ b/oshdb-helpers/oshdb-database-driver/src/main/java/org/heigit/ohsome/oshdb/helpers/db/OSHDBDriver.java
@@ -80,19 +80,17 @@ private static int connectToH2(Properties props, Execute connect)
     var multithreading =
         getInterpolated(props, MULTITHREADING_PROPERTY_NAME).filter("true"::equalsIgnoreCase)
             .isPresent();
-    return connectToH2(h2, prefix, multithreading, connect);
+    return connectToH2(h2, multithreading, connect);
   }
 
   // OSHDBJdbc throws "Exception"
   @SuppressWarnings("java:S112")
-  private static int connectToH2(String h2, String prefix, boolean multithreading,
+  private static int connectToH2(String h2, boolean multithreading,
       Execute connect) throws Exception {
     try (final var oshdb = new OSHDBH2(h2)) {
-      oshdb.prefix(prefix);
       oshdb.multithreading(multithreading);
       var props = new Properties();
       props.setProperty(OSHDBDriver.OSHDB_PROPERTY_NAME, h2);
-      props.setProperty(PREFIX_PROPERTY_NAME, prefix);
       final var connection = new OSHDBConnection(props, oshdb);
       return connect.apply(connection);
     }
@@ -117,8 +115,7 @@ private static int connectToIgnite(Properties props, Execute connect)
       var hcKeytables = new HikariConfig();
       hcKeytables.setJdbcUrl(keyTablesUrl);
       try (var dsKeytables = new HikariDataSource(hcKeytables);
-          var oshdb = new OSHDBIgnite(ignite, dsKeytables)) {
-        oshdb.prefix(prefix);
+          var oshdb = new OSHDBIgnite(ignite, prefix, dsKeytables)) {
         var connection = new OSHDBConnection(props, oshdb);
         return connect.apply(connection);
       }