org.h2.mvstore
Class MVStore

java.lang.Object
  org.h2.mvstore.MVStore

public class MVStore
extends java.lang.Object

A persistent storage for maps.

Nested Class Summary

static class

MVStore.Builder A builder for an MVStore.

Field Summary

static boolean

ASSERT Whether assertions are enabled.

Method Summary

void	close() Close the file and the store.
void	closeImmediately() Close the file and the store, without writing anything.
long	commit() Commit the changes.
boolean	compact(int fillRate) Try to reduce the file size by re-writing partially full chunks.
boolean	compactMoveChunks() Compact the store by moving all chunks next to each other, if there is free space between chunks.
long	getCommittedVersion() Get the last committed version.
long	getCurrentVersion() Get the current version of the data.
FileStore	getFileStore() Get the file store.
MVMap<java.lang.String,java.lang.String>	getMetaMap() Get the metadata map.
int	getPageSplitSize()
long	getRetainVersion() Get the oldest version to retain in memory.
int	getRetentionTime()
boolean	getReuseSpace()
java.util.Map<java.lang.String,java.lang.String>	getStoreHeader() Get the store header.
int	getStoreVersion() Get the store version.
int	getUnsavedPageCount() Get the estimated number of unsaved pages.
int	getUnsavedPageCountMax() Get the maximum number of unsaved pages.
int	getWriteDelay()
boolean	hasMap(java.lang.String name) Check whether a given map exists.
boolean	hasUnsavedChanges() Check whether there are any unsaved changes.
long	incrementVersion() Increment the current version, without committing the changes.
boolean	isClosed()
static MVStore	open(java.lang.String fileName) Open a store in exclusive mode.
<K,V> MVMap<K,V>	openMap(java.lang.String name) Open a map with the default settings.
<M extends MVMap<K,V>,K,V> M	openMap(java.lang.String name, MVMap.MapBuilder<M,K,V> builder) Open a map with the given builder.
void	rollbackTo(long version) Revert to the beginning of the given version.
void	setCacheSize(int mb) Set the read cache size in MB.
void	setRetainVersion(long retainVersion) Which version to retain in memory.
void	setRetentionTime(int ms) How long to retain old, persisted chunks, in milliseconds.
void	setReuseSpace(boolean reuseSpace) Whether empty space in the file should be re-used.
void	setStoreVersion(int version) Update the store version.
void	setWriteDelay(int millis) Set the maximum delay in milliseconds to store committed changes (for file-based stores).
long	store() Commit all changes and persist them to disk.
void	sync() Force all changes to be written to the storage.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

ASSERT

public static final boolean ASSERT

Whether assertions are enabled.

See Also:

Constant Field Values

Method Detail

open

public static MVStore open(java.lang.String fileName)

Open a store in exclusive mode. For a file-based store, the parent directory must already exist.

Parameters:

fileName - the file name (null for in-memory)

Returns:

the store

openMap

public <K,V> MVMap<K,V> openMap(java.lang.String name)

Open a map with the default settings. The map is automatically create if it does not yet exist. If a map with this name is already open, this map is returned.

Type Parameters:

K - the key type

V - the value type

Parameters:

name - the name of the map

Returns:

the map

openMap

public <M extends MVMap<K,V>,K,V> M openMap(java.lang.String name,
                                            MVMap.MapBuilder<M,K,V> builder)

Open a map with the given builder. The map is automatically create if it does not yet exist. If a map with this name is already open, this map is returned.

Type Parameters:

K - the key type

V - the value type

Parameters:

name - the name of the map

builder - the map builder

Returns:

the map

getMetaMap

public MVMap<java.lang.String,java.lang.String> getMetaMap()

Get the metadata map. This data is for informational purposes only. The data is subject to change in future versions. The data should not be modified (doing so may corrupt the store).

It contains the following entries:

 name.{name} = {mapId}
 map.{mapId} = {map metadata}
 root.{mapId} = {root position}
 chunk.{chunkId} = {chunk metadata}
 

Returns:

the metadata map

hasMap

public boolean hasMap(java.lang.String name)

Check whether a given map exists.

Parameters:

name - the map name

Returns:

true if it exists

close

public void close()

Close the file and the store. If there are any committed but unsaved changes, they are written to disk first. If any temporary data was written but not committed, this is rolled back. All open maps are closed.

It is not allowed to concurrently call close and store.

closeImmediately

public void closeImmediately()

Close the file and the store, without writing anything. This will stop the background thread. This method ignores all errors.

incrementVersion

public long incrementVersion()

Increment the current version, without committing the changes.

Returns:

the new version

commit

public long commit()

Commit the changes. This method marks the changes as committed and increments the version.

Unless the write delay is set to 0, this method does not write to the file. Instead, data is written after the delay, manually by calling the store method, when the write buffer is full, or when closing the store.

Returns:

the new version

store

public long store()

