org.gillius.realdb.model
Class Database

java.lang.Object
  org.gillius.realdb.model.Database

All Implemented Interfaces:

java.io.Closeable, java.io.Flushable, Formattable

public class Database
extends java.lang.Object
implements Formattable, java.io.Flushable, java.io.Closeable

The Database class is the main class to be used in RealDB. A Database holds a set of DataStream objects for reading and writing data. The static factory methods or the DatabaseBuilder can be used to obtain a Database instance.

Author:

Jason Winnebeck

Constructor Summary

Database(BlockFile file, MetadataSection metadata, BlockPool pool, DataIndexSection index, DataSection data)
Constructs a new Database with all of the sections already loaded and configured.

Method Summary

void	close() Closes the database by flushing all buffers and closing any open resources.
static Database	createNew(BlockFile bf, MetadataSection metadata) Creates a new Database and formats the given BlockFile with it.
void	flush() Flushes the Database, but keeps it open for further operations.
void	forceClose() Forces the underlying BlockFile to be closed immediately without flushing any data remaining to be written.
void	format() Clears out the database entirely by reformatting the index and data sections.
int	getBlockSize() Returns the block size, in bytes, of the underlying storage.
int	getDataBlocksUsed() Returns the number of data blocks used.
MetadataSection	getMetadata()
DatabaseStatistics	getProfilingStatistics() If this Database is enabled for profiling, returns a DatabaseStatistics, else returns null.
java.util.Map<java.lang.String,java.lang.Integer>	getSectionSizes() Returns a mapping of section names to their sizes in blocks.
int	getSizeInBlocks() Returns the size of the database, in blocks.
java.util.Collection<DataStream>	getStreams() Returns all of the DataStreams in this database.
java.util.Map<java.lang.Integer,DataStream>	getStreamsMap() Returns a map of DataStream user ID to DataStream.
int	getTotalDataBlocks() Returns the total number of data blocks.
static Database	load(BlockFile bf) Loads a database from a properly constructed BlockFile.
static Database	load(java.io.File f) Loads a database from the given File.
static Database	load(java.io.File f, boolean profiling) Loads a database from the given File.

Methods inherited from class java.lang.Object

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

Constructor Detail

Database

public Database(BlockFile file,
                MetadataSection metadata,
                BlockPool pool,
                DataIndexSection index,
                DataSection data)

Constructs a new Database with all of the sections already loaded and configured.

Parameters:

file - nullable BlockFile, used only in the close method.

Method Detail

getMetadata

public MetadataSection getMetadata()

getSectionSizes

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

Returns a mapping of section names to their sizes in blocks. All of the sections are entirely accounted for and none overlap. Therefore, the values should add up to the file's size in blocks except for any "slack" space (odd unused blocks at the end)

getDataBlocksUsed

public int getDataBlocksUsed()

Returns the number of data blocks used. A data block normally consists of multiple file blocks, so this is not the same value as from getSectionSizes().

getTotalDataBlocks

public int getTotalDataBlocks()

Returns the total number of data blocks. A data block normally consists of multiple file blocks, so this is not the same value as from getSectionSizes().

getBlockSize

public int getBlockSize()

Returns the block size, in bytes, of the underlying storage.

getSizeInBlocks

public int getSizeInBlocks()

Returns the size of the database, in blocks.

getStreams

public java.util.Collection<DataStream> getStreams()

Returns all of the DataStreams in this database.

getStreamsMap

public java.util.Map<java.lang.Integer,DataStream> getStreamsMap()

Returns a map of DataStream user ID to DataStream.

format

public void format()
            throws java.io.IOException

Clears out the database entirely by reformatting the index and data sections. The file header and metadata sections are unchanged. If a format operation fails, the underlying file is an undefined state. You can try to format it again, but that is the only allowed operation on such a file.

Specified by:

format in interface Formattable

Throws:

java.io.IOException - if an error occurs writing the database

flush

public void flush()
           throws java.io.IOException

Flushes the Database, but keeps it open for further operations. Flushing a database will commit all changes to disk. If this operation succeeds, any data written can be recovered if a failure occurs later. If this operation fails, then some or all data could be lost in the database since the last flush.

Specified by:

flush in interface java.io.Flushable

Throws:

java.io.IOException

close

public void close()
           throws java.io.IOException

Closes the database by flushing all buffers and closing any open resources. A close operation is performed on the underlying file, if there is one. Once a Database is closed, it and nothing that comes from it should be used again, but the Database may be reloaded with load(java.io.File) later.

If an IOException is thrown while trying to close the database, the underlying file, if there is one, is forcefully closed to release this resource. In this case not all streams and buffers were flushed properly.

Specified by:

close in interface java.io.Closeable

Throws:

java.io.IOException

forceClose

public void forceClose()

Forces the underlying BlockFile to be closed immediately without flushing any data remaining to be written.

TODO: remove this method when RealDB code is exception-safe.

getProfilingStatistics

public DatabaseStatistics getProfilingStatistics()

If this Database is enabled for profiling, returns a DatabaseStatistics, else returns null.

createNew

public static Database createNew(BlockFile bf,
                                 MetadataSection metadata)
                          throws java.io.IOException

Creates a new Database and formats the given BlockFile with it. This includes writing of the file header and serialization of the given MetadataSection.

Parameters:

bf - BlockFile where DB will be created or loaded

metadata - Constructed MetadataSection

Returns:

non-null new Database

Throws:

java.io.IOException - if there is an error writing to the file. If this occurs the file may have been partially written.

load

public static Database load(java.io.File f)
                     throws java.io.IOException,
                            BadFileException

Loads a database from the given File.

Parameters:

f - non-null existing File

Returns:

non-null Database

Throws:

java.io.IOException - if an error occurs accessing the file

BadFileException - if the file is read, but the data is unrecoverably corrupted

load

public static Database load(java.io.File f,
                            boolean profiling)
                     throws java.io.IOException,
                            BadFileException

Loads a database from the given File.

Parameters:

f - non-null existing File

profiling - if true, enables collection of profiling statistics (has some overhead).

Returns:

non-null Database

Throws:

java.io.IOException - if an error occurs accessing the file

BadFileException - if the file is read, but the data is unrecoverably corrupted

load

public static Database load(BlockFile bf)
                     throws java.io.IOException,
                            BadFileException

Loads a database from a properly constructed BlockFile. The file header is in the first block and its block size is checked against the given BlockFile size and the versions are checked.

Parameters:

bf - non-null BlockFile

Returns:

new Database attached to the given BlockFile.

Throws:

java.io.IOException - if an error occurs accessing the file

BadFileException - if the file is read, but the data is unrecoverably corrupted