com.faunos.skwish.sys.filters
Class UnionSegment

java.lang.Object
  com.faunos.skwish.Segment
      com.faunos.skwish.sys.filters.UnionSegment

All Implemented Interfaces:

Range

public class UnionSegment
extends Segment

A union of segments. An instance is based on any number of underlying subsegments. The subsegments are assumed to span non-overlapping IDs.

Each method call on an instance of this class delegates to a subsegment instance that handles the specified entry id. New entries are only ever added to the high subsegment.
KF: A subclass might allow entries to be added to fill the gaps, but this would break the entry lifecycle model proper.

Gap IDs
Entry IDs that fall in the gaps between segments (so called gap IDs are considered deleted (even though such entries have never been created).

Note about gap IDs

The other design choice was to consider gap IDs as entries with zero length. But under such a model, we'd have to distinguish between a deleted entry and one with zero size (something an ordinary segment supports), and so I favored the deleted state. Once deleted, always deleted; simpler and easier to implement. Such IDs are considered deleted because under this model entries may only be added on the high segment.

Author:

Babak Farhang

Field Summary

Fields inherited from class com.faunos.skwish.Segment

validator

Constructor Summary

	UnionSegment(Segment[] segments)
protected	UnionSegment(Segment[] segments, boolean checkOverlap, boolean readOnly, boolean autoSetReadOnly)

Method Summary

void	delete(long id, int count, boolean purge) Deletes count entries starting at the entry with the specified id.
protected long	failReadOnly() Throws an exception signifying an attempt to perform a write operation on a read-only instance.
long	getBaseId() Returns the instance's base ID.
void	getEntry(long id, ByteBuffer out, ByteBuffer workBuffer) Returns the contents of the entry with the specified id.
FileChannel	getEntryChannel(long id) Returns the contents of the entry with the given id as a FileChannel, or null, if deleted.
long	getEntryCount() Returns the number of entries in this instance.
int	getEntryPart(long id, long position, ByteBuffer out, ByteBuffer workBuffer) Returns the specified part of the entry contents with the specified id.
long	getEntrySize(long id, ByteBuffer workBuffer) Returns the size of the entry with the specified id.
long	getNextId() Returns the ID the entry will get on the next insertion.
protected Segment	getSegmentForId(long id) Returns the subsegment containing the given id, or null if no subsegment contains it.
protected Segment	hiSegment() Returns the subsegment with the largest base Id.
long	insertEntry(ByteBuffer entry) Inserts the given entry and returns the entry's ID.
long	insertEntry(ReadableByteChannel entry) Inserts the entry represented by the given channel.
boolean	isReadOnly() Determines whether this instance is read-only (unmodifiable).
long	killNext(int count) Kills the next count entry IDs.
protected Segment	loSegment() Returns the subsegment with the smallest base Id.

Methods inherited from class com.faunos.skwish.Segment

contains, delete, delete, getEntry, getEntrySize, getEntryStream, hi, isDeleted, isDeleted, killNext, lo, toString

Methods inherited from class java.lang.Object

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

Constructor Detail

UnionSegment

public UnionSegment(Segment[] segments)
             throws IOException

Throws:

IOException

UnionSegment

protected UnionSegment(Segment[] segments,
                       boolean checkOverlap,
                       boolean readOnly,
                       boolean autoSetReadOnly)
                throws IOException

Throws:

IOException

Method Detail

isReadOnly

public boolean isReadOnly()

Description copied from class: Segment

Determines whether this instance is read-only (unmodifiable).

Specified by:

isReadOnly in class Segment

Returns:

true, if any of the underlying segments is

See Also:

Write operations

delete

public void delete(long id,
                   int count,
                   boolean purge)
            throws IOException

Description copied from class: Segment

Deletes count entries starting at the entry with the specified id. The contents of the deleted entries may optionally be requested to be purged (overwritten) immediately; o.w. the deleted contents will be purged whenever the segment is compacted or merged with another segment.

Note that purging is not part of any transaction semantic; whether or not a purge immediately takes place on its being signaled is implementation-dependent.

Specified by:

delete in class Segment

Parameters:

id - the ID of the first entry to be deleted. Must be a valid ID in this segment [baseId, baseId + entryCount)

count - the number of entries to be deleted. Specifies a range of IDs to be deleted: [id, id + count). The range of IDs must be valid entries within this segment; o.w. an exception is raised.

purge - if true, the contents of the deleted entries are signaled to be purged (overwritten) immediately; o.w. the contents will be deleted on the next time the segment is compacted.

Throws:

IOException

getBaseId

public long getBaseId()

Description copied from class: Segment

Returns the instance's base ID. An instances valid entry IDs are in the range [baseId, baseId + entryCount).

Specified by:

getBaseId in class Segment

See Also:

Segment.getEntryCount()

getEntryPart

public int getEntryPart(long id,
                        long position,
                        ByteBuffer out,
                        ByteBuffer workBuffer)
                 throws IOException

Description copied from class: Segment

Returns the specified part of the entry contents with the specified id. Up to out.remaining() bytes of the contents of the entry are copied into the given out buffer.

Specified by:

getEntryPart in class Segment

position - the starting position into the entry from where data will be copied into the out buffer

out - the out buffer into which data is written

workBuffer - a work buffer with a minimum size of 16

Returns:

the number of bytes read (possibly zero if out has no remaining bytes), or -1, if the position is greater than the size of the entry, or if the entry is deleted.

Throws:

IOException

getEntry

public void getEntry(long id,
                     ByteBuffer out,
                     ByteBuffer workBuffer)
              throws IOException

Description copied from class: Segment

Returns the contents of the entry with the specified id. If the entry is deleted, the method returns without modifying the out buffer.

Specified by:

getEntry in class Segment

out - the buffer into which the contents are written. Its remaining bytes must be large enough; o.w., an exception is raised.

workBuffer - a work buffer used internally to read offsets. The minimum capacity of this work buffer must be 16

Throws:

IOException

getEntryChannel

public FileChannel getEntryChannel(long id)
                            throws IOException

Description copied from class: Segment

Returns the contents of the entry with the given id as a FileChannel, or null, if deleted. The returned channel is positioned at zero and is read-only.

Specified by:

getEntryChannel in class Segment

Throws:

IOException

getEntryCount

public long getEntryCount()

Description copied from class: Segment

Returns the number of entries in this instance.

Specified by:

getEntryCount in class Segment

getEntrySize

public long getEntrySize(long id,
                         ByteBuffer workBuffer)
                  throws IOException

Description copied from class: Segment

Returns the size of the entry with the specified id. A work buffer with a minimum size of 16 must be passed in.

Specified by:

getEntrySize in class Segment

Returns:

the size of the entry if present; -1, if deleted.

Throws:

IOException

getNextId

public long getNextId()

Description copied from class: Segment

Returns the ID the entry will get on the next insertion.

Specified by:

getNextId in class Segment

See Also:

ID invariants

killNext

public long killNext(int count)
              throws IOException

Description copied from class: Segment

Kills the next count entry IDs. A killed entry is an entry that begins (and ends) life in the deleted state.

Specified by:

killNext in class Segment

Parameters:

count - the number of entries to kill (must be greater than 1)

Returns:

the value that getNextId() returns after this method has completed

Throws:

IOException

insertEntry

public long insertEntry(ByteBuffer entry)
                 throws IOException

Description copied from class: Segment

Inserts the given entry and returns the entry's ID. The contents of the entry is understood to be the remaining contents in the given buffer.

Specified by:

insertEntry in class Segment

Parameters:

entry - they contents of the entry

Returns:

the ID assigned to the entry

Throws:

IOException

insertEntry

public long insertEntry(ReadableByteChannel entry)
                 throws IOException

Description copied from class: Segment

Inserts the entry represented by the given channel. The contents are of the entry is understood to be the entire remaining contents in the specified channel.

This is the most efficient method for inserting a large-size entry (even one that doesn't fit in memory).

Specified by:

insertEntry in class Segment

Throws:

IOException

getSegmentForId

protected final Segment getSegmentForId(long id)

Returns the subsegment containing the given id, or null if no subsegment contains it.

Parameters:

id - an ID contained within this union

loSegment

protected final Segment loSegment()

Returns the subsegment with the smallest base Id.

hiSegment

protected final Segment hiSegment()

Returns the subsegment with the largest base Id.

failReadOnly

protected long failReadOnly()

Throws an exception signifying an attempt to perform a write operation on a read-only instance.

Throws:

UnsupportedOperationException