org.magnos.data
Interface Store

All Known Implementing Classes:

AbstractStore, FileStore, MappedStore, MemoryStore

public interface Store

A place to store data as bytes and ByteBuffers. Stores can represent data thats persisted in memory, on disk, or persisted to RAM and sync'd to the file system (mapped). Granting access to opening and creating stores is implementation dependent.

Author:

Philip Diffenderfer

See Also:

FileStore, MappedStore, MemoryStore

Method Summary

int	capacity() Returns the size or capacity of the store in bytes.
int	capacity(int newCapacity) Sets the stores size or capacity in bytes.
void	close() Closes this store if not closed already.
StoreAccess	create(StoreAccess initialAccess, int initialCapacity) Creates the store by opening it with the given access and setting the initial capacity.
void	delete() Removes this store from any persisted medium.
boolean	exists() Whether the store exists.
void	flush() Explicitly writes the data to the store.
void	get(int location, byte[] bytes) Reads an array of bytes from the store at the given location.
void	get(int location, byte[] bytes, int offset, int length) Reads from the store and puts it in a section in the array of bytes.
void	get(int location, java.nio.ByteBuffer buffer) Reads a ByteBuffer to the store at the given location.
byte[]	get(int location, int size) Returns an array of bytes read from the store at the given location.
StoreAccess	getAccess() Returns the current access of this store to its persisted medium if any exists.
java.lang.String	getName() Returns the name of the store.
boolean	isAutoFlush() Whether the store automatically flushes data immediately after its written to the store.
boolean	isAutoLoad() Whether the store automatically loads data immediately before its read from the store.
boolean	isAutoOpen() Whether the store automatically opens with the default or last access if some action needs to be done to the store.
boolean	isClosed() Whether the store is closed.
boolean	isOpen() Whether the store is open.
void	load() Explicitly loads the data from the store into memory.
StoreAccess	open(StoreAccess initialAccess) Explicitly opens this store for reading and writing.
void	put(int location, byte[] bytes) Writes the array of bytes to the store at the given location.
void	put(int location, byte[] bytes, int offset, int length) Writes a section in the array of bytes to the store at the given location.
void	put(int location, java.nio.ByteBuffer buffer) Writes a ByteBuffer to the store at the given location.
StoreAccess	setAccess(StoreAccess newAccess) Sets the access of this store to its persisted medium.
void	setAutoFlush(boolean autoFlush) Sets whether the store automatically flushes data immediately after its written to the store.
void	setAutoLoad(boolean autoLoad) Set whether the store automatically loads data immediately before its read from the store.
void	setAutoOpen(boolean autoOpen) Sets whether the store automatically opens with the default or last access if some actions need to be done to the store.

Method Detail

getName

java.lang.String getName()

Returns the name of the store. This should be unique amongst stores to avoid concurrent access to the same data source. This may represent a file name if the store implementation persists its data to some medium.

Returns:

The unique name of this store.

create

StoreAccess create(StoreAccess initialAccess,
                   int initialCapacity)
                   throws StoreIOException,
                          StoreAccessException

Creates the store by opening it with the given access and setting the initial capacity. If the store already exists it will not modify any pre-existing data but simply change the capacity and access if possible. If the requested access cannot be granted the next best access will be granted. If no access could be granted null will be returned.

Parameters:

initialAccess - The requested access to the store.

initialCapacity - The new capacity of the store.

Returns:

The access that has been granted on the store, or null if no access could be granted to the store.

Throws:

StoreIOException - An error occurred in the implementation. See attached exception.

StoreAccessException - The store does not have sufficient access to perform the operation.

open

StoreAccess open(StoreAccess initialAccess)
                 throws StoreIOException

Explicitly opens this store for reading and writing. If this store has auto open set true then this is called when the user tries doing their first read or write since the stores creation or a recent close. If the requested access cannot be granted the next best access will be granted. If no access could be granted null will be returned.

Parameters:

initialAccess - The requested access to the store.

Returns:

The access that has been granted on the store, or null if no access could be granted to the store.

Throws:

StoreIOException - An error occurred in the implementation. See attached exception.

load

void load()
          throws StoreIOException,
                 StoreClosedException

Explicitly loads the data from the store into memory. This is mainly used for memory mapped files that may be modified by different threads and the current threads wants to see current data. If this store has auto load set true then this is called when the store is open, however it will not be called before every read.

