tkrzw-java/overview.html at master · thecoden/tkrzw-java · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
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
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
<?xml version="1.0" encoding="UTF-8"?>

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">

<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">

<head>
<meta http-equiv="Content-Language" content="en" />
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
<meta http-equiv="Content-Style-Type" content="text/css" />
<meta name="author" content="FAL Labs" />
<meta name="keywords" content="Tkrzw, DBM, Java" />
<meta name="description" content="API specifications of Java binding" />
<link rel="contents" href="./" />
<title>Java Binding of Tkrzw</title>
</head>

<body>

<h1>Java Binding of Tkrzw</h1>

<h2>Introduction</h2>

<p>DBM (Database Manager) is a concept to store an associative array on a permanent storage.  In other words, DBM allows an application program to store key-value pairs in a file and reuse them later.  Each of keys and values is a string or a sequence of bytes.  A key must be unique within the database and a value is associated to it.  You can retrieve a stored record with its key very quickly.  Thanks to simple structure of DBM, its performance can be extremely high.</p>

<p>Tkrzw is a library implementing DBM with various algorithms.  It features high degrees of performance, concurrency, scalability and durability.  The following data structures are provided.</p>

<ul>
<li>HashDBM : File datatabase manager implementation based on hash table.</li>
<li>TreeDBM : File datatabase manager implementation based on B+ tree.</li>
<li>SkipDBM : File datatabase manager implementation based on skip list.</li>
<li>TinyDBM : On-memory datatabase manager implementation based on hash table.</li>
<li>BabyDBM : On-memory datatabase manager implementation based on B+ tree.</li>
<li>CacheDBM : On-memory datatabase manager implementation with LRU deletion.</li>
<li>StdHashDBM : On-memory DBM implementations using std::unordered_map.</li>
<li>StdTreeDBM : On-memory DBM implementations using std::map.</li>
</ul>

<p>Whereas Tkrzw is C++ library, this package provides its Java interface.  All above data structures are available via one adapter class "<a href="tkrzw/DBM.html">DBM</a>".  Read the <a href="http://dbmx.net/tkrzw/">homepage</a> for details.</p>

<p>DBM stores key-value pairs of strings.  Each string is represented as a byte array in Java.  Although you can also use methods with string arguments and return values, their internal representations are byte arrays.</p>

<p>All classes are defined under the package "tkrzw", which can be imported in source files of application programs.</p>

<pre style="margin: 0em 0.8em; padding: 0.3em; background: #f8f8f8 none; border: 1px solid #dddddd; font-size: 90%;">import tkrzw.Status;
import tkrzw.StatusException;
import tkrzw.DBM;
import tkrzw.Iterator;
import tkrzw.Utility;
</pre>

<p>An instance of the class "<a href="tkrzw/DBM.html">DBM</a>" is used in order to handle a database.  You can store, delete, and retrieve records with the instance.  The result status of each operation is represented by an object of the class "<a href="tkrzw/Status.html">Status</a>".  Iterator to access access each record is implemented by the class "<a href="tkrzw/Iterator.html">Iterator</a>".</p>

<h2>Installation</h2>

<p>Install the latest version of Tkrzw beforehand and get the package of the Python binding of Tkrzw.  JDK 9.0 or later is required to use this package.</p>

<p>Enter the directory of the extracted package then perform installation.  The environment variable JAVA_HOME must be set properly.</p>

<pre style="margin: 0em 0.8em; padding: 0.3em; background: #f8f8f8 none; border: 1px solid #dddddd; font-size: 90%;">./configure
make
make check
sudo make install
</pre>

<p>When a series of work finishes, the JAR file "tkrzw.jar" and the shared object files "libjtkrzw.so" and so on are installed under "/usr/local/lib".</p>

<p>Let the class search path include "/usr/local/lib/tkrzw.jar" and let the library search path include "/usr/local/lib".</p>

