io.github.whippetdb.db.api

Class DbBuilder<K,V>

java.lang.Object

io.github.whippetdb.db.api.DbBuilder<K,V>

Type Parameters:

K -

V -

public class DbBuilder<K,V>
extends java.lang.Object

Entry point to the database API.

Constructor Summary

Constructors

Constructor and Description
DbBuilder() Build a database with unlimited variable-size key and value and no Map interface.
DbBuilder(int keySize, int valueSize, boolean... hybrid) Build a database with fixed- or hybrid-size fields and no Map interface.
DbBuilder(TypeIO<K> keyType, TypeIO<V> valueType) Build a database a Map interface.

Method Summary

Modifier and Type	Method and Description
java.util.Map<K,V>	asMap() Represents the database as a java.util.Map.
DbBuilder<K,V>	autocommit(boolean b) Wheter to automatically commit each write in journaling mode.
DbBuilder<K,V>	autoflush(boolean b) Whether to instantly persist each write.
DbBuilder<K,V>	create() Creates the in-memory database.
DbBuilder<K,V>	create(java.lang.String path) Creates the on-disk database over a specified file.
Db	db() Return raw interface to the database.
DbBuilder<K,V>	journalDurabilityVsSpeed(float v) Controls the tradeoff between the average write speed and the durability of writes.
DbBuilder<K,V>	journaling(boolean b) Enable journaling.
DbBuilder<K,V>	journalSizeVsSpeed(float v) Chooses the max journal size from a meaningful range, in an exponential way, where 0 corresponds to 2mb, 0.5 to 23mb, and 1 to 130mb.
DbBuilder<K,V>	open(java.lang.String path) Opens the existing on-disk database.
DbBuilder<K,V>	openOrCreate(java.lang.String path) If the file exists tries to open it, otherwise creates a new on-disk database.
DbBuilder<K,V>	speedVsCapacity(float v) Controls the tradeoff between the capacity and speed.
DbBuilder<K,V>	synchronize(boolean b) Whether to ensure a thread safety.
java.lang.String	toString()

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

DbBuilder

public DbBuilder()

Build a database with unlimited variable-size key and value and no Map interface. Use db() to obtain a raw interface.

DbBuilder

public DbBuilder(int keySize,
                 int valueSize,
                 boolean... hybrid)

Build a database with fixed- or hybrid-size fields and no Map interface.

Parameters:

keySize - - key size, ether fixed or limited by this parameter

valueSize - - value size, ether fixed or limited by this parameter

hybrid - - key hybrid flag, value hybrid flag

DbBuilder

public DbBuilder(TypeIO<K> keyType,
                 TypeIO<V> valueType)

Build a database a Map interface. Field sizes are defined by their TypeIO.

Parameters:

keyType - - defines key type and size

valueType - - defines value type and size

Method Detail

speedVsCapacity

public DbBuilder<K,V> speedVsCapacity(float v)

Controls the tradeoff between the capacity and speed.

Parameters:

v - - value in the range 0 (better speed) to 1 (better capacity), default is 0.5

Returns:

- this

journaling

public DbBuilder<K,V> journaling(boolean b)

Enable journaling. In this mode the changes are persisted in an atomic way, guaranteeing the db integrity in the case of an application or system failure. This also causes a significant slowdown of the db. The inserts are slowed down by 20-100 times, depending on the next flags, and the reads by 3-5 times. In journaled mode the db is less compact, because the records are page aligned. If the db was created in the journaled mode, it may be later opened in either journaled or plain mode. If it was created in the plain mode, it may be later opened only in the plain mode. The maximum observed insertion speed in journaling mode with SSD disk was around 260k op/sec.

Parameters:

b - whether to enable journaling

Returns:

this

journalSizeVsSpeed

public DbBuilder<K,V> journalSizeVsSpeed(float v)

Chooses the max journal size from a meaningful range, in an exponential way, where 0 corresponds to 2mb, 0.5 to 23mb, and 1 to 130mb. It controls the tradeoff between the average write speed and the journal RAM footprint. On one hand, the larger is this parameter, the more RAM is taken by the page table. On the other hand, as this parameter increases, the db file is flushed to disk less often, so the average write speed also increases. In the experiments with SSD disk the write speed depended on this parameter non-monotonically, reaching the maximum at 0.55, which is against the expectations and is not yet explained. Thus if you need the maximum write speed, it is recommended to choose this parameter experimentally from the range 0.5-1, or leave the default value untouched.

Parameters:

v - - journal max size preference, the allowed range is 0..1, the default value is 0.5

Returns:

- this

journalDurabilityVsSpeed

public DbBuilder<K,V> journalDurabilityVsSpeed(float v)

Controls the tradeoff between the average write speed and the durability of writes. If the choice is maximum durability (at v=0), each write instantly becomes durable (persistent), but the average write speed is low. The expected speed numbers are 1000 inserts/sec for SSD and 100 inserts/sec for HDD. If the choice is maximum speed (at v=1), a number of last writes may be lost in the case of a system failure. In the case of an application failure the last writes are not at risk. In most situations the recommended value is 1 (max speed). In any case, the atomicity of writes is not affected, in journaling mode they are always atomic.

Parameters:

v - - a preference in the range of 0..1, where 0 is for max durability, 1 for max speed, default is 0.5

Returns:

- this

autocommit

public DbBuilder<K,V> autocommit(boolean b)

Wheter to automatically commit each write in journaling mode. Enabled by default. If you need manual control of commits, disable this parameter and use db().commit() and db().discard() as needed. Note that commits in Whippet are only about the atomicity of writes and only in journaling mode. The durability may be forced by db().flush().

Parameters:

b - - a choice; default is true

Returns:

- this

autoflush

public DbBuilder<K,V> autoflush(boolean b)

Whether to instantly persist each write. Applies both to journaling and plain mode.

Parameters:

b - - a choice; default is false

Returns:

- this

synchronize

public DbBuilder<K,V> synchronize(boolean b)

Whether to ensure a thread safety.

Parameters:

b - - a choice; default is false

Returns:

- this

create

public DbBuilder<K,V> create()

Creates the in-memory database.

Returns:

- this

create

public DbBuilder<K,V> create(java.lang.String path)
                      throws RuntimeIOException

Creates the on-disk database over a specified file. If the specified path is a directory, it creates and uses a temporary file in this directory. This file is deleted when the db is closed or the application exits.

Returns:

- this

Throws:

RuntimeIOException

open

public DbBuilder<K,V> open(java.lang.String path)
                    throws RuntimeIOException

Opens the existing on-disk database.

Returns:

- this

Throws:

RuntimeIOException

openOrCreate

public DbBuilder<K,V> openOrCreate(java.lang.String path)
                            throws RuntimeIOException

If the file exists tries to open it, otherwise creates a new on-disk database.

Returns:

- this

Throws:

RuntimeIOException

asMap

public java.util.Map<K,V> asMap()

Represents the database as a java.util.Map. The database should be opened or created beforehand. The builder must have a key and value data types.

Returns:

- a map

See Also:

DbBuilder(TypeIO, TypeIO)

db

public Db db()

Return raw interface to the database. Provides access to lifecycle methods (e.g. close()) and advanced data access methods.

Returns:

the actual interface to the database

See Also:

Db

toString

public java.lang.String toString()

Overrides:

toString in class java.lang.Object