mobios.mckoi.store
Interface Store

All Known Implementing Classes:

AbstractStore, ScatteringFileStore

public interface Store

A store is a resource where areas can be allocated and freed to store objects. A store can be backed by a file or main memory, or a combination of the two.

Some characteristics of implementations of Store may be separately specified. For example, a file based store that is intended to persistently store objects may have robustness as a primary requirement. A main memory based store, or other type of volatile store, may not require robustness.

Author:

Tobias Downer

Method Summary

long	alloc(long size) Allocates a block of memory out of the store of the specified size, and returns a pointer to the block.
void	flush() Flushes any changes to the underlying storage device if the store implements memory mapping or buffering.
void	free(long pointer) Frees a block of memory from the store that was previously allocated via 'alloc'.
List	getAllAreas() Returns a complete list of pointers to all areas in the Store as Long objects sorted from lowest pointer to highest.
Area	getArea(long pointer) Returns an Area object that can be used to manipulate an area allocated from the store.
Area	getFixedArea() Returns an Area object that represents the 64 byte fixed area as can be changed by the 'getFixedArea' and 'setFixedArea' methods.
InputStream	getInputStream(long pointer) Returns an InputStream for reading from the area of the store allocated via the 'alloc' method.
OutputStream	getOutputStream(long pointer) Returns an OutputStream for writing to the area of the store allocated via the 'alloc' method.
boolean	lastCloseClean() Returns true if the store was closed cleanly.
void	synch() Flushes and synchronizes any changes made to the store with the underlying persistent device.

Method Detail

alloc

long alloc(long size)
           throws IOException

Allocates a block of memory out of the store of the specified size, and returns a pointer to the block. If the store can not allocate an area of memory large enough for the request, a StoreException exception is thrown. This also throws a StoreException if the backing store is read-only.

Parameters:

size - the amount of memory to allocate.

Returns:

a 64-bit pointer to the allocated memory.

Throws:

IOException - is the allocation can not happen.

free

void free(long pointer)
          throws IOException

Frees a block of memory from the store that was previously allocated via 'alloc'. Freeing an invalid pointer is implementation defined, however the ideal behaviour is for a StoreException to be thrown.

Parameters:

pointer - a 64-bit pointer to the memory to free.

Throws:

IOException

getFixedArea

Area getFixedArea()
                  throws IOException

Returns an Area object that represents the 64 byte fixed area as can be changed by the 'getFixedArea' and 'setFixedArea' methods.

Throws:

IOException

getInputStream

InputStream getInputStream(long pointer)
                           throws IOException

Returns an InputStream for reading from the area of the store allocated via the 'alloc' method. Trying to read from an invalid pointer is implementation defined, however the ideal behaviour is for a StoreException to be thrown.

The returned stream does not perform buffering. For efficiency, it is a good idea to wrap the returned steam with a BufferedInputStream.

Parameters:

pointer - a 64-bit pointer to the memory to read.

Returns:

an InputStream for reading from the allocated resource.

Throws:

IOException

getOutputStream

OutputStream getOutputStream(long pointer)
                             throws IOException

Returns an OutputStream for writing to the area of the store allocated via the 'alloc' method. Trying to write to an invalid pointer is implementation defined, however the ideal behaviour is for a StoreException to be thrown. This also throws a StoreException if the backing store is read-only.

The returned stream does not perform buffering. For efficiency, it is a good idea to wrap the returned steam with a BufferedOutputStream.

Parameters:

pointer - a 64-bit pointer to the memory to write.

Returns:

an OutputStream for writing to the allocated resource.

Throws:

IOException

getArea

Area getArea(long pointer)
             throws IOException

Returns an Area object that can be used to manipulate an area allocated from the store. The returned Area performs buffering.

Parameters:

pointer - a 64-bit pointer to the area (allocated via 'alloc').

Returns:

an Area object for manipulating the area.

Throws:

IOException

flush

void flush()
           throws IOException

Flushes any changes to the underlying storage device if the store implements memory mapping or buffering.

Throws:

IOException

synch

void synch()
           throws IOException

Flushes and synchronizes any changes made to the store with the underlying persistent device. This is only necessary for stores based on files. After an 'alloc', 'free' or write operation has occured, this method should be called if this level of robustness is necessary.

Throws:

IOException

lastCloseClean

boolean lastCloseClean()

Returns true if the store was closed cleanly. This is important information that may need to be considered when reading information from the store. This is typically used to issue a scan on the data in the store when it is not closed cleanly.

getAllAreas

List getAllAreas()
                 throws IOException

Returns a complete list of pointers to all areas in the Store as Long objects sorted from lowest pointer to highest. This should be used for diagnostics only because it may be difficult for this to be generated with some implementations. It is useful in a repair tool to determine if a pointer is valid or not.

Throws:

IOException