com.amazon.carbonado.raw
Class RawCursor<S>

java.lang.Object
  com.amazon.carbonado.cursor.AbstractCursor<S>
      com.amazon.carbonado.raw.RawCursor<S>

All Implemented Interfaces:

Cursor<S>

public abstract class RawCursor<S>
extends AbstractCursor<S>

Abstract Cursor implementation for a repository that manipulates raw bytes.

Author:

Brian S O'Neill

Field Summary

protected Lock

mLock Lock object, as passed into the constructor

Constructor Summary

protected

RawCursor(Lock lock, byte[] startBound, boolean inclusiveStart, byte[] endBound, boolean inclusiveEnd, int maxPrefix, boolean reverse)

Method Summary

void	close() Call close to release any resources being held by this cursor.
protected int	compareKeysPartially(byte[] key1, byte[] key2) Returns <0 if key1 is less, 0 if equal (at least partially), >0 if key1 is greater.
protected void	disableKeyAndValue() An optimization hint which disables key and value acquisition.
protected void	disableValue() An optimization hint which disables just value acquisition.
protected void	enableKeyAndValue() Enable key and value acquisition again, after they have been disabled.
protected abstract byte[]	getCurrentKey() Returns the contents of the current key being referenced, or null otherwise.
protected abstract byte[]	getCurrentValue() Returns the contents of the current value being referenced, or null otherwise.
protected void	handleNoSuchElement() Called right before throwing NoSuchElementException.
boolean	hasNext() Returns true if this cursor has more elements.
protected abstract S	instantiateCurrent() Returns a new Storable instance for the currently referenced entry.
S	next() Returns the next element from this cursor.
protected abstract void	release() Release any internal resources, called when closed.
int	skipNext(int amount) Skips forward by the specified amount of elements, returning the actual amount skipped.
protected abstract boolean	toFirst() Move the cursor to the first available entry.
protected abstract boolean	toFirst(byte[] key) Move the cursor to the first available entry at or after the given key.
protected abstract boolean	toLast() Move the cursor to the last available entry.
protected abstract boolean	toLast(byte[] key) Move the cursor to the last available entry at or before the given key.
protected abstract boolean	toNext() Move the cursor to the next available entry, returning false if none.
protected int	toNext(int amount) Move the cursor to the next available entry, incrementing by the amount given.
protected boolean	toNextKey() Move the cursor to the next unique key, returning false if none.
protected abstract boolean	toPrevious() Move the cursor to the previous available entry, returning false if none.
protected int	toPrevious(int amount) Move the cursor to the previous available entry, decrementing by the amount given.
protected boolean	toPreviousKey() Move the cursor to the previous unique key, returning false if none.

Methods inherited from class com.amazon.carbonado.cursor.AbstractCursor

copyInto, copyInto, toList, toList

Methods inherited from class java.lang.Object

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

Field Detail

mLock

protected final Lock mLock

Lock object, as passed into the constructor

Constructor Detail

RawCursor

protected RawCursor(Lock lock,
                    byte[] startBound,
                    boolean inclusiveStart,
                    byte[] endBound,
                    boolean inclusiveEnd,
                    int maxPrefix,
                    boolean reverse)

Parameters:

lock - operations lock on this object

startBound - specify the starting key for the cursor, or null if first

inclusiveStart - true if start bound is inclusive

endBound - specify the ending key for the cursor, or null if last

inclusiveEnd - true if end bound is inclusive

maxPrefix - maximum expected common initial bytes in start and end bound

reverse - when true, iteration is reversed

Throws:

IllegalArgumentException - if any bound is null but is not inclusive

Method Detail

close

public void close()
           throws FetchException

Description copied from interface: Cursor

Call close to release any resources being held by this cursor. Further operations on this cursor will behave as if there are no results.

Throws:

FetchException

hasNext

public boolean hasNext()
                throws FetchException

Description copied from interface: Cursor

Returns true if this cursor has more elements. In other words, returns true if next would return an element rather than throwing an exception.

Throws:

FetchException - if storage layer throws an exception

next

public S next()
       throws FetchException,
              NoSuchElementException

Description copied from interface: Cursor

Returns the next element from this cursor. This method may be called repeatedly to iterate through the results.

Throws:

FetchException - if storage layer throws an exception

NoSuchElementException - if the cursor has no next element.

skipNext

public int skipNext(int amount)
             throws FetchException

Description copied from interface: Cursor

Skips forward by the specified amount of elements, returning the actual amount skipped. The actual amount is less than the requested amount only if the end of the results was reached.

Specified by:

skipNext in interface Cursor<S>

Overrides:

skipNext in class AbstractCursor<S>

Parameters:

amount - maximum amount of elements to skip

Returns:

actual amount skipped

Throws:

FetchException - if storage layer throws an exception

release

protected abstract void release()
                         throws FetchException

Release any internal resources, called when closed.

Throws:

FetchException

getCurrentKey

protected abstract byte[] getCurrentKey()
                                 throws FetchException

Returns the contents of the current key being referenced, or null otherwise. Caller is responsible for making a copy of the key. The array must not be modified concurrently.

If cursor is not opened, null must be returned.