Commit all changes and persist them to disk. This method does nothing if there are no unsaved changes, otherwise it increments the current version and stores the data (for file based stores).

One store operation may run at any time.

Returns:

the new version (incremented if there were changes)

hasUnsavedChanges

public boolean hasUnsavedChanges()

Check whether there are any unsaved changes.

Returns:

if there are any changes

compactMoveChunks

public boolean compactMoveChunks()

Compact the store by moving all chunks next to each other, if there is free space between chunks. This might temporarily double the file size. Chunks are overwritten irrespective of the current retention time. Before overwriting chunks and before resizing the file, syncFile() is called.

Returns:

if anything was written

sync

public void sync()

Force all changes to be written to the storage. The default implementation calls FileChannel.force(true).

compact

public boolean compact(int fillRate)

Try to reduce the file size by re-writing partially full chunks. Chunks with a low number of live items are re-written. If the current fill rate is higher than the target fill rate, nothing is done.

Only data of open maps can be moved. For maps that are not open, the old chunk is still referenced. Therefore, it is recommended to open all maps before calling this method.

Parameters:

fillRate - the minimum percentage of live entries

Returns:

if anything was written

getPageSplitSize

public int getPageSplitSize()

getReuseSpace

public boolean getReuseSpace()

setReuseSpace

public void setReuseSpace(boolean reuseSpace)

Whether empty space in the file should be re-used. If enabled, old data is overwritten (default). If disabled, writes are appended at the end of the file.

This setting is specially useful for online backup. To create an online backup, disable this setting, then copy the file (starting at the beginning of the file). In this case, concurrent backup and write operations are possible (obviously the backup process needs to be faster than the write operations).

Parameters:

reuseSpace - the new value

getRetentionTime

public int getRetentionTime()

setRetentionTime

public void setRetentionTime(int ms)

How long to retain old, persisted chunks, in milliseconds. Chunks that are older may be overwritten once they contain no live data.

The default value is 45000 (45 seconds) when using the default file store. It is assumed that a file system and hard disk will flush all write buffers within this time. Using a lower value might be dangerous, unless the file system and hard disk flush the buffers earlier. To manually flush the buffers, use MVStore.getFile().force(true), however please note that according to various tests this does not always work as expected depending on the operating system and hardware.

This setting is not persisted.

Parameters:

ms - how many milliseconds to retain old chunks (0 to overwrite them as early as possible)

setRetainVersion

public void setRetainVersion(long retainVersion)

Which version to retain in memory. If not set, all versions back to the last stored version are retained.

Parameters:

retainVersion - the oldest version to retain

getRetainVersion

public long getRetainVersion()

Get the oldest version to retain in memory.

Returns:

the version

getUnsavedPageCount

public int getUnsavedPageCount()

Get the estimated number of unsaved pages. The returned value is not accurate, specially after rollbacks, but can be used to estimate the memory usage for unsaved data.

Returns:

the number of unsaved pages

getUnsavedPageCountMax

public int getUnsavedPageCountMax()

Get the maximum number of unsaved pages. If this number is exceeded, the unsaved changes are stored to disk, including uncommitted changes. Saved uncommitted changes are rolled back when opening the store.

Returns:

the number of maximum unsaved pages

getStoreVersion

public int getStoreVersion()

Get the store version. The store version is usually used to upgrade the structure of the store after upgrading the application. Initially the store version is 0, until it is changed.

Returns:

the store version

setStoreVersion

public void setStoreVersion(int version)

Update the store version.

Parameters:

version - the new store version

rollbackTo

public void rollbackTo(long version)

Revert to the beginning of the given version. All later changes (stored or not) are forgotten. All maps that were created later are closed. A rollback to a version before the last stored version is immediately persisted. Rollback to version 0 means all data is removed.

Parameters:

version - the version to revert to

getCurrentVersion

public long getCurrentVersion()

Get the current version of the data. When a new store is created, the version is 0.

Returns:

the version

getCommittedVersion

public long getCommittedVersion()

Get the last committed version.

Returns:

the version

getFileStore

public FileStore getFileStore()

Get the file store.

Returns:

the file store

getStoreHeader

public java.util.Map<java.lang.String,java.lang.String> getStoreHeader()

Get the store header. This data is for informational purposes only. The data is subject to change in future versions. The data should not be modified (doing so may corrupt the store).

Returns:

the store header

setCacheSize

public void setCacheSize(int mb)

Set the read cache size in MB.

Parameters:

mb - the cache size in MB.

isClosed

public boolean isClosed()

setWriteDelay

public void setWriteDelay(int millis)

Set the maximum delay in milliseconds to store committed changes (for file-based stores).

The default is 1000, meaning committed changes are stored after at most one second.

When the value is set to -1, committed changes are only written when calling the store method. When the value is set to 0, committed changes are immediately written on a commit, but please note this decreases performance and does still not guarantee the disk will actually write the data.

Parameters:

millis - the maximum delay

getWriteDelay

public int getWriteDelay()