README.md 4.04 KB
Newer Older
1
# OSHDB Database Driver
Rafael Troilo's avatar
Rafael Troilo committed
2

Martin Raifer's avatar
Martin Raifer committed
3
[![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)
4
5
6
7
8
[![Sonarcloud Status](https://sonarcloud.io/api/project_badges/measure?project=org.heigit.ohsome.oshdb.helpers:OSHDBDriver&metric=alert_status)](https://sonarcloud.io/dashboard?id=org.heigit.ohsome.oshdb.helpers:OSHDBDriver)
[![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 database driver for opening a connection to ignite or h2 instances.
Martin Raifer's avatar
Martin Raifer committed
9

Rafael Troilo's avatar
Rafael Troilo committed
10
## Usage:
Moritz Schott's avatar
Moritz Schott committed
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

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

Rafael Troilo's avatar
Rafael Troilo committed
26
```java
Rafael Troilo's avatar
Rafael Troilo committed
27
   Properties props = new Properties();
Rafael Troilo's avatar
Rafael Troilo committed
28
    //props.put("oshdb", "h2:PATH_TO_H2");
Rafael Troilo's avatar
Rafael Troilo committed
29
30
    props.setProperty("oshdb","ignite:PATH_TO_CFG");
    props.setProperty("prefix","global");
Moritz Schott's avatar
Moritz Schott committed
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
    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
Rafael Troilo's avatar
Rafael Troilo committed
48
    });
Moritz Schott's avatar
Moritz Schott committed
49
50
51
```

Make sure you handle all exceptions inside the lambda expression.
Martin Raifer's avatar
Martin Raifer committed
52

Moritz Schott's avatar
Moritz Schott committed
53
Alternatively you can connect using one of the specifc type-bound methods such as 
Martin Raifer's avatar
Martin Raifer committed
54

Moritz Schott's avatar
Moritz Schott committed
55
56
57
```java
    OSHDBDriver.connectToIgnite("PATH_TO_CFG", "KEYTABLES_CONNCTION_URL", oshdb -> {
        //your oshdb code goes here
Rafael Troilo's avatar
Rafael Troilo committed
58
59
    );
```
Moritz Schott's avatar
Moritz Schott committed
60
61
62
63
64
65
66
67

### Example


```java
package mypackage;

import java.util.Properties;
68
69
70
import org.heigit.ohsome.oshdb.osm.OSMType;
import org.heigit.ohsome.oshdb.util.OSHDBBoundingBox;
import org.heigit.ohsome.oshdb.util.OSHDBTagKey;
Moritz Schott's avatar
Moritz Schott committed
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
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();
            }
        });
    }

}
```