RegisterSign In

API Documentation: Class LocalFileSystemDatabase

Package: com.mckoi.data
implements com.mckoi.data.KeyObjectDatabase

A database implementation that uses the com.mckoi.database.store API to persist data structures in the local file system with a simple configuration. This object implements a full range of features including journaling and a heap cache.

The directory specified in the local file system will contain one or more 'data.koi' files, journal files 'jnl*' and a lock file. The name of the file resources may not be changed, therefore storing multiple database repositories in the same directory is not permitted.

By default, this object operates with conservative cache options allocating 8MB for the page cache (maximum of 1,024 8KB pages). File rollover is set to 512MB (the maximum size a file will grow to before new data blocks are stored in a new file).

Node and branch cache size is set to 14MB and 2MB respectively. In the default configuration, the object may use as much as 30MB of heap on cached content alone.

All cache sizes can be configured as necessary.

This object is useful for creating embedded database instances inside a Java application. It does not have any networking or concurrency control features.

Constructors Summary

LocalFileSystemDatabase(File the_path)

Methods Summary

void setPageSize(int page_size)
int getPageSize()
void setMaxPageCount(int page_count)
int getMaxPageCount()
void setFileRolloverSize(long size)
long getFileRolloverSize()
void setBranchNodeSize(int branch_size)
int getBranchNodeSize()
void setLeafNodeSize(int leaf_size)
int getLeafNodeSize()
void setHeapNodeCacheSize(int heap_node_cache_size)
long getHeapNodeCacheSize()
void setBranchNodeCacheSize(int branch_node_cache_size)
long getBranchNodeCacheSize()
boolean start() throws IOException
void stop() throws IOException
StoreBackedTreeSystem getTreeSystem()
TreeReportNode createDiagnosticGraph() throws IOException
KeyObjectTransaction createTransaction()
void publish(KeyObjectTransaction transaction)
void dispose(KeyObjectTransaction transaction)
void checkPoint()

Constructor Details

LocalFileSystemDatabase(File the_path)

Constructs the file system database with the given local path to the repository in the local file system where the data is to be stored.

Method Details

void setPageSize(int page_size)

Set the page size.

int getPageSize()

The page size of data read by the buffer manager when accessing information in the database file(s).

Default is 8KB = (8 * 1024).

void setMaxPageCount(int page_count)

Set the maximum number of pages stored in the cache.

int getMaxPageCount()

The page size cache (the maximum number of pages that can be held by the buffer manager).

Default is 1024.

void setFileRolloverSize(long size)

Sets the file rollover size in bytes.

long getFileRolloverSize()

The file size rollover value (the number of bytes stored in a data file before expansion of the file is rolled over into a new file).

Default is 512MB = (512 * 1024 * 1024)

void setBranchNodeSize(int branch_size)

Sets the maximum number of pointers in a branch element (must be an even value > 6).

int getBranchNodeSize()

The size of a branch node (the maximum number of pointers on a branch node).

Default is 16.

void setLeafNodeSize(int leaf_size)

Sets the maximum number of bytes that can be stored in a leaf element in the tree.

int getLeafNodeSize()

The size of a leaf node (the maximum number of bytes of data that can be stored on a leaf node).

Default is 4010.

void setHeapNodeCacheSize(int heap_node_cache_size)

Sets the size, in bytes, of all nodes stored on the heap during write operations before nodes are flushed to the backing store.

long getHeapNodeCacheSize()

The size, in bytes, of all nodes stored on the heap during write operations before nodes are flushed to the backing store.

Default is 14MB = (14 * 1024 * 1024).

void setBranchNodeCacheSize(int branch_node_cache_size)

Sets the size of the cache for storing branch nodes.

long getBranchNodeCacheSize()

The maximum heap size of branch nodes stored in the cache.

Default is 2MB = (2 * 1024 * 1024).

boolean start()

Initializes the storage objects and returns from this method when the data system is in an initialized state and ready to accept transaction requests. Throws IOException if initialization failed due to a data integrity error.

Returns true if the start operation succeeded, false if the database already started and initialized.

void stop()

Stops the storage objects and returns when the data storage system has cleanly shut down.

StoreBackedTreeSystem getTreeSystem()

Returns the underlying StoreBackedTreeSystem object.

TreeReportNode createDiagnosticGraph()

Generates a diagnostic graph object of the entire database state.

KeyObjectTransaction createTransaction()

Returns a KeyObjectTransaction object that represents the most current view of the database and allows isolated read and write operations on the data including creating new key/data entries and modifying and removing existing entries.

The returned object is NOT thread safe and may have various other restrictions on its use depending on the implementation. However, the implemented transaction object should generally provide efficient implementations on its function.

void publish(KeyObjectTransaction transaction)

Publishes the transaction as the most current version of the database state. The given KeyObjectTransaction object must be a modified form of the most recent version committed otherwise this operation will fail. For example, the following sequence will cause an exception;

t1 = createTransaction(); t2 = createTransaction(); publish(t1); publish(t2);

In the example above, the first publish will be successful but the second publish will fail because t2 is no longer backed by the most recent version.

If it is necessary to publish changes from an old view then the various data copy/merge facilities should be used (eg. if this is part of a general commit/consensus function). It is left to the database model to track database changes to manage version publish merge operations. The reason for this is because operations such as index merges can not be supported in a general way at this level.

void dispose(KeyObjectTransaction transaction)

Disposes a transaction. If the transaction was not published by the 'publish' method above, then all data created in the transaction will be deleted. If the transaction was published, the transaction is marked 'out of scope' and the database may choose to reclaim resources associated with the transaction.

void checkPoint()

If the underlying data storage structure supports check points, syncs all the updates to the database up to this point in time. This method provides some guarantee that information written to the database is consistent over multiple invocations. A check point will typically result in a sync and journal flush.

It is intended for check points to happen immediately after a publish, but it is not necessary and check points can be made at any time.

The text on this page is licensed under the Creative Commons Attribution 3.0 License. Java is a registered trademark of Oracle and/or its affiliates.
Mckoi is Copyright © 2000 - 2020 Diehl and Associates, Inc. All rights reserved.