com.faunos.skwish
Class Segment

java.lang.Object
  com.faunos.skwish.Segment

All Implemented Interfaces:

Range

Direct Known Subclasses:

BaseSegment, EmptySegment, FilterSegment, SettableSegment, TxnSegment, UnionSegment

public abstract class Segment
extends Object
implements Range

The elementary storage class. A segment logically consists of a mapping of integral IDs to entries. An entry is just an uninterpreted, bounded sequence of bytes. It may represent a file, a record, whatever. The entry IDs a segment knows about are in the contiguous range [baseId, nextId).

So a segment is really a random access list of blobs.

Here's the general usage pattern. A user first creates an entry using one of the insertion methods and gets an entry ID (a long). The user does not control what the ID will be: entry IDs are doled out in ascending order and the next ID is determined by the nextId property. Given the entry's ID, the user can either retrieve the entry using one of the getEntry.. methods, or alternatively, delete the entry. A delete cannot be undone: once deleted, forever deleted.

Thus an entry may only ever be added or removed; it cannot be modified.

BF: --8/29/08
We're sticking to this model for time being, though the machinery for a bounded update model (where you can update the contents of an entry, but not its size) is already here. I hope to return to this once I have transactions worked out.

Read Operations

Every segment instance has read privileges. The segment read methods are categorized below.

Meta-information accessors

• getBaseId()
• getEntryCount()
• getEntrySize(long), getEntrySize(long, ByteBuffer)
• getNextId()
• isDeleted(long), isDeleted(long, ByteBuffer)
• isReadOnly()

Also, the following invariant regarding entry IDs holds:

         baseId + entryCount = nextId
 

Entry accessors

• getEntry(long, ByteBuffer), and getEntry(long, ByteBuffer, ByteBuffer)
• getEntryChannel(long)
• getEntryStream(long)

Note: Invoking any of the above accessors with an out of range id results in a thrown NotFoundException.

Write Operations

A segment supports write operations if its read-only property is false. If one write operation is supported, then all write operations are supported. Invoking any of the methods in this section on a read-only instance raises an java.lang.UnsupportedOperationException.

Insert Methods

• insertEntry(ByteBuffer)
• insertEntry(ReadableByteChannel)

Delete Methods

Already existing entries may be deleted one at a time

• delete(long), or in bulk
• delete(long, int), or with the optional purge parameter
• delete(long, int, boolean) signaling that the deleted contents should be purged ASAP on the file system.

Killing entry IDs

If, for whatever reason, the application wants to discard the next entity ID, it can always insert and then delete the just inserted entry. This should be a rare need (see also Infrequent delete assumption) from the application's viewpoint. Still, the functionality to perform the above two steps in one call is exposed (perhaps because it is implemented easily and efficiently), and it can be used when merging segments.

• killNext(), and
• killNext(int) (bulk kill)

Note on the Range Implementation

The implementation of the Range interface here is only valid if the Segment instance is not empty (entryCount > 0); o.w. the Range contract is violated (because Range.lo == Range.hi).

Author:

Babak Farhang

See Also:

isReadOnly()

Field Summary

protected static Validator<SegmentException>

validator A centralized exception raising mechanism.

Constructor Summary

Segment()

Method Summary

