Commit dd7ef506 authored by Moritz Schott's avatar Moritz Schott Committed by Rafael Troilo
Browse files

Docu enhancement

parent ea0923fc
......@@ -8,33 +8,94 @@
Simple oshdb database driver for opening a connection to ignite or h2 instances.
## Usage:
The OSHDBDriver is simplified connection mechanism for the [OSHDB](https://github.com/GIScience/oshdb). It is configured using a `Properties` object containing the following connection details:
- oshdb
- for a connection to an H2-file this is the absolute path to the H2-file prefixed by "h2:"
- for a connection to an Ignite cluster this is the absolute path to an ignite-config.xml file prefixed by "ignite:"
- prefix
- a string prefixed to database objects to allow multiple data versions to co-exist. You will be notified about this once you get access to an H2-file or the Ignite cluster. It is either empty or mostly something like "global-xxxx" where xxxx is the sequence number from http://api.ohsome.org/v1/metadata
- keytables
- a JDBC string to defining a connection to the keytables linked to the oshdb. This parameter is optional for H2 files as they may already self-contain the keytables
See https://github.com/GIScience/oshdb for more details on the properties.
So first 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("prefix","global");
props.setProperty("keytable","jdbc:postgresql://localhost/keytables-${prefix}?user=ohsome&password=secret");
OSHDBDriver.connect(props, oshdb -> {
try {
OSHDBTagKey tagKeyHighway = oshdb.getTagTranslator().getOSHDBTagKeyOf("highway");
Integer result = oshdb.getSnapshotView()
.areaOfInterest(new OSHDBBoundingBox(8.651133, 49.387611, 8.6561, 49.390513))
.osmType(OSMType.NODE)
.timestamps("2018-05-01")
.count();
System.out.println(result);
} catch (Exception e) {
e.printStackTrace();
}
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 the OSHDB using the oshdb-driver
```java
OSHDBDriver.connect(props, (OSHDBConnection oshdb) -> {
//your oshdb code goes here
});
```
Make sure you handle all exceptions inside the lambda expression.
// or
Alternatively you can connect using one of the specifc type-bound methods such as
OSHDBDriver.connectToIgnite("PATH_TO_CFG", "KEYTABLE_CONNCTION_URL", oshdb -> {
Integer result = oshdb.getSnapshotView()
.areaOfInterest(new OSHDBBoundingBox(8.651133, 49.387611, 8.6561, 49.390513))
...
}
```java
OSHDBDriver.connectToIgnite("PATH_TO_CFG", "KEYTABLES_CONNCTION_URL", oshdb -> {
//your oshdb code goes here
);
```
### Example
```java
package mypackage;
import java.util.Properties;
import org.heigit.bigspatialdata.oshdb.osm.OSMType;
import org.heigit.bigspatialdata.oshdb.util.OSHDBBoundingBox;
import org.heigit.bigspatialdata.oshdb.util.OSHDBTagKey;
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("prefix", "global");
props.setProperty("keytables", "jdbc:postgresql://localhost/keytables-global?user=ohsome&password=secret");
OSHDBDriver.connect(props, oshdb -> {
try {
OSHDBTagKey tagKeyHighway = oshdb.getTagTranslator().getOSHDBTagKeyOf("highway");
Integer result = oshdb.getSnapshotView()
.areaOfInterest(new OSHDBBoundingBox(8.651133, 49.387611, 8.6561, 49.390513))
.osmType(OSMType.NODE)
.timestamps("2018-05-01")
.count();
System.out.println(result);
} catch (Exception e) {
e.printStackTrace();
}
});
}
}
```
......@@ -40,7 +40,7 @@ public class OSHDBDriver {
* <pre>{@code
* oshdb="ignite:Path_To_Config" \ "h2:Path_To_Database"
* prefix="global"
* keytable="jdbc:postgresql://IP_OR_URL/keytables\${prefix}?user=ohsome&password=secret"
* keytables="jdbc:postgresql://IP_OR_URL/keytables\${prefix}?user=ohsome&password=secret"
* #multithreading default false, only used by h2 connections
* multithreading=true
* }</pre>
......@@ -54,11 +54,11 @@ public class OSHDBDriver {
if (oshdb.toLowerCase().startsWith("ignite:")) {
String cfg = oshdb.substring(7);
String prefix = getInterpolated(props, "prefix", "");
String keyTableUrl = getInterpolated(props, "keytable");
if (keyTableUrl == null) {
throw new IllegalArgumentException("ignite specified but missing keytable");
String keyTablesUrl = getInterpolated(props, "keytables");
if (keyTablesUrl == null) {
throw new IllegalArgumentException("ignite specified but missing keytables");
}
connectToIgnite(cfg, prefix, keyTableUrl, connect);
connectToIgnite(cfg, prefix, keyTablesUrl, connect);
} else if (oshdb.toLowerCase().startsWith("h2:")) {
String h2 = oshdb.substring(3);
String prefix = getInterpolated(props, "prefix", "");
......@@ -86,9 +86,9 @@ public class OSHDBDriver {
}
}
public static void connectToIgnite(String cfg, String prefix, String keytableUrl,
public static void connectToIgnite(String cfg, String prefix, String keytablesUrl,
Consumer<OSHDBConnection> connect) throws Exception {
try (final Connection ktConnection = DriverManager.getConnection(keytableUrl);
try (final Connection ktConnection = DriverManager.getConnection(keytablesUrl);
final OSHDBJdbc keytables = new OSHDBJdbc(ktConnection);
final OSHDBIgnite oshdb = new OSHDBIgnite(cfg)) {
oshdb.prefix(prefix);
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment