com.faunos.skwish.sys
Class IndexMetrics

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

public final class IndexMetrics
extends Object

Encapsulates the immutable properties of an index and its data model. The Index class maintains an IndexMetrics instance in order to store the data read in the HEADER part of the index file (sans the entry count part, which is mutable). Index also delegates the actual reading and writing of offset values to this class.

Implementation Note on the representation of deleted offsets

Deleted offsets are internally represented simply with the high bit turned on. That way, if a read occurs while a partial write is underway, the data read will still be self-consistent. The external representation of a deleted offset value (that is, what the users of this class see), on the other hand, is given by

      deletedOffset = -offset - 1
 

Either way, user code doesn't actually have to know what this exact representation is: the isDeleted(long), toAbsolute(long), and toDeleted(long) methods shield the user from this knowledge.

Author:

Babak Farhang

Constructor Summary

IndexMetrics(long zeroPosition, Word wordType, long baseId, long baseOffset)
Creates a new instance.

IndexMetrics(Word wordType)
Creates a new instance with default base offset, zero position and base ID of zero.

IndexMetrics(Word wordType, long baseOffset)
Creates a new instance with default zero position and base ID of zero.

Method Summary

long	getBaseId() Returns the base ID.
long	getBaseOffset() Returns the base offset.
long	getMaxOffset() Returns the magnitude of the largest offset that is representable in this metric.
Word	getOffsetWordType() Returns the byte width of entry offsets (as a Word).
long	getPositionForId(long id) Returns the file position (in the index file) of the entry with the given ID.
long	getZeroPosition() Returns the file position (in the index file) of the first entry offset.
static boolean	isDeleted(long offset) Determines whether the given offset represents a deleted offset.
IndexMetrics	newBaseId(long baseId)
long	readOffset(ByteBuffer in) Reads and returns the offset contained in the given buffer.
static long	readOffset(ByteBuffer in, Word wordType, long baseOffset) Reads and returns the offset contained in the given buffer using the specified base offset and word type.
static long	toAbsolute(long offset) Returns the given signed offset as an absolute offset.
static long	toDeleted(long offset) Returns the given offset as a deleted offset.
IndexMetrics	writeOffset(long offset, ByteBuffer out) Writes the specified offset to the given buffer.
static void	writeOffset(long offset, ByteBuffer out, Word targetWordType, long targetBaseOffset) Writes the specified offset to the given buffer.

Methods inherited from class java.lang.Object

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

Constructor Detail

IndexMetrics

public IndexMetrics(Word wordType)

Creates a new instance with default base offset, zero position and base ID of zero.

IndexMetrics

public IndexMetrics(Word wordType,
                    long baseOffset)

Creates a new instance with default zero position and base ID of zero. Such an instance might be created if you simply want to just translate offsets.

IndexMetrics

public IndexMetrics(long zeroPosition,
                    Word wordType,
                    long baseId,
                    long baseOffset)

Creates a new instance. The integral parameters must all be non-negative.

Method Detail

getZeroPosition

public long getZeroPosition()

Returns the file position (in the index file) of the first entry offset. If the index is empty, then the first entry is the sentinel entry.

See Also:

getPositionForId(long)

getOffsetWordType

public Word getOffsetWordType()

Returns the byte width of entry offsets (as a Word).

getBaseId

public long getBaseId()

Returns the base ID. IDs in the index are interpreted relative to this base. The base ID is the smallest possible ID in the index.

getBaseOffset

public long getBaseOffset()

Returns the base offset. Offsets are recorded relative to this base offset.

getMaxOffset

public long getMaxOffset()

Returns the magnitude of the largest offset that is representable in this metric.

getPositionForId

public long getPositionForId(long id)

Returns the file position (in the index file) of the entry with the given ID. id should not be less than the base ID.

See Also:

getZeroPosition()

readOffset

public long readOffset(ByteBuffer in)

Reads and returns the offset contained in the given buffer. The offset is interpreted using this instance's base offset and offset word type.

readOffset

public static long readOffset(ByteBuffer in,
                              Word wordType,
                              long baseOffset)

Reads and returns the offset contained in the given buffer using the specified base offset and word type.

writeOffset

public IndexMetrics writeOffset(long offset,
                                ByteBuffer out)

Writes the specified offset to the given buffer. If the magnitude of the offset is larger than what is representable by this metric, then an exception will be raised.

See Also:

getMaxOffset()

writeOffset

public static void writeOffset(long offset,
                               ByteBuffer out,
                               Word targetWordType,
                               long targetBaseOffset)

Writes the specified offset to the given buffer. If the magnitude of the offset is larger than what is representable by the metric (as specified in targetBaseOffset and targetWordType, then an exception is raised.

toAbsolute

public static long toAbsolute(long offset)

Returns the given signed offset as an absolute offset.

See Also:

toDeleted(long)

toDeleted

public static long toDeleted(long offset)

Returns the given offset as a deleted offset. If the the offset already represents a deleted offset (negative), then it's returned unchanged.

See Also:

toAbsolute(long), isDeleted(long)

isDeleted

public static boolean isDeleted(long offset)

Determines whether the given offset represents a deleted offset.

See Also:

toDeleted(long)

newBaseId

public IndexMetrics newBaseId(long baseId)