RawCursor (Carbonado 1.2.3 API)

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
+ + + + + + + + + + +
Fields
Modifier and Type Field and Description
protected java.util.concurrent.locks.Lock mLock +
Lock object, as passed into the constructor
+
+

Fields
Modifier and Type	Field and Description
`protected java.util.concurrent.locks.Lock`	`mLock` + Lock object, as passed into the constructor +

+ +

Constructor Summary

+ + + + + + + + + + +

Constructors
Modifier	Constructor and Description
`protected`	`RawCursor(java.util.concurrent.locks.Lock lock, + byte[] startBound, + boolean inclusiveStart, + byte[] endBound, + boolean inclusiveEnd, + int maxPrefix, + boolean reverse)`

+ +

+ + +

Method Summary

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

Methods
Modifier and Type	Method and Description
`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 java.util.concurrent.locks.Lock mLock
```
    +
    Lock object, as passed into the constructor
    +
  +
+ +
- + + +
  Constructor Detail
  + + + +
  - +
    RawCursor
    +
```
protected RawCursor(java.util.concurrent.locks.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:
    +
    java.lang.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,
+              java.util.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
    +
    java.util.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:
    +
    java.lang.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:
    +
    java.lang.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:
    +
    java.lang.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:
    +
    java.lang.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:
    +
    java.lang.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:
    +
    java.lang.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:
    +
    java.lang.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:
    +
    java.lang.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:
    +
    java.lang.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:
    +
    java.lang.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:
    +
    java.lang.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:
    +
    java.lang.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:
    +
    java.lang.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
    +
  +
+

Class RawCursor<S>

Field Summary

Constructor Summary

Method Summary

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

Methods inherited from class java.lang.Object

Field Detail

mLock

Constructor Detail

RawCursor

Method Detail

close

hasNext

next

skipNext

release

getCurrentKey

getCurrentValue

disableKeyAndValue

disableValue

enableKeyAndValue

instantiateCurrent

toFirst

toFirst

toLast

toLast

toNext

toNext

toNextKey

toPrevious

toPrevious

toPreviousKey

compareKeysPartially

handleNoSuchElement