API Documentation: Class SDBFile

An object that represents a file in the Simple Database API. A file is a bounded collection of bytes that can grow and shrink in size, and provides a pointer that can be positioned at any location in the file to read and write data from the file content. Simple Database files provide an efficient shift function for creating or deleting arbitrary areas of the file. In addition, SDBFile objects can be efficiently 'shadow copied' by using the 'copyTo' method.

Note that SDBFile borrows all of its functionality from an implementation of com.mckoi.data.DataFile, therefore supports all the DataFile wrapping classes in the com.mckoi.data package.

Methods Summary

Method Details

String getName()

Returns the name of this file.

void copyFrom(DataFile from, long size)

Copies 'size' amount of data from the current position in the 'from' file to this DataFile at its position location. If there is less data remaining in this file than 'size', then only the remaining data available is copied. Any data in this DataFile past its position is shifted forward by the amount of data that is being copied from the target.

The 'from' DataFile may be a file in the same transaction as this DataFile or it may be a file in a different transaction, or even a file in another KeyObjectDatabase. However, the given DataFile may NOT be the same file as this or an instantiated file with the same key from the same transaction. In other words, you can not use this to move data inside one DataFile object in one transaction.

This copy routine may employ any number of optimization tricks. For example, data copied to a file in a different transaction but in the same database may just need to do some meta tree manipulation operations and reference updates.

It is intended for this operation to be a versatile and efficient way to merge data between transactions. For example, provided no consistency checks fail, we may need to perform a series of copy operations on data from a transaction several versions before the current transaction to update the latest transaction version.

This method also provides us a way to express to the data storage system a form of compression of datasets that contain near identical information repeated with slight variations. Used appropriately, this may improve performance by increasing cache hits and reducing disk reads.

When this method returns, the position location in both the source and target will point to the end of the copied sequence.

void replicateFrom(DataFile from)

Replaces the entire contents of this file with the content of the given file in entirety. When this method returns, the target DataFile will be the same size and contain the same data as this file. This is the same as following code sequence; 'this.delete(); from.position(0); this.copyFrom(from, from.size())'

Like 'copyFrom', this may employ a number of optimization tricks to perform the operation efficiently, including not changing anything at all if the contents are determined to be the same.

It is intended that this operation looks for the changes between this and the target and only copies the meta-data that has changed. This leads to efficient replication of large content.

When this method returns, the position location in both the source and destination will point to the end of the content.

void copyTo(DataFile target, long size)

Legacy method - 'copyFrom' with reversed targets. This should always be implemented as 'target.copyFrom(this, size)'

void replicateTo(DataFile target)

Legacy method - 'replicateFrom' with reversed targets. This should always be implemented as 'target.replicateFrom(this)'

Object getBlockLocationMeta(long start_position, long end_position)

Returns an object that describes a fully qualified addressable location of the data representing this DataFile from the start position (inclusive) to the end position (exclusive). The object returned is entirely implementation specific, and is used by the 'copyFrom' and 'replicateFrom' methods to optimize the block replication methods. Calling 'df.getBlockLocationMeta(0, df.size())' will return a meta object describing the complete file content.

This method may return null, which signifies that the content of the file is not eligible to be replicated using a block replication method. For example, a DataFile that has content entirely on the Java Heap should return null for this method.

For security reasons, the object returned should not expose information about the data being addressed.

void delete()

Deletes all data in the file. When this returns the size of the file will be 0.

byte get()

Returns the byte at the current position and forwards the position pointer by 1.

void get(byte[] buf, int off, int len)

Fills the given byte[] array with 'len' number of bytes at the current position and forwards the position pointer by len. The bytes are filled at 'off' offset within the byte[] array. If there is not enough data available in the data file to fulfill the request a RuntimeException is generated.

char getChar()

Returns the unicode character value (16 bits) at the current position and forwards the position pointer by 2.

int getInt()

Returns the integer value (32 bits) at the current position and forwards the position pointer by 4.

long getLong()

Returns the long value (64 bits) at the current position and forwards the position pointer by 8.

short getShort()

Returns the short value (16 bits) at the current position and forwards the position pointer by 2.

void position(long position)

Changes the position of the pointer within the data sequence address space, where position(0) moves to the first location in the sequence.

long position()

Returns the current pointer location.

void put(byte b)

Writes a byte at the current position and forwards the position pointer by 1. Any existing data at the position is overwritten. If the position location is at the end of the file, the size is increased by the size of the data being written.

void put(byte[] buf, int off, int len)

Writes a length 'len' of the byte[] array starting at offset 'off' at the current position and moves the position pointer forward by 'len'. Any existing data in the file past the current position is overwritten by this operation (up to the amount of data written). If, during the write, the position extends past the end of the file, the size of the file is increased to make room of the data being written.

void put(byte[] buf)

Writes the entire byte[] array at the current position and moves the position pointer forward by the size of the array. Any existing data in the file past the current position is overwritten by this operation (up to the amount of data written). If, during the write, the position extends past the end of the file, the size of the file is increased to make room of the data being written.

void putChar(char c)

Writes a character value (16 bits) at the current position and forwards the position pointer by 2. Any existing data at the position is overwritten. If the position location is at the end of the file, the size is increased by the size of the data being written.

void putInt(int i)

Writes an integer value (32 bits) at the current position and forwards the position pointer by 4. Any existing data at the position is overwritten. If the position location is at the end of the file, the size is increased by the size of the data being written.

void putLong(long l)

Writes a long value (64 bits) at the current position and forwards the position pointer by 8. Any existing data at the position is overwritten. If the position location is at the end of the file, the size is increased by the size of the data being written.

void putShort(short s)

Writes a short value (16 bits) at the current position and forwards the position pointer by 2. Any existing data at the position is overwritten. If the position location is at the end of the file, the size is increased by the size of the data being written.

void setSize(long size)

Sets the size of the file. If the size set is smaller than the current size then the file is truncated. If the size is greater than the current size then extra space is added to the end of the file. We do not define the content of the extra space created in a file by this way.

void shift(long offset)

Shifts all the data after the position location by the given offset. A negative value will shift all the data backward and reduce the size of the file. A positive value will shift all the data forward and increase the size of the file. When shifting forward, the content of the space between 'position' and 'position + shift' is not defined by this contract.

The position location is not changed after using this operation.

This method is intended to be used when there is a need to insert data or remove data before the end of the file. It is expected that implementations of this method are able to efficiently shift large magnitudes of data. For example, shifting 10 MB of data forward by 8 bytes should be efficient.

long size()

Returns the size of the data file address space in bytes.