Returns:

currently referenced key bytes or null if no current

Throws:

IllegalStateException - if key is disabled

FetchException

getCurrentValue

protected abstract byte[] getCurrentValue()
                                   throws FetchException

Returns the contents of the current value being referenced, or null otherwise. Caller is responsible for making a copy of the value. The array must not be modified concurrently.

If cursor is not opened, null must be returned.

Returns:

currently referenced value bytes or null if no current

Throws:

IllegalStateException - if value is disabled

FetchException

disableKeyAndValue

protected void disableKeyAndValue()

An optimization hint which disables key and value acquisition. The default implementation of this method does nothing.

disableValue

protected void disableValue()

An optimization hint which disables just value acquisition. The default implementation of this method does nothing.

enableKeyAndValue

protected void enableKeyAndValue()
                          throws FetchException

Enable key and value acquisition again, after they have been disabled. Calling this method forces the key and value to be re-acquired, if they had been disabled. Key and value acquisition must be enabled by default. The default implementation of this method does nothing.

Throws:

FetchException

instantiateCurrent

protected abstract S instantiateCurrent()
                                 throws FetchException

Returns a new Storable instance for the currently referenced entry.

Returns:

new Storable instance, never null

Throws:

IllegalStateException - if no current entry to instantiate

FetchException

toFirst

protected abstract boolean toFirst()
                            throws FetchException

Move the cursor to the first available entry. If false is returned, the cursor must be positioned before the first available entry.

Returns:

true if first entry exists and is now current

Throws:

IllegalStateException - if cursor is not opened

FetchException

toFirst

protected abstract boolean toFirst(byte[] key)
                            throws FetchException

Move the cursor to the first available entry at or after the given key. If false is returned, the cursor must be positioned before the first available entry. Caller is responsible for preserving contents of array.

Parameters:

key - key to search for

Returns:

true if first entry exists and is now current

Throws:

IllegalStateException - if cursor is not opened

FetchException

toLast

protected abstract boolean toLast()
                           throws FetchException

Move the cursor to the last available entry. If false is returned, the cursor must be positioned after the last available entry.

Returns:

true if last entry exists and is now current

Throws:

IllegalStateException - if cursor is not opened

FetchException

toLast

protected abstract boolean toLast(byte[] key)
                           throws FetchException

Move the cursor to the last available entry at or before the given key. If false is returned, the cursor must be positioned after the last available entry. Caller is responsible for preserving contents of array.

Parameters:

key - key to search for

Returns:

true if last entry exists and is now current

Throws:

IllegalStateException - if cursor is not opened

FetchException

toNext

protected abstract boolean toNext()
                           throws FetchException

Move the cursor to the next available entry, returning false if none. If false is returned, the cursor must be positioned after the last available entry.

Returns:

true if moved to next entry

Throws:

IllegalStateException - if cursor is not opened

FetchException

toNext

protected int toNext(int amount)
              throws FetchException

Move the cursor to the next available entry, incrementing by the amount given. The actual amount incremented is returned. If the amount is less then requested, the cursor must be positioned after the last available entry. Subclasses may wish to override this method with a faster implementation.

Calling to toNext(1) is equivalent to calling toNext().

Parameters:

amount - positive amount to advance

Returns:

actual amount advanced

Throws:

IllegalStateException - if cursor is not opened

FetchException

toNextKey

protected boolean toNextKey()
                     throws FetchException

Move the cursor to the next unique key, returning false if none. If false is returned, the cursor must be positioned after the last available entry. Subclasses may wish to override this method with a faster implementation.

Returns:

true if moved to next unique key

Throws:

IllegalStateException - if cursor is not opened

FetchException

toPrevious

protected abstract boolean toPrevious()
                               throws FetchException

Move the cursor to the previous available entry, returning false if none. If false is returned, the cursor must be positioned before the first available entry.

Returns:

true if moved to previous entry

Throws:

IllegalStateException - if cursor is not opened

FetchException

toPrevious

protected int toPrevious(int amount)
                  throws FetchException

Move the cursor to the previous available entry, decrementing by the amount given. The actual amount decremented is returned. If the amount is less then requested, the cursor must be positioned before the first available entry. Subclasses may wish to override this method with a faster implementation.

Calling to toPrevious(1) is equivalent to calling toPrevious().

Parameters:

amount - positive amount to retreat

Returns:

actual amount retreated

Throws:

IllegalStateException - if cursor is not opened

FetchException

toPreviousKey

protected boolean toPreviousKey()
                         throws FetchException

Move the cursor to the previous unique key, returning false if none. If false is returned, the cursor must be positioned before the first available entry. Subclasses may wish to override this method with a faster implementation.

Returns:

true if moved to previous unique key

Throws:

IllegalStateException - if cursor is not opened

FetchException

compareKeysPartially

protected int compareKeysPartially(byte[] key1,
                                   byte[] key2)

Returns <0 if key1 is less, 0 if equal (at least partially), >0 if key1 is greater.

handleNoSuchElement

protected void handleNoSuchElement()
                            throws FetchException

Called right before throwing NoSuchElementException. Subclasses may override to do special checks or throw a different exception.

Throws:

FetchException