Package com.mckoi.database

## Class IndexStore

- java.lang.Object
- - com.mckoi.database.IndexStore

    public final class IndexStore
    extends java.lang.Object

A class that manages the storage of a set of transactional index lists in a way that is fast to modify. This class has a number of objectives;

- To prevent corruption as best as possible.
- To be able to modify lists of integers very fast and persistantly.
- To have size optimization features such as defragmentation.
- To provide very fast searches on sorted lists (caching features).
- To be able to map a list to an IntegerListInterface interface.

None intuitively, this object also handles unique ids.

Author:
  Tobias Downer

### Constructor Summary

Constructors
`IndexStore​(java.io.File file_name, DebugLogger logger)` Constructs the IndexStore.

### Method Summary

All Methods Instance Methods Concrete Methods
`void` `addIndexLists​(int count, byte type)` Adds a number of blank index tables to the index store.
`void` `close()` Cleanly closes the index store.
`void` `commitIndexSet​(IndexSet index_set)` Commits changes made to a snapshop of an IndexSet as being permanent changes to the state of the index store.
`void` `copyTo​(java.io.File path)` Copies the persistant part of this to another store.
`void` `create​(int block_size)` Creates a new black index store and returns leaving the newly created store in an open state.
`void` `delete()` Deletes the store.
`boolean` `exists()` Returns true if the index store file exists.
`boolean` `fix​(UserTerminal terminal)` Performs checks to determine that the index store is stable.
`void` `flush()` Flushes all information in this index store to the file representing this store in the file system.
`IndexSet` `getSnapshotIndexSet()` Returns a current snapshot of the current indexes that are committed in this store.
`void` `hardSynch()` Performs a hard synchronization of this index store.
`void` `init()` Initializes the IndexStore.
`boolean` `isReadOnly()` Returns true if this store is read only.
`boolean` `open​(boolean read_only)` Opens this index store.
`java.lang.String` `statusString()` Returns a string that contains diagnostic information.

### Methods inherited from class java.lang.Object

`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

### Constructor Detail

#### IndexStore

    public IndexStore​(java.io.File file_name,
                      DebugLogger logger)

Constructs the IndexStore.

Parameters:
  `file_name` - the path to the file of the index store in the file system.

### Method Detail

#### exists

    public boolean exists()
                   throws java.io.IOException

Returns true if the index store file exists.

Throws:
  `java.io.IOException`

#### create

    public void create​(int block_size)
                throws java.io.IOException

Creates a new black index store and returns leaving the newly created store in an open state. This method initializes the various data in the index store for a blank set of index tables. Must call the 'init' method after this is called.

Parameters:
  `block_size` - the number of ints stored in each block. This can be optimized for specific use. Must be between 0 and 32768.
Throws:
  `java.io.IOException`

#### open

    public boolean open​(boolean read_only)
                 throws java.io.IOException

Opens this index store. If 'read_only' is set to true then the store is opened in read only mode.

Returns true if opening the store was dirty (was not closed properly) and may need repair.

If the index store does not exist before this method is called then it is created.

Throws:
  `java.io.IOException`

#### init

    public void init()
              throws java.io.IOException

Initializes the IndexStore. Must be called after it is opened for normal use, however it should not be called if we are fixing or repairing the store.

Throws:
  `java.io.IOException`

#### fix

    public boolean fix​(UserTerminal terminal)
                throws java.io.IOException

Performs checks to determine that the index store is stable. If an IndexStore is not stable and can not be fixed cleanly then it deletes all information in the store and returns false indicating the index information must be rebuilt.

Assumes the index store has been opened previous to calling this.

Returns true if the IndexStore is stable.

Throws:
  `java.io.IOException`

#### isReadOnly

    public boolean isReadOnly()

Returns true if this store is read only.

#### delete

    public void delete()

Deletes the store. Must have been closed before this is called.

#### copyTo

    public void copyTo​(java.io.File path)
                throws java.io.IOException

Copies the persistant part of this to another store. Must be open when this is called.

Throws:
  `java.io.IOException`

#### close

    public void close()
               throws java.io.IOException

Cleanly closes the index store.

Throws:
  `java.io.IOException`

#### flush

    public void flush()
               throws java.io.IOException

Flushes all information in this index store to the file representing this store in the file system. This is called to persistantly update the state of the index store.

Throws:
  `java.io.IOException`

#### hardSynch

    public void hardSynch()
                   throws java.io.IOException

Performs a hard synchronization of this index store. This will force the OS to synchronize the contents of the data store.

For this to be useful, 'flush' should be called before a hardSynch.

Throws:
  `java.io.IOException`

#### addIndexLists

    public void addIndexLists​(int count,
                              byte type)

Adds a number of blank index tables to the index store. For example, we may want this store to contain 16 index lists.

NOTE: This doesn't write the updated information to the file. You must call 'flush' to write the information to the store.

#### getSnapshotIndexSet

    public IndexSet getSnapshotIndexSet()

Returns a current snapshot of the current indexes that are committed in this store. The returned object can be used to create mutable IntegerListInterface objects. The created index lists are isolated from changes made to the rest of the indexes after this method returns.

A transaction must grab an IndexSet object when it opens.

NOTE: We MUST guarentee that the IndexSet is disposed when the transaction finishes.

#### commitIndexSet

    public void commitIndexSet​(IndexSet index_set)

Commits changes made to a snapshop of an IndexSet as being permanent changes to the state of the index store. This will generate an error if the given IndexSet is not the last set returned from the 'getSnapshotIndexSet' method.

For this to be used, during the transaction commit function a 'getSnapshopIndexSet' must be obtained, changes made to it from info in the journal, then a call to this method. There must be a guarentee that 'getSnapshotIndexSet' is not called again during this process.

NOTE: This doesn't write the updated information to the file. You must call 'flush' to write the information to the store.

NOTE: We must be guarenteed that when this method is called no other calls to other methods in this object can be called.

#### statusString

    public java.lang.String statusString()
                                  throws java.io.IOException

Returns a string that contains diagnostic information.

Throws:
  `java.io.IOException`