org.magnos.data.store
Class AbstractStore

java.lang.Object
  org.magnos.data.store.AbstractStore

All Implemented Interfaces:

Store

Direct Known Subclasses:

FileStore, MappedStore, MemoryStore

public abstract class AbstractStore
extends java.lang.Object
implements Store

An abstract Store. Implementations must adhere to the guidelines specified in the documentation of the abstract methods.

Author:

Philip Diffenderfer

Constructor Summary

protected

AbstractStore(java.lang.String name) Instantiates a new AbstractStore.

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	equals(java.lang.Object o)
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.
int	hashCode()
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.
protected abstract void	storeClose() Should close the store.
protected abstract void	storeDelete() Deletes the medium to which the store has been persisting to.
protected abstract boolean	storeExists() Returns whether the store exists in its probable medium.
protected abstract void	storeFlush() Should flush the contents of the store from memory to a persisted medium if the implementation supports it.
protected abstract void	storeGet(int location, byte[] bytes, int offset, int length) Gets data at the given location and stores it in the given byte array.
protected abstract void	storeGet(int location, java.nio.ByteBuffer buffer) Gets data at the given location and stores it in the given ByteBuffer.
protected abstract void	storeLoad() Should load contents of the store into memory from a persisted medium if the implementation supports it.
protected abstract int	storeOpen(StoreAccess access) Should open the store and return the capacity.
protected abstract void	storePut(int location, byte[] bytes, int offset, int length) Puts data at the given location from the given byte array.
protected abstract void	storePut(int location, java.nio.ByteBuffer buffer) Puts data at the given location from the given ByteBuffer.
protected abstract int	storeResize(int capacity) Resizes the store to the given capacity.
java.lang.String	toString()
protected void	validate() Validates an action by checking if the store is closed.

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

AbstractStore

protected AbstractStore(java.lang.String name)

Instantiates a new AbstractStore.

Parameters:

name - The unique name of this store. If this store is persisted to a file system this may be the file name.

Method Detail

storeOpen

protected abstract int storeOpen(StoreAccess access)
                          throws java.io.IOException

Should open the store and return the capacity. If the requested access could not be granted an exception should be thrown. This will only be invoked if the store has been closed previously or has not been opened yet. If the store doesn't exist this should forcefully create it before opening it with the requested access.

Returns:

The capacity of the store.

Throws:

java.io.IOException - An error occurred opening the store with the given access.

storeLoad

protected abstract void storeLoad()
                           throws java.io.IOException

Should load contents of the store into memory from a persisted medium if the implementation supports it.

Throws:

java.io.IOException - An error occurred loading the store.

storeFlush

protected abstract void storeFlush()
                            throws java.io.IOException

Should flush the contents of the store from memory to a persisted medium if the implementation supports it.

Throws:

java.io.IOException - An error occurred flushing the store.

storeClose

protected abstract void storeClose()
                            throws java.io.IOException

Should close the store. This will only be invoked if the store has been successfully opened previously. If there is an error closing the store an exception should be thrown. This exception however may be ignored due to the likeliness that the store is still closed even after an exception is thrown.

Throws:

java.io.IOException - An error occurred closing the store.

storeResize

protected abstract int storeResize(int capacity)
                            throws java.io.IOException

Resizes the store to the given capacity. If the store could not be resized to the requested capacity an exception should be thrown. This will only be called if the store was successfully opened previously. If the resize results in a larger store the end of the store should be padded with zeros (which the system will implicitly due most likely).

Parameters:

capacity - The new capacity of the store.

Throws:

java.io.IOException - An error occured resizing the store.

storeExists

protected abstract boolean storeExists()

Returns whether the store exists in its probable medium. This could be called before or after the store has been opened or created.

Returns:

True if the store already exists.

storeDelete

protected abstract void storeDelete()

Deletes the medium to which the store has been persisting to.

storeGet

protected abstract void storeGet(int location,
                                 byte[] bytes,
                                 int offset,
                                 int length)
                          throws java.io.IOException

Gets data at the given location and stores it in the given byte array.

Parameters:

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

bytes - The array of bytes to place the data in.

offset - The offset in the byte array to place the data.

length - The number of bytes to copy from the store and place in the array.

Throws:

java.io.IOException - An error occurred reading from the store.

storeGet

protected abstract void storeGet(int location,
                                 java.nio.ByteBuffer buffer)
                          throws java.io.IOException

Gets data at the given location and stores it in the given ByteBuffer.

Parameters:

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

buffer - The buffer to place the data in. The buffer will be filled with data to its limit (so it has no remaining bytes).

