Class HeapStore

java.lang.Object
com.mckoi.store.HeapStore
All Implemented Interfaces:
Store

public final class HeapStore extends Object implements Store
An implementation of the Store interface that persists information in the volatile JVM heap memory. Each Area in the store is represented by a byte[] array from the Java heap.

Note that in Java there is no way to cast a reference to a numeric value, or to cast a numeric value back into a reference. This means that Area lookup has to be coordinated via a hashing algorithm over an array. There would prehaps be a more efficient way to achieve this with JNI but it would mean we can't be pure Java and it would require locking the address of objects in the heap.

Another alternative way of implementing this class would be to use JNI to access a C style 'malloc' function in the operating system and wrap the memory with a native Area implementation.

Author:
Tobias Downer
  • Constructor Summary

    Constructors
    Constructor
    Description
    Defaults heap size to 257 elements.
    HeapStore(int hash_size)
    Creates the HeapStore.
  • Method Summary

    Modifier and Type
    Method
    Description
    createArea(long size)
    Allocates a block of memory in the store of the specified size and returns an AreaWriter object that can be used to initialize the contents of the area.
    void
    deleteArea(long pointer)
    Deletes an area that was previously allocated by the 'createArea' method by the area id.
    void
     
    Returns a complete list of pointers to all areas in the Store as Long objects sorted from lowest pointer to highest.
    getArea(long pointer)
    Returns an object that allows for the contents of an area (represented by the 'id' parameter) to be read.
    getAreaInputStream(long pointer)
    Returns an InputStream implementation that allows for the area with the given identifier to be read sequentially.
    getMutableArea(long pointer)
    Returns an object that allows for the contents of an area (represented by the 'id' parameter) to be read and written.
    boolean
    Returns true if the store was closed cleanly.
    void
    It is often useful to guarentee that a certain sequence of updates to a store is completed and not broken in the middle.
    void
     
    void
    See the 'lockForWrite' method description.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
  • Constructor Details

    • HeapStore

      public HeapStore(int hash_size)
      Creates the HeapStore.
    • HeapStore

      public HeapStore()
      Defaults heap size to 257 elements.
  • Method Details

    • createArea

      public AreaWriter createArea(long size) throws IOException
      Description copied from interface: Store
      Allocates a block of memory in the store of the specified size and returns an AreaWriter object that can be used to initialize the contents of the area. Note that an area in the store is undefined until the 'finish' method is called in AreaWriter.
      Specified by:
      createArea in interface Store
      Parameters:
      size - the amount of memory to allocate.
      Returns:
      an AreaWriter object that allows the area to be setup.
      Throws:
      IOException - if not enough space available to create the area or the store is read-only.
    • deleteArea

      public void deleteArea(long pointer) throws IOException
      Description copied from interface: Store
      Deletes an area that was previously allocated by the 'createArea' method by the area id. Once an area is deleted the resources may be reclaimed. The behaviour of this method is undefined if the id doesn't represent a valid area.
      Specified by:
      deleteArea in interface Store
      Parameters:
      pointer - the identifier of the area to delete.
      Throws:
      IOException - (optional) if the id is invalid or the area can not otherwise by deleted.
    • getAreaInputStream

      public InputStream getAreaInputStream(long pointer) throws IOException
      Description copied from interface: Store
      Returns an InputStream implementation that allows for the area with the given identifier to be read sequentially. The behaviour of this method, and InputStream object, is undefined if the id doesn't represent a valid area.

      When 'id' is -1 then a fixed area (64 bytes in size) in the store is returned. The fixed area can be used to store important static static information.

      Specified by:
      getAreaInputStream in interface Store
      Parameters:
      pointer - the identifier of the area to read, or id = -1 is a 64 byte fixed area in the store.
      Returns:
      an InputStream that allows the area to be read from the start.
      Throws:
      IOException - (optional) if the id is invalid or the area can not otherwise be accessed.
    • getArea

      public Area getArea(long pointer) throws IOException
      Description copied from interface: Store
      Returns an object that allows for the contents of an area (represented by the 'id' parameter) to be read. The behaviour of this method, and Area object, is undefined if the id doesn't represent a valid area.

      When 'id' is -1 then a fixed area (64 bytes in size) in the store is returned. The fixed area can be used to store important static static information.

      Specified by:
      getArea in interface Store
      Parameters:
      pointer - the identifier of the area to read, or id = -1 is a 64 byte fixed area in the store.
      Returns:
      an Area object that allows access to the part of the store.
      Throws:
      IOException - (optional) if the id is invalid or the area can not otherwise be accessed.
    • getMutableArea

      public MutableArea getMutableArea(long pointer) throws IOException
      Description copied from interface: Store
      Returns an object that allows for the contents of an area (represented by the 'id' parameter) to be read and written. The behaviour of this method, and MutableArea object, is undefined if the id doesn't represent a valid area.

      When 'id' is -1 then a fixed area (64 bytes in size) in the store is returned. The fixed area can be used to store important static static information.

      Specified by:
      getMutableArea in interface Store
      Parameters:
      pointer - the identifier of the area to access, or id = -1 is a 64 byte fixed area in the store.
      Returns:
      a MutableArea object that allows access to the part of the store.
      Throws:
      IOException - (optional) if the id is invalid or the area can not otherwise be accessed.
    • flush

      public void flush() throws IOException
      Throws:
      IOException
    • synch

      public void synch() throws IOException
      Throws:
      IOException
    • lockForWrite

      public void lockForWrite()
      Description copied from interface: Store
      It is often useful to guarentee that a certain sequence of updates to a store is completed and not broken in the middle. For example, when inserting data into a table you don't want a record to be partially written when a check point is made. You want the entire sequence of modifications to be completed before the check point can run. This means that if a crash occurs, a check point will not recover to a possible corrupt file.

      To achieve this, the 'lockForWrite' and 'unlockForWrite' methods are available. When 'lockForWrite' has been called, a check point can not created until there are no write locks obtained on the table.

      Specified by:
      lockForWrite in interface Store
    • unlockForWrite

      public void unlockForWrite()
      Description copied from interface: Store
      See the 'lockForWrite' method description.
      Specified by:
      unlockForWrite in interface Store
    • lastCloseClean

      public boolean lastCloseClean()
      Description copied from interface: Store
      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.
      Specified by:
      lastCloseClean in interface Store
    • getAllAreas

      public List getAllAreas() throws IOException
      Description copied from interface: Store
      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.
      Specified by:
      getAllAreas in interface Store
      Throws:
      IOException