boolean	contains(long id) Determines whether the given entry ID exists in this segment.
void	delete(long id) Deletes the entry with the specified id.
void	delete(long id, int count) Deletes count entries starting at the entry with the specified id.
abstract void	delete(long id, int count, boolean purge) Deletes count entries starting at the entry with the specified id.
abstract long	getBaseId() Returns the instance's base ID.
void	getEntry(long id, ByteBuffer out) Returns the contents of the entry with the specified id.
abstract void	getEntry(long id, ByteBuffer out, ByteBuffer workBuffer) Returns the contents of the entry with the specified id.
abstract FileChannel	getEntryChannel(long id) Returns the contents of the entry with the given id as a FileChannel, or null, if deleted.
abstract long	getEntryCount() Returns the number of entries in this instance.
abstract 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) Returns the size of the entry with the specified id.
abstract long	getEntrySize(long id, ByteBuffer workBuffer) Returns the size of the entry with the specified id.
InputStream	getEntryStream(long id) Returns the entry with the given id as an input stream, or null, if deleted.
abstract long	getNextId() Returns the ID the entry will get on the next insertion.
long	hi() Returns the high (exclusive) value of the range.
abstract long	insertEntry(ByteBuffer entry) Inserts the given entry and returns the entry's ID.
abstract long	insertEntry(ReadableByteChannel entry) Inserts the entry represented by the given channel.
boolean	isDeleted(long id) Determines whether the entry with the specified id is deleted.
boolean	isDeleted(long id, ByteBuffer workBuffer) Determines whether the entry with the specified id is deleted.
abstract boolean	isReadOnly() Determines whether this instance is read-only (unmodifiable).
long	killNext() Kills the next entry ID.
abstract long	killNext(int count) Kills the next count entry IDs.
long	lo() Returns the low (inclusive) value of the range.
String	toString() Returns a concatenation of the simple class name together with the base ID and entry count.

Methods inherited from class java.lang.Object

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

Field Detail

validator

protected static final Validator<SegmentException> validator

A centralized exception raising mechanism. Subclasses can use it too.

Constructor Detail

Segment

public Segment()

Method Detail

getBaseId

public abstract long getBaseId()

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

See Also:

getEntryCount()

lo

public final long lo()

Description copied from interface: Range

Returns the low (inclusive) value of the range.

Specified by:

lo in interface Range

Returns:

the baseId property

getEntryCount

public abstract long getEntryCount()

Returns the number of entries in this instance.

getNextId

public abstract long getNextId()

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

See Also:

ID invariants

hi

public final long hi()

Description copied from interface: Range

Returns the high (exclusive) value of the range.

Specified by:

hi in interface Range

Returns:

the nextId property

contains

public boolean contains(long id)

Determines whether the given entry ID exists in this segment. The associated entry may or may not be deleted.

insertEntry

public abstract long insertEntry(ByteBuffer entry)
                          throws IOException

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.

Parameters:

entry - they contents of the entry

Returns:

the ID assigned to the entry

Throws:

IOException

insertEntry

public abstract long insertEntry(ReadableByteChannel entry)
                          throws IOException

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).

Throws:

IOException

killNext

public long killNext()
              throws IOException

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

Returns:

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

Throws:

IOException

killNext

public abstract long killNext(int count)
                       throws IOException

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

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

delete

public void delete(long id)
            throws IOException

Deletes the entry with the specified id. The entry is marked as deleted; the deleted contents will be purged whenever the segment is compacted or merged with another segment.

Parameters:

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

Throws:

IOException

delete

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

Deletes count entries starting at the entry with the specified id. The entries are marked as deleted; the deleted contents will be purged whenever the segment is compacted or merged with another 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.

Throws:

IOException

delete

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

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.

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

isDeleted

public boolean isDeleted(long id)
                  throws IOException

Determines whether the entry with the specified id is deleted.

Throws:

IOException

isDeleted

public boolean isDeleted(long id,
                         ByteBuffer workBuffer)
                  throws IOException

Determines whether the entry with the specified id is deleted. A work buffer (of at least 16 bytes size) must be supplied with this method.

Throws:

IOException

getEntrySize

public long getEntrySize(long id)
                  throws IOException

Returns the size of the entry with the specified id.

Returns:

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

Throws:

IOException

getEntrySize

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

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

Returns:

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

Throws:

IOException

getEntryPart

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

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.

Parameters:

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)
              throws IOException

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

Parameters:

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

Throws:

IOException

getEntryStream

public InputStream getEntryStream(long id)
                           throws IOException

Returns the entry with the given id as an input stream, or null, if deleted.

Throws:

IOException

getEntryChannel

public abstract FileChannel getEntryChannel(long id)
                                     throws IOException

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.

Throws:

IOException

getEntry

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

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

Parameters:

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

isReadOnly

public abstract boolean isReadOnly()

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

See Also:

Write operations

toString

public String toString()

Returns a concatenation of the simple class name together with the base ID and entry count.

Overrides:

toString in class Object