Throws:

StoreIOException - An error occurred in the implementation. See attached exception.

StoreClosedException - The store is closed. If auto open is set to true this still may be thrown if there was an error opening the store.

flush

void flush()
           throws StoreIOException,
                  StoreClosedException

Explicitly writes the data to the store. This is mainly used for memory mapped files that occasionally can have unwritten sections. If this store has auto write set trye then this is called whenever data is written to the store.

Throws:

StoreIOException - An error occurred in the implementation. See attached exception.

StoreClosedException - The store is closed. If auto open is set to true this still may be thrown if there was an error opening the store.

close

void close()
           throws StoreIOException

Closes this store if not closed already. A closed store will throw exceptions when data is trying to be read from and written to.

Throws:

StoreIOException - An error occurred in the implementation. See attached exception.

delete

void delete()
            throws StoreIOException,
                   StoreAccessException

Removes this store from any persisted medium. If open, this store will be automatically closed before anything is removed.

Throws:

StoreIOException - An error occurred in the implementation. See attached exception.

StoreAccessException - The store does not have sufficient access to perform the operation.

exists

boolean exists()

Whether the store exists. If this store is based in memory it will always exist. If this store is persisted to some medium it will returned whether that medium exists (i.e. a file in the filesystem). This is independent on whether the store is open or closed.

Returns:

True if the store exists in some medium, otherwise false.

capacity

int capacity()

Returns the size or capacity of the store in bytes.

Returns:

The store's size in bytes.

capacity

int capacity(int newCapacity)
             throws StoreIOException,
                    StoreClosedException,
                    StoreAccessException

Sets the stores size or capacity in bytes. If the given capacity is less than the current capacity the difference will be removed from the end of this store losing the last bytes. If the given capacity is greater than the current capacity than this will have no affect on the data currently in the store.

Parameters:

newCapacity - The desired capacity of the store.

Returns:

The capacity of this store at the end of the method invokation.

Throws:

StoreIOException - An error occurred in the implementation. See attached exception.

StoreClosedException - The store is closed. If auto open is set to true this still may be thrown if there was an error opening the store.

StoreAccessException - The store does not have sufficient access to perform the operation.

getAccess

StoreAccess getAccess()

Returns the current access of this store to its persisted medium if any exists. The default access if the store is opened implicitly is ReadWrite access. The current access may have less access then the requested access sent to create or open if the requested access could not be granted.

Returns:

The current access to the persisted medium.

setAccess

StoreAccess setAccess(StoreAccess newAccess)

Sets the access of this store to its persisted medium. If this store is closed the access will be changed without affecting it. If the store is open it will be closed and reopened with the new access, or an access which is grantable if the given access cannot be granted.

Parameters:

newAccess - The requested access to the store.

Returns:

The granted access on the store.

isClosed

boolean isClosed()

Whether the store is closed. A store is closed by default. Once opened a store can be closed if its invoked explicitly, or if the store has been deleted.

Returns:

True if the store is closed, otherwise false.

isOpen

boolean isOpen()

Whether the store is open. A store is closed by default. It can only be opened by explicitly calling open or create.

Returns:

True if the store is open, otherwise false.

isAutoOpen

boolean isAutoOpen()

Whether the store automatically opens with the default or last access if some action needs to be done to the store. This is true by default.

Returns:

True if the store can automatically open, otherwise false.

setAutoOpen

void setAutoOpen(boolean autoOpen)

Sets whether the store automatically opens with the default or last access if some actions need to be done to the store. This is true by default.

Parameters:

autoOpen - True if the store should automatically open, otherwise false.

isAutoFlush

boolean isAutoFlush()

Whether the store automatically flushes data immediately after its written to the store. This is false by defaut.

Returns:

True if the store should automatically flush, otherwise false.

setAutoFlush

void setAutoFlush(boolean autoFlush)

Sets whether the store automatically flushes data immediately after its written to the store. This is false by default.

Parameters:

autoFlush - True if the store should automatically flush, otherwise false.

isAutoLoad

boolean isAutoLoad()

Whether the store automatically loads data immediately before its read from the store. This is false by defaut.

Returns:

True if the store should automatically load, otherwise false.

setAutoLoad