<pre style="margin: 0em 0.8em; padding: 0.3em; background: #f8f8f8 none; border: 1px solid #dddddd; font-size: 90%;">CLASSPATH="$CLASSPATH:/usr/local/lib/tkrzw.jar"
LD_LIBRARY_PATH="$LD_LIBRARY_PATH:/usr/local/lib"
export CLASSPATH LD_LIBRARY_PATH
</pre>

<p>The above settings can be specified by options of the runtime command.</p>

<pre style="margin: 0em 0.8em; padding: 0.3em; background: #f8f8f8 none; border: 1px solid #dddddd; font-size: 90%;">java -cp .:tkrzw.jar -Djava.library.path=.:/usr/local/lib FooBarBaz ...
</pre>

<h2>Example</h2>

<p>The following code is a simple example to use a database, without checking errors.  Many methods accept both byte arrays and strings.  If strings are given, they are converted implicitly into byte arrays.</p>

<pre style="margin: 0em 0.8em; padding: 0.3em; background: #f8f8f8 none; border: 1px solid #dddddd; font-size: 90%;">import tkrzw.*;

public class Example1 {
  public static void main(String[] args) {
    // Prepares the database.
    DBM dbm = new DBM();
    dbm.open("casket.tkh", true);

    // Sets records.
    // Keys and values are implicitly converted into byte arrays.
    dbm.set("first", "hop");
    dbm.set("second", "step");
    dbm.set("third", "jump");

    // Retrieves record values.
    // If the operation fails, null is returned.
    // If the class of the key is String, the value is converted into String.
    System.out.println(dbm.get("first"));
    System.out.println(dbm.get("second"));
    System.out.println(dbm.get("third"));
    System.out.println(dbm.get("fourth"));

    // Traverses records.
    // After using the iterator, it should be destructed explicitly.
    Iterator iter = dbm.makeIterator();
    iter.first();
    while (true) {
      String[] record = iter.getString();
      if (record == null) {
        break;
      }
      System.out.println(record[0] + ": " + record[1]);
      iter.next();
    }
    iter.destruct();

    // Closes the database.
    // After using the database, it should be destructed explicitly.
    dbm.close();
    dbm.destruct();
  }
}
</pre>

<p>The following code is a typical example to use a database, checking errors.  Usually, objects of DBM and Iterator should be destructed in "finally" blocks to avoid memory leak.  Even if the database is not closed, the destructor closes it implicitly.  The method "orDie" throws an exception on failure so it is useful for checking errors.</p>

<pre style="margin: 0em 0.8em; padding: 0.3em; background: #f8f8f8 none; border: 1px solid #dddddd; font-size: 90%;">import tkrzw.*;

public class Example2 {
  public static void main(String[] args) {
    DBM dbm = new DBM();
    try {
      // Prepares the database, giving tuning parameters.
      Status status = dbm.open(
          "casket.tkh", true, Utility.parseParams("truncate=True,num_buckets=100"));
      // Checks the status explicitly.
      if (!status.isOK()) {
        throw new StatusException(status);
      }

      // Sets records.
      // Throws an exception on failure.
      dbm.set("first", "hop").orDie();
      dbm.set("second", "step").orDie();
      dbm.set("third", "jump").orDie();

      // Retrieves record values.
      String[] keys = {"first", "second", "third", "fourth"};
      for (String key : keys) {
        // Gives a status object to check.
        String value = dbm.get(key, status);
        if (status.isOK()) {
          System.out.println(value);
        } else {
          System.err.println(status);
          if (!status.equals(Status.NOT_FOUND_ERROR)) {
            throw new StatusException(status);
          }
        }
      }

      // Traverses records.
      Iterator iter = dbm.makeIterator();
      try {
        iter.first();
        while (true) {
          String[] record = iter.getString(status);
          if (!status.isOK()) {
            if (!status.equals(Status.NOT_FOUND_ERROR)) {
              throw new StatusException(status);
            }
            break;
          }
          System.out.println(record[0] + ": " + record[1]);
          iter.next();
        }
      } finally {
        // Releases the resources.
        iter.destruct();
      }

      // Closes the database.
      dbm.close().orDie();
    } finally {
      // Releases the resources.
      dbm.destruct();
    }
  }
}
</pre>

</body>

</html>