IBigArray (bigqueue 1.0.0 API)

All Superinterfaces:

AutoCloseable, Closeable

All Known Implementing Classes:

BigArrayImpl
```
public interface IBigArray
extends Closeable
```
Append Only Big Array ADT

Author:

bulldog

Field Summary

Fields
Modifier and Type Field and Description

static long NOT_FOUND

Fields
Modifier and Type	Field and Description
`static long`	`NOT_FOUND`

Method Summary

All Methods Instance Methods Abstract Methods
Modifier and Type	Method and Description
`long`	`append(byte[] data)` Append the data into the head of the array
`long`	`findClosestIndex(long timestamp)` Find an index closest to the specific timestamp when the corresponding item was appended
`void`	`flush()` Force to persist newly appended data, normally, you don't need to flush explicitly since: 1.) BigArray will automatically flush a cached page when it is replaced out, 2.) BigArray uses memory mapped file technology internally, and the OS will flush the changes even your process crashes, call this periodically only if you need transactional reliability and you are aware of the cost to performance.
`byte[]`	`get(long index)` Get the data at specific index
`long`	`getBackFileSize()` Get total size of back files(index and data files) of the big array
`int`	`getDataPageSize()` Get the back data file size per page.
`long`	`getHeadIndex()` The head of the array.
`int`	`getItemLength(long index)` Get the data item length at specific index
`long`	`getTailIndex()` The tail of the array.
`long`	`getTimestamp(long index)` Get the timestamp of data at specific index, this is the timestamp when the data was appended.
`boolean`	`isEmpty()` Check if the array is empty or not
`boolean`	`isFull()` Check if the ring space of java long type has all been used up.
`void`	`limitBackFileSize(long sizeLimit)` limit the back file size, truncate back file and advance array tail index accordingly, Note, this is a best effort call, exact size limit can't be guaranteed
`void`	`removeAll()` Remove all data in this array, this will empty the array and delete all back page files.
`void`	`removeBefore(long timestamp)` Remove all data before specific timestamp, this will advance the array tail and delete back page files accordingly.
`void`	`removeBeforeIndex(long index)` Remove all data before specific index, this will advance the array tail to index and delete back page files before index.
`long`	`size()` The total number of items has been appended into the array

Methods inherited from interface java.io.Closeable
close

- Field Detail
  - NOT_FOUND
```
static final long NOT_FOUND
```
    See Also:
    
    Constant Field Values
- Method Detail
  - append
```
long append(byte[] data)
     throws IOException
```
    Append the data into the head of the array
    
    Parameters:
    
    data - binary data to append
    
    Returns:
    
    appended index
    
    Throws:
    
    IOException - if there is any IO error
  - get
```
byte[] get(long index)
    throws IOException
```
    Get the data at specific index
    
    Parameters:
    
    index - valid data index
    
    Returns:
    
    binary data if the index is valid
    
    Throws:
    
    IOException - if there is any IO error
  - getTimestamp
```
long getTimestamp(long index)
           throws IOException
```
    Get the timestamp of data at specific index, this is the timestamp when the data was appended.
    
    Parameters:
    
    index - valid data index
    
    Returns:
    
    timestamp when the data was appended
    
    Throws:
    
    IOException - if there is any IO error
  - size
```
long size()
```
    The total number of items has been appended into the array
    
    Returns:
    
    total number
  - getDataPageSize
```
int getDataPageSize()
```
    Get the back data file size per page.
    
    Returns:
    
    size per page
  - getHeadIndex
```
long getHeadIndex()
```
    The head of the array. This is the next to append index, the index of the last appended data is [headIndex - 1] if the array is not empty.
    
    Returns:
    
    an index
  - getTailIndex
```
long getTailIndex()
```
    The tail of the array. The is the index of the first appended data
    
    Returns:
    
    an index
  - isEmpty
```
boolean isEmpty()
```
    Check if the array is empty or not
    
    Returns:
    
    true if empty false otherwise
  - isFull
```
boolean isFull()
```
    Check if the ring space of java long type has all been used up. can always assume false, if true, the world is end:)
    
    Returns:
    
    array full or not
  - removeAll
```
void removeAll()
        throws IOException
```
    Remove all data in this array, this will empty the array and delete all back page files.
    
    Throws:
    
    IOException - exception thrown if IO error occurs durring remove all
  - removeBeforeIndex
```
void removeBeforeIndex(long index)
                throws IOException
```
    Remove all data before specific index, this will advance the array tail to index and delete back page files before index.
    
    Parameters:
    
    index - an index
    
    Throws:
    
    IOException - exception thrown if there was any IO error during the removal operation
  - removeBefore
```
void removeBefore(long timestamp)
           throws IOException
```
    Remove all data before specific timestamp, this will advance the array tail and delete back page files accordingly.
    
    Parameters:
    
    timestamp - a timestamp
    
    Throws:
    
    IOException - exception thrown if there was any IO error during the removal operation
  - flush
```
void flush()
```
    Force to persist newly appended data, normally, you don't need to flush explicitly since: 1.) BigArray will automatically flush a cached page when it is replaced out, 2.) BigArray uses memory mapped file technology internally, and the OS will flush the changes even your process crashes, call this periodically only if you need transactional reliability and you are aware of the cost to performance.
  - findClosestIndex
```
long findClosestIndex(long timestamp)
               throws IOException
```
    Find an index closest to the specific timestamp when the corresponding item was appended
    
    Parameters:
    
    timestamp - when the corresponding item was appended
    
    Returns:
    
    an index
    
    Throws:
    
    IOException - exception thrown if there was any IO error during the getClosestIndex operation
  - getBackFileSize
```
long getBackFileSize()
              throws IOException
```
    Get total size of back files(index and data files) of the big array
    
    Returns:
    
    total size of back files
    
    Throws:
    
    IOException - exception thrown if there was any IO error during the getBackFileSize operation
  - limitBackFileSize
```
void limitBackFileSize(long sizeLimit)
                throws IOException
```
    limit the back file size, truncate back file and advance array tail index accordingly, Note, this is a best effort call, exact size limit can't be guaranteed
    
    Parameters:
    
    sizeLimit - the size to limit
    
    Throws:
    
    IOException - exception thrown if there was any IO error during the limitBackFileSize operation
  - getItemLength
```
int getItemLength(long index)
           throws IOException
```
    Get the data item length at specific index
    
    Parameters:
    
    index - valid data index
    
    Returns:
    
    the length of binary data if the index is valid
    
    Throws:
    
    IOException - if there is any IO error

Interface IBigArray

Field Summary

Method Summary

Methods inherited from interface java.io.Closeable

Field Detail

NOT_FOUND

Method Detail

append

get

getTimestamp

size

getDataPageSize

getHeadIndex

getTailIndex

isEmpty

isFull

removeAll

removeBeforeIndex

removeBefore

flush

findClosestIndex

getBackFileSize

limitBackFileSize

getItemLength