org.h2.mvstore
Class MVStore

java.lang.Object
  extended by 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 targetFillRate, int minSaving)
          Try to increase the fill rate 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.
 int getAutoCommitDelay()
          Get the auto-commit delay.
 int getAutoCommitPageCount()
          Get the maximum number of unsaved pages.
 CacheLongKeyLIRS<Page> getCache()
          Get the cache.
 int getCacheSize()
          Get the maximum cache size, in MB.
 int getCacheSizeUsed()
          Get the amount of memory used for caching, in MB.
 long getCurrentVersion()
          Get the current version of the data.
 FileStore getFileStore()
          Get the file store.
 java.lang.String getMapName(int id)
          Get the name of the given map.
 java.util.Set<java.lang.String> getMapNames()
          Get the set of all map names.
 MVMap<java.lang.String,java.lang.String> getMetaMap()
          Get the metadata map.
 int getPageSplitSize()
           
 int getRetentionTime()
           
 boolean getReuseSpace()
           
 java.util.Map<java.lang.String,java.lang.Object> getStoreHeader()
          Get the store header.
 int getStoreVersion()
          Get the store version.
 int getUnsavedPageCount()
          Get the estimated number of unsaved pages.
 long getVersionsToKeep()
          Get the oldest version to retain in memory (for in-memory stores).
 boolean hasMap(java.lang.String name)
          Check whether a given map exists.
 boolean hasUnsavedChanges()
          Check whether there are any unsaved 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 removeMap(MVMap<?,?> map)
          Remove a map.
 void renameMap(MVMap<?,?> map, java.lang.String newName)
          Rename a map.
 void rollback()
          Revert to the beginning of the current version, reverting all uncommitted changes.
 void rollbackTo(long version)
          Revert to the beginning of the given version.
 void setAutoCommitDelay(int millis)
          Set the maximum delay in milliseconds to auto-commit changes.
 void setCacheSize(int mb)
          Set the read cache size in MB.
 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 setVersionsToKeep(int count)
          How many versions to retain for in-memory stores.
 void sync()
          Force all stored 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

getMapNames

public java.util.Set<java.lang.String> getMapNames()
Get the set of all map names.

Returns:
the set of names

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 in this map should not be modified (changing system data may corrupt the store). If modifications are needed, they need be synchronized on the store.

The metadata map contains the following entries:

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

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. Unsaved changes are written to disk first.


closeImmediately

public void closeImmediately()
Close the file and the store, without writing anything. This will stop the background thread. This method ignores all errors.


commit

public long commit()
Commit the changes.

For in-memory stores, this method increments the version.

For persistent stores, it also writes changes to disk. It does nothing if there are no unsaved changes, and returns the old version. It is not necessary to call this method when auto-commit is enabled (the default setting), as in this case it is automatically called from time to time or when enough changes have accumulated. However, it may still be called to flush all changes to disk.

Returns:
the new version

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 stored changes to be written to the storage. The default implementation calls FileChannel.force(true).


compact

public boolean compact(int targetFillRate,
                       int minSaving)
Try to increase the fill rate 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. If not at least a minimum amount of space can be saved, nothing is done.

Please note this method will not necessarily reduce the file size, as empty chunks are not overwritten.

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:
targetFillRate - the minimum percentage of live entries
minSaving - the minimum amount of saved space
Returns:
if a chunk was re-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)

setVersionsToKeep

public void setVersionsToKeep(int count)
How many versions to retain for in-memory stores. If not set, 5 old versions are retained.

Parameters:
count - the number of versions to keep

getVersionsToKeep

public long getVersionsToKeep()
Get the oldest version to retain in memory (for in-memory stores).

Returns:
the version

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

rollback

public void rollback()
Revert to the beginning of the current version, reverting all uncommitted changes.


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

getFileStore

public FileStore getFileStore()
Get the file store.

Returns:
the file store

getStoreHeader

public java.util.Map<java.lang.String,java.lang.Object> 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

renameMap

public void renameMap(MVMap<?,?> map,
                      java.lang.String newName)
Rename a map.

Parameters:
map - the map
newName - the new name

removeMap

public void removeMap(MVMap<?,?> map)
Remove a map.

Parameters:
map - the map

getMapName

public java.lang.String getMapName(int id)
Get the name of the given map.

Parameters:
id - the map id
Returns:
the name, or null if not found

setCacheSize

public void setCacheSize(int mb)
Set the read cache size in MB.

Parameters:
mb - the cache size in MB.

isClosed

public boolean isClosed()

setAutoCommitDelay

public void setAutoCommitDelay(int millis)
Set the maximum delay in milliseconds to auto-commit changes.

To disable auto-commit, set the value to 0. In this case, changes are only committed when explicitly calling commit.

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

Parameters:
millis - the maximum delay

getAutoCommitDelay

public int getAutoCommitDelay()
Get the auto-commit delay.

Returns:
the delay in milliseconds, or 0 if auto-commit is disabled.

getAutoCommitPageCount

public int getAutoCommitPageCount()
Get the maximum number of unsaved pages. If this number is exceeded, unsaved changes are stored to disk.

Returns:
the number of maximum unsaved pages

getUnsavedPageCount

public int getUnsavedPageCount()
Get the estimated number of unsaved pages. If the value exceeds the auto-commit page count, the changes are committed.

The returned value may not be completely accurate, but can be used to estimate the memory usage for unsaved data.

Returns:
the number of unsaved pages

getCacheSizeUsed

public int getCacheSizeUsed()
Get the amount of memory used for caching, in MB.

Returns:
the amount of memory used for caching

getCacheSize

public int getCacheSize()
Get the maximum cache size, in MB.

Returns:
the cache size

getCache

public CacheLongKeyLIRS<Page> getCache()
Get the cache.

Returns:
the cache