void setAutoLoad(boolean autoLoad)

Set whether the store automatically loads data immediately before its read from the store. This is false by defaut.

Parameters:

autoLoad - True if the store should automatically load, otherwise false.

put

void put(int location,
         byte[] bytes)
         throws StoreIOException,
                StoreClosedException,
                StoreAccessException

Writes the array of bytes to the store at the given location.

Parameters:

location - The location in the store, the offset of bytes from the beginning.

bytes - The array of bytes to write.

Throws:

StoreIOException - An error occurred in the implementation. See attached exception.

StoreClosedException - The store is closed. If auto open is set to true this still may be thrown if there was an error opening the store.

StoreAccessException - The store does not have sufficient access to perform the operation.

put

void put(int location,
         byte[] bytes,
         int offset,
         int length)
         throws StoreIOException,
                StoreClosedException,
                StoreAccessException

Writes a section in the array of bytes to the store at the given location.

Parameters:

location - The location in the store, the offset of bytes from the beginning.

bytes - The array of bytes to write.

offset - The offset into the array of bytes.

length - The number of bytes to write starting at the offset in the array.

Throws:

StoreIOException - An error occurred in the implementation. See attached exception.

StoreClosedException - The store is closed. If auto open is set to true this still may be thrown if there was an error opening the store.

StoreAccessException - The store does not have sufficient access to perform the operation.

put

void put(int location,
         java.nio.ByteBuffer buffer)
         throws StoreIOException,
                StoreClosedException,
                StoreAccessException

Writes a ByteBuffer to the store at the given location.

Parameters:

location - The location in the store, the offset of bytes from the beginning.

buffer - The buffer of data to write. The bytes written to the store are the bytes that exist between the buffers position and limit.

Throws:

StoreIOException - An error occurred in the implementation. See attached exception.

StoreClosedException - The store is closed. If auto open is set to true this still may be thrown if there was an error opening the store.

StoreAccessException - The store does not have sufficient access to perform the operation.

get

void get(int location,
         byte[] bytes)
         throws StoreIOException,
                StoreClosedException,
                StoreAccessException

Reads an array of bytes from the store at the given location.

Parameters:

location - The location in the store, the offset of bytes from the beginning.

bytes - The array of bytes to read into.

Throws:

StoreIOException - An error occurred in the implementation. See attached exception.

StoreClosedException - The store is closed. If auto open is set to true this still may be thrown if there was an error opening the store.

StoreAccessException - The store does not have sufficient access to perform the operation.

get

void get(int location,
         byte[] bytes,
         int offset,
         int length)
         throws StoreIOException,
                StoreClosedException,
                StoreAccessException

Reads from the store and puts it in a section in the array of bytes.

Parameters:

location - The location in the store, the offset of bytes from the beginning.

bytes - The array of bytes to read into.

offset - The offset into the array of bytes.

length - The number of bytes to read starting at the offset in the array.

Throws:

StoreIOException - An error occurred in the implementation. See attached exception.

StoreClosedException - The store is closed. If auto open is set to true this still may be thrown if there was an error opening the store.

StoreAccessException - The store does not have sufficient access to perform the operation.

get

void get(int location,
         java.nio.ByteBuffer buffer)
         throws StoreIOException,
                StoreClosedException,
                StoreAccessException

Reads a ByteBuffer to the store at the given location.

Parameters:

location - The location in the store, the offset of bytes from the beginning.

buffer - The buffer of data to write. The bytes written to the store are the bytes that exist between the buffers position and limit.

Throws:

StoreIOException - An error occurred in the implementation. See attached exception.

StoreClosedException - The store is closed. If auto open is set to true this still may be thrown if there was an error opening the store.

StoreAccessException - The store does not have sufficient access to perform the operation.

get

byte[] get(int location,
           int size)
           throws StoreIOException,
                  StoreClosedException,
                  StoreAccessException

Returns an array of bytes read from the store at the given location.

Parameters:

location - The location in the store, the offset of bytes from the beginning.

size - The number of bytes to read and return.

Returns:

An array of bytes with the given size.

Throws:

StoreIOException - An error occurred in the implementation. See attached exception.

StoreClosedException - The store is closed. If auto open is set to true this still may be thrown if there was an error opening the store.

StoreAccessException - The store does not have sufficient access to perform the operation.