Throws:

java.io.IOException - An error occurred reading from the store.

storePut

protected abstract void storePut(int location,
                                 byte[] bytes,
                                 int offset,
                                 int length)
                          throws java.io.IOException

Puts data at the given location from the given byte array.

Parameters:

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

bytes - The array of bytes to take data from.

offset - The offset in the byte array to take the data.

length - The number of bytes to copy from the array and place in the store.

Throws:

java.io.IOException - An error occurred writing to the store.

storePut

protected abstract void storePut(int location,
                                 java.nio.ByteBuffer buffer)
                          throws java.io.IOException

Puts data at the given location from the given ByteBuffer.

Parameters:

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

buffer - The buffer to take the data from. The buffer will be emptied of data to its limit (so it has no remaining bytes).

Throws:

java.io.IOException - An error occurred writing to the store.

validate

protected final void validate()
                       throws StoreClosedException

Validates an action by checking if the store is closed. If the store is closed and the store could not be automatically opened this will throw a StoreClosedException.

Throws:

StoreClosedException

getName

public final 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.

Specified by:

getName in interface Store

Returns:

The unique name of this store.

capacity

public final int capacity()

Returns the size or capacity of the store in bytes.

Specified by:

capacity in interface Store

Returns:

The store's size in bytes.

getAccess

public final 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.

Specified by:

getAccess in interface Store

Returns:

The current access to the persisted medium.

setAccess

public final 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.

Specified by:

setAccess in interface Store

Parameters:

newAccess - The requested access to the store.

Returns:

The granted access on the store.

exists

public final 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.

Specified by:

exists in interface Store

Returns:

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

delete

public final void delete()

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

Specified by:

delete in interface Store

capacity

public final int capacity(int newCapacity)

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.

Specified by:

capacity in interface Store

Parameters:

newCapacity - The desired capacity of the store.

Returns:

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

create

public final StoreAccess create(StoreAccess initialAccess,
                                int initialCapacity)
                         throws StoreIOException

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.

Specified by:

create in interface Store

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.

open

public final 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.

Specified by:

open in interface Store

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

public final void load()
                throws StoreIOException

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.

Specified by:

load in interface Store

Throws:

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

flush

public final void flush()
                 throws StoreIOException

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.

Specified by:

flush in interface Store

Throws:

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

close

public final 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.

Specified by:

close in interface Store

Throws:

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

isClosed

public final 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.

Specified by:

isClosed in interface Store

Returns:

True if the store is closed, otherwise false.

isOpen

public final boolean isOpen()

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

Specified by:

isOpen in interface Store

Returns:

True if the store is open, otherwise false.

get

public final 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.

Specified by:

get in interface Store

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.

get

public final void get(int location,
                      java.nio.ByteBuffer buffer)

Reads a ByteBuffer to the store at the given location.

Specified by:

get in interface Store

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.

get

public final void get(int location,
                      byte[] bytes)

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

Specified by:

get in interface Store

Parameters:

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

bytes - The array of bytes to read into.

get

public final byte[] get(int location,
                        int size)

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

Specified by:

get in interface Store

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.

put

public final 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.

Specified by:

put in interface Store

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.

put

public final void put(int location,
                      java.nio.ByteBuffer buffer)

Writes a ByteBuffer to the store at the given location.

Specified by:

put in interface Store

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.

put

public final void put(int location,
                      byte[] bytes)

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

Specified by:

put in interface Store

Parameters:

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

bytes - The array of bytes to write.

isAutoOpen

public final 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.

Specified by:

isAutoOpen in interface Store

Returns:

True if the store can automatically open, otherwise false.

setAutoOpen

public final 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.

Specified by:

setAutoOpen in interface Store

Parameters:

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

isAutoFlush

public final boolean isAutoFlush()

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

Specified by:

isAutoFlush in interface Store

Returns:

True if the store should automatically flush, otherwise false.

setAutoFlush

public final void setAutoFlush(boolean autoFlush)

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

Specified by:

setAutoFlush in interface Store

Parameters:

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

isAutoLoad

public final boolean isAutoLoad()

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

Specified by:

isAutoLoad in interface Store

Returns:

True if the store should automatically load, otherwise false.

setAutoLoad

public final void setAutoLoad(boolean autoLoad)

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

Specified by:

setAutoLoad in interface Store

Parameters:

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

hashCode

public final int hashCode()

Overrides:

hashCode in class java.lang.Object

equals

public final boolean equals(java.lang.Object o)

Overrides:

equals in class java.lang.Object

toString

public final java.lang.String toString()

Overrides:

toString in class java.lang.Object