com.faunos.skwish.sys
Class Index

java.lang.Object
  com.faunos.skwish.sys.Index

All Implemented Interfaces:

Closeable

Direct Known Subclasses:

MutableBaseIdIndex

public class Index
extends Object
implements Closeable

An index of offsets backed by a file. The implementation is based on the file format described in the package summary.

Note

The writeNextOffset family of functions here are poorly designed. It might make more sense to expand a family of pushNext member functions instead.

Author:

Babak Farhang

See Also:

IndexMetrics

Field Summary

protected static int	BASEID_WIDTH
protected static int	BASEOFFSET_WIDTH
protected static int	ENTRYCOUNT_WIDTH
static int	FIXED_HEADER_WIDTH The byte size of an index's fixed header.
protected static ChannelUtil<IndexException>	helper
protected FileChannel	indexFile The underlying persistent representation of the index.
protected static int	OFFSETWIDTH_WIDTH
protected static Validator<IndexException>	validator

Constructor Summary

	Index(FileChannel indexFile) Reads an index from the specified I/O channel.
	Index(FileChannel indexFile, boolean recover) Reads an index from the specified I/O channel.
protected	Index(FileChannel indexFile, Word offsetWidth, long baseId, long baseOffset) Writes a new index to the specified file.

Method Summary

void	close() Closes this index and its underlying file.
void	commit() Commits the entry count to the backing file.
long	delete(long id) Deletes the entry with the given ID.
long	delete(long startId, int count) Deletes count entries starting with the given startId.
void	flush() Flushes the underlying file stream.
long	getContentsSize() Returns the byte size of all the entry contents this index knows about.
long	getEntryCount() Returns the number of entries that are in the index.
long	getIndexSize() Returns the byte size of the index.
long	getLastOffset() Returns the last offset in the content file that this instance [implicitly] manages.
IndexMetrics	getMetrics() Returns the metrics of the index.
long	getNextId() Returns the ID that would be returned on inserting or killing the next entry.
boolean	isAutoCommit() Determines whether this instance is in auto-commit mode.
long	killNext() Kills the next entry.
long	killNext(int count) Kills the next count entry.
long	pushNext(long size) Pushes the next entry of the given size.
void	readOffsets(long id, ByteBuffer out) Reads and returns the offsets of the entry with the specified ID.
void	readOffsets(long startId, ByteBuffer out, int count) Reads and returns the offsets of count entries, starting at the specified startId.
void	readOffsets(long startId, ByteBuffer out, int count, ByteBuffer work)
void	setAutoCommit(boolean autoCommit) Sets the auto-commit property.
static Index	writeNewIndex(FileChannel indexFile, Word offsetWidth, long baseId, long baseOffset) Writes a new index to the specified file.

Methods inherited from class java.lang.Object

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

Field Detail

OFFSETWIDTH_WIDTH

protected static final int OFFSETWIDTH_WIDTH

BASEOFFSET_WIDTH

protected static final int BASEOFFSET_WIDTH

BASEID_WIDTH

protected static final int BASEID_WIDTH

ENTRYCOUNT_WIDTH

protected static final int ENTRYCOUNT_WIDTH

FIXED_HEADER_WIDTH

public static final int FIXED_HEADER_WIDTH

The byte size of an index's fixed header.

helper

protected static final ChannelUtil<IndexException> helper

validator

protected static final Validator<IndexException> validator

indexFile

protected final FileChannel indexFile

The underlying persistent representation of the index. In an effort to minimize concurrency contentions, the index file's position is never used after instantiation.

Constructor Detail

Index

public Index(FileChannel indexFile)
      throws IOException

Reads an index from the specified I/O channel.

Throws:

IOException

Index

public Index(FileChannel indexFile,
             boolean recover)
      throws IOException

Reads an index from the specified I/O channel.

Throws:

IOException

Index

protected Index(FileChannel indexFile,
                Word offsetWidth,
                long baseId,
                long baseOffset)
         throws IOException

Writes a new index to the specified file. This method was made protected in order to prevent the user from accidentally overwriting an existing index.

Throws:

IOException

See Also:

writeNewIndex(FileChannel, Word, long, long)

Method Detail

writeNewIndex

public static Index writeNewIndex(FileChannel indexFile,
                                  Word offsetWidth,
                                  long baseId,
                                  long baseOffset)
                           throws IOException

Writes a new index to the specified file.

Returns:

the newly created index instance

Throws:

IOException

getContentsSize

public long getContentsSize()

Returns the byte size of all the entry contents this index knows about.

getIndexSize

public long getIndexSize()

Returns the byte size of the index.

readOffsets

public void readOffsets(long id,
                        ByteBuffer out)
                 throws IOException

Reads and returns the offsets of the entry with the specified ID. The offsets are written into the given out-parameter buffer in LONG format using 0 (zero) as the base offset.

Throws:

NotFoundException - if id is out of range

IOException

readOffsets

public void readOffsets(long startId,
                        ByteBuffer out,
                        int count)
                 throws IOException

Reads and returns the offsets of count entries, starting at the specified startId. The offsets are written into the given out-parameter buffer in LONG format using 0 (zero) as the base offset. The number of entry offsets written to the out parameter is always count + 1.

Throws:

IOException

readOffsets

public void readOffsets(long startId,
                        ByteBuffer out,
                        int count,
                        ByteBuffer work)
                 throws IOException

Throws:

IOException

getEntryCount

public long getEntryCount()

Returns the number of entries that are in the index. The number of entries contained in the index is exactly equal to the number of entry IDs this index knows about.

getMetrics

public IndexMetrics getMetrics()

Returns the metrics of the index.

getLastOffset

public long getLastOffset()

Returns the last offset in the content file that this instance [implicitly] manages. This is always a non-negative number. It is also exactly equal to the sentinel offset of the index.

getNextId

public long getNextId()

Returns the ID that would be returned on inserting or killing the next entry.

commit

public void commit()
            throws IOException

Commits the entry count to the backing file.

Throws:

IOException

isAutoCommit

public boolean isAutoCommit()

Determines whether this instance is in auto-commit mode. When in auto-commit mode, every write operation that is not a delete causes the entry count of an index to bump up. However, the serial representation of the index remains unchanged while the entry count cell has yet to be updated.

setAutoCommit

public void setAutoCommit(boolean autoCommit)

Sets the auto-commit property.

pushNext

public long pushNext(long size)
              throws IOException

Pushes the next entry of the given size. Invoke this method when you don't want to have to know what the last offset was.

Throws:

IOException

killNext

public long killNext()
              throws IOException

Kills the next entry. Killing an entry is equivalent to creating and then deleting an entry in one step, except that it's faster.

Returns:

the value of next ID property post invocation

Throws:

IOException

killNext

public long killNext(int count)
              throws IOException

Kills the next count entry. Killing an entry is equivalent to creating and then deleting an entry in one step, except that this method is faster.

Returns:

the value of next ID property post invocation

Throws:

IOException

delete

public long delete(long id)
            throws IOException

Deletes the entry with the given ID. The entry with the given ID must already exist in this index.

Throws:

IOException

delete

public long delete(long startId,
                   int count)
            throws IOException

Deletes count entries starting with the given startId. The specified range of entry IDs must already exist in this index. Returns the offset of the next entry beyond the last entry deleted.

Throws:

IOException

close

public void close()
           throws IOException

Closes this index and its underlying file. Note if this instance's underlying file is shared by other instances of this class, then invoking this method will effectively close those instances as well.

It's OK to invoke this method multiple times.

Warning: This method does not commit the index prior to closing the stream. So if the auto-commit property of the instance was false, and if the last insertions were not followed by a commit, then those last insertions would be lost on invoking this method.

Specified by:

close in interface Closeable

Throws:

IOException

flush

public void flush()
           throws IOException

Flushes the underlying file stream. Note the commit caveat described in the close() method applies here too.

Throws:

IOException