com.sleepycat.persist

Class BasicCursor<V>

java.lang.Object

com.sleepycat.persist.BasicCursor<V>

All Implemented Interfaces:

EntityCursor<V>, ForwardCursor<V>, java.io.Closeable, java.lang.AutoCloseable, java.lang.Iterable<V>

Direct Known Subclasses:

SubIndexCursor

 class BasicCursor<V>
extends java.lang.Object
implements EntityCursor<V>

Implements EntityCursor and uses a ValueAdapter so that it can enumerate either keys or entities.

Author:

Mark Hayes

Field Summary

Fields

Modifier and Type	Field and Description
(package private) ValueAdapter<V>	adapter
(package private) RangeCursor	cursor
(package private) DatabaseEntry	data
(package private) DatabaseEntry	key
(package private) DatabaseEntry	pkey
(package private) boolean	updateAllowed

Constructor Summary

Constructors

Constructor and Description
BasicCursor(RangeCursor cursor, ValueAdapter<V> adapter, boolean updateAllowed)

Method Summary

Methods

Modifier and Type	Method and Description
(package private) void	checkInitialized()
void	close() Closes the cursor.
int	count() Returns the number of values (duplicates) for the key at the cursor position, or returns zero if all values for the key have been deleted.
long	countEstimate() Returns a rough estimate of the number of values (duplicates) for the key at the cursor position, or returns zero if all values for the key have been deleted.
V	current() Returns the value at the cursor position, or null if the value at the cursor position has been deleted.
V	current(LockMode lockMode) Returns the value at the cursor position, or null if the value at the cursor position has been deleted.
boolean	delete() Deletes the entity at the cursor position.
EntityCursor<V>	dup() Duplicates the cursor at the cursor position.
V	first() Moves the cursor to the first value and returns it, or returns null if the cursor range is empty.
V	first(LockMode lockMode) Moves the cursor to the first value and returns it, or returns null if the cursor range is empty.
CacheMode	getCacheMode() Returns the CacheMode used for operations performed using this cursor.
java.util.Iterator<V>	iterator() Returns an iterator over the key range, starting with the value following the current position or at the first value if the cursor is uninitialized.
java.util.Iterator<V>	iterator(LockMode lockMode) Returns an iterator over the key range, starting with the value following the current position or at the first value if the cursor is uninitialized.
V	last() Moves the cursor to the last value and returns it, or returns null if the cursor range is empty.
V	last(LockMode lockMode) Moves the cursor to the last value and returns it, or returns null if the cursor range is empty.
V	next() Moves the cursor to the next value and returns it, or returns null if there are no more values in the cursor range.
V	next(LockMode lockMode) Moves the cursor to the next value and returns it, or returns null if there are no more values in the cursor range.
V	nextDup() Moves the cursor to the next value with the same key (duplicate) and returns it, or returns null if no more values are present for the key at the current position.
V	nextDup(LockMode lockMode) Moves the cursor to the next value with the same key (duplicate) and returns it, or returns null if no more values are present for the key at the current position.
V	nextNoDup() Moves the cursor to the next value with a different key and returns it, or returns null if there are no more unique keys in the cursor range.
V	nextNoDup(LockMode lockMode) Moves the cursor to the next value with a different key and returns it, or returns null if there are no more unique keys in the cursor range.
V	prev() Moves the cursor to the previous value and returns it, or returns null if there are no preceding values in the cursor range.
V	prev(LockMode lockMode) Moves the cursor to the previous value and returns it, or returns null if there are no preceding values in the cursor range.
V	prevDup() Moves the cursor to the previous value with the same key (duplicate) and returns it, or returns null if no preceding values are present for the key at the current position.
V	prevDup(LockMode lockMode) Moves the cursor to the previous value with the same key (duplicate) and returns it, or returns null if no preceding values are present for the key at the current position.
V	prevNoDup() Moves the cursor to the preceding value with a different key and returns it, or returns null if there are no preceding unique keys in the cursor range.
V	prevNoDup(LockMode lockMode) Moves the cursor to the preceding value with a different key and returns it, or returns null if there are no preceding unique keys in the cursor range.
(package private) V	returnValue(OperationStatus status)
void	setCacheMode(CacheMode cacheMode) Changes the CacheMode used for operations performed using this cursor.
boolean	update(V entity) Replaces the entity at the cursor position with the given entity.

Methods inherited from class java.lang.Object

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

Field Detail

cursor

RangeCursor cursor

adapter

ValueAdapter<V> adapter

updateAllowed

boolean updateAllowed

key

DatabaseEntry key

pkey

DatabaseEntry pkey

data

DatabaseEntry data

Constructor Detail

BasicCursor

BasicCursor(RangeCursor cursor,
           ValueAdapter<V> adapter,
           boolean updateAllowed)

Method Detail

first

public V first()
        throws DatabaseException

Description copied from interface: EntityCursor

Moves the cursor to the first value and returns it, or returns null if the cursor range is empty.

LockMode.DEFAULT is used implicitly.

Specified by:

first in interface EntityCursor<V>

Returns:

the first value, or null if the cursor range is empty.

Throws:

OperationFailureException - if one of the Read Operation Failures occurs.

EnvironmentFailureException - if an unexpected, internal or environment-wide failure occurs.

DatabaseException - the base class for all BDB exceptions.

first

public V first(LockMode lockMode)
        throws DatabaseException

Description copied from interface: EntityCursor

Moves the cursor to the first value and returns it, or returns null if the cursor range is empty.

Specified by:

first in interface EntityCursor<V>

Parameters:

lockMode - the lock mode to use for this operation, or null to use LockMode.DEFAULT.

Returns:

the first value, or null if the cursor range is empty.

Throws:

OperationFailureException - if one of the Read Operation Failures occurs.

EnvironmentFailureException - if an unexpected, internal or environment-wide failure occurs.

DatabaseException - the base class for all BDB exceptions.

last

public V last()
       throws DatabaseException

Description copied from interface: EntityCursor

Moves the cursor to the last value and returns it, or returns null if the cursor range is empty.

LockMode.DEFAULT is used implicitly.

Specified by:

last in interface EntityCursor<V>

Returns:

the last value, or null if the cursor range is empty.

Throws:

OperationFailureException - if one of the Read Operation Failures occurs.

EnvironmentFailureException - if an unexpected, internal or environment-wide failure occurs.

DatabaseException - the base class for all BDB exceptions.

last

public V last(LockMode lockMode)
       throws DatabaseException

Description copied from interface: EntityCursor

Moves the cursor to the last value and returns it, or returns null if the cursor range is empty.

Specified by:

last in interface EntityCursor<V>

Parameters:

lockMode - the lock mode to use for this operation, or null to use LockMode.DEFAULT.

Returns:

the last value, or null if the cursor range is empty.

Throws:

OperationFailureException - if one of the Read Operation Failures occurs.

EnvironmentFailureException - if an unexpected, internal or environment-wide failure occurs.

DatabaseException - the base class for all BDB exceptions.

next

public V next()
       throws DatabaseException

Description copied from interface: EntityCursor

Moves the cursor to the next value and returns it, or returns null if there are no more values in the cursor range. If the cursor is uninitialized, this method is equivalent to EntityCursor.first().

LockMode.DEFAULT is used implicitly.

Specified by:

next in interface EntityCursor<V>

Specified by:

next in interface ForwardCursor<V>

Returns:

the next value, or null if there are no more values in the cursor range.

Throws:

OperationFailureException - if one of the Read Operation Failures occurs.

EnvironmentFailureException - if an unexpected, internal or environment-wide failure occurs.

DatabaseException - the base class for all BDB exceptions.

next

public V next(LockMode lockMode)
       throws DatabaseException

Description copied from interface: EntityCursor

Moves the cursor to the next value and returns it, or returns null if there are no more values in the cursor range. If the cursor is uninitialized, this method is equivalent to EntityCursor.first().

Specified by:

next in interface EntityCursor<V>

Specified by:

next in interface ForwardCursor<V>

Parameters:

lockMode - the lock mode to use for this operation, or null to use LockMode.DEFAULT.

Returns:

the next value, or null if there are no more values in the cursor range.

Throws:

OperationFailureException - if one of the Read Operation Failures occurs.

EnvironmentFailureException - if an unexpected, internal or environment-wide failure occurs.

DatabaseException - the base class for all BDB exceptions.

nextDup

public V nextDup()
          throws DatabaseException

Description copied from interface: EntityCursor

Moves the cursor to the next value with the same key (duplicate) and returns it, or returns null if no more values are present for the key at the current position.

LockMode.DEFAULT is used implicitly.

Specified by:

nextDup in interface EntityCursor<V>

Returns:

the next value with the same key, or null if no more values are present for the key at the current position.

Throws:

OperationFailureException - if one of the Read Operation Failures occurs.

EnvironmentFailureException - if an unexpected, internal or environment-wide failure occurs.

DatabaseException - the base class for all BDB exceptions.

nextDup

public V nextDup(LockMode lockMode)
          throws DatabaseException

Description copied from interface: EntityCursor

Moves the cursor to the next value with the same key (duplicate) and returns it, or returns null if no more values are present for the key at the current position.

Specified by:

nextDup in interface EntityCursor<V>

Parameters:

lockMode - the lock mode to use for this operation, or null to use LockMode.DEFAULT.

Returns:

the next value with the same key, or null if no more values are present for the key at the current position.

Throws:

OperationFailureException - if one of the Read Operation Failures occurs.

EnvironmentFailureException - if an unexpected, internal or environment-wide failure occurs.

DatabaseException - the base class for all BDB exceptions.

nextNoDup

public V nextNoDup()
            throws DatabaseException

Description copied from interface: EntityCursor

Moves the cursor to the next value with a different key and returns it, or returns null if there are no more unique keys in the cursor range. If the cursor is uninitialized, this method is equivalent to EntityCursor.first().

LockMode.DEFAULT is used implicitly.

Specified by:

nextNoDup in interface EntityCursor<V>

Returns:

the next value with a different key, or null if there are no more unique keys in the cursor range.

Throws:

OperationFailureException - if one of the Read Operation Failures occurs.

EnvironmentFailureException - if an unexpected, internal or environment-wide failure occurs.

DatabaseException - the base class for all BDB exceptions.

nextNoDup

public V nextNoDup(LockMode lockMode)
            throws DatabaseException

Description copied from interface: EntityCursor

Moves the cursor to the next value with a different key and returns it, or returns null if there are no more unique keys in the cursor range. If the cursor is uninitialized, this method is equivalent to EntityCursor.first().

Specified by:

nextNoDup in interface EntityCursor<V>

Parameters:

lockMode - the lock mode to use for this operation, or null to use LockMode.DEFAULT.

Returns:

the next value with a different key, or null if there are no more unique keys in the cursor range.

Throws:

OperationFailureException - if one of the Read Operation Failures occurs.

EnvironmentFailureException - if an unexpected, internal or environment-wide failure occurs.

DatabaseException - the base class for all BDB exceptions.

prev

public V prev()
       throws DatabaseException

Description copied from interface: EntityCursor

Moves the cursor to the previous value and returns it, or returns null if there are no preceding values in the cursor range. If the cursor is uninitialized, this method is equivalent to EntityCursor.last().

LockMode.DEFAULT is used implicitly.

Specified by:

prev in interface EntityCursor<V>

Returns:

the previous value, or null if there are no preceding values in the cursor range.

Throws:

OperationFailureException - if one of the Read Operation Failures occurs.

EnvironmentFailureException - if an unexpected, internal or environment-wide failure occurs.

DatabaseException - the base class for all BDB exceptions.

prev

public V prev(LockMode lockMode)
       throws DatabaseException

Description copied from interface: EntityCursor

Moves the cursor to the previous value and returns it, or returns null if there are no preceding values in the cursor range. If the cursor is uninitialized, this method is equivalent to EntityCursor.last().

Specified by:

prev in interface EntityCursor<V>

Parameters:

lockMode - the lock mode to use for this operation, or null to use LockMode.DEFAULT.

Returns:

the previous value, or null if there are no preceding values in the cursor range.

Throws:

OperationFailureException - if one of the Read Operation Failures occurs.

EnvironmentFailureException - if an unexpected, internal or environment-wide failure occurs.

DatabaseException - the base class for all BDB exceptions.

prevDup

public V prevDup()
          throws DatabaseException

Description copied from interface: EntityCursor

Moves the cursor to the previous value with the same key (duplicate) and returns it, or returns null if no preceding values are present for the key at the current position.

LockMode.DEFAULT is used implicitly.

Specified by:

prevDup in interface EntityCursor<V>

Returns:

the previous value with the same key, or null if no preceding values are present for the key at the current position.

Throws:

OperationFailureException - if one of the Read Operation Failures occurs.

EnvironmentFailureException - if an unexpected, internal or environment-wide failure occurs.

DatabaseException - the base class for all BDB exceptions.

prevDup

public V prevDup(LockMode lockMode)
          throws DatabaseException

Description copied from interface: EntityCursor

Moves the cursor to the previous value with the same key (duplicate) and returns it, or returns null if no preceding values are present for the key at the current position.

Specified by:

prevDup in interface EntityCursor<V>

Parameters:

lockMode - the lock mode to use for this operation, or null to use LockMode.DEFAULT.

Returns:

the previous value with the same key, or null if no preceding values are present for the key at the current position.

Throws:

OperationFailureException - if one of the Read Operation Failures occurs.

EnvironmentFailureException - if an unexpected, internal or environment-wide failure occurs.

DatabaseException - the base class for all BDB exceptions.

prevNoDup

public V prevNoDup()
            throws DatabaseException

Description copied from interface: EntityCursor

Moves the cursor to the preceding value with a different key and returns it, or returns null if there are no preceding unique keys in the cursor range. If the cursor is uninitialized, this method is equivalent to EntityCursor.last().

LockMode.DEFAULT is used implicitly.

Specified by:

prevNoDup in interface EntityCursor<V>

Returns:

the previous value with a different key, or null if there are no preceding unique keys in the cursor range.

Throws:

OperationFailureException - if one of the Read Operation Failures occurs.

EnvironmentFailureException - if an unexpected, internal or environment-wide failure occurs.

DatabaseException - the base class for all BDB exceptions.

prevNoDup

public V prevNoDup(LockMode lockMode)
            throws DatabaseException

Description copied from interface: EntityCursor

Moves the cursor to the preceding value with a different key and returns it, or returns null if there are no preceding unique keys in the cursor range. If the cursor is uninitialized, this method is equivalent to EntityCursor.last().

Specified by:

prevNoDup in interface EntityCursor<V>

Parameters:

lockMode - the lock mode to use for this operation, or null to use LockMode.DEFAULT.

Returns:

the previous value with a different key, or null if there are no preceding unique keys in the cursor range.

Throws:

OperationFailureException - if one of the Read Operation Failures occurs.

EnvironmentFailureException - if an unexpected, internal or environment-wide failure occurs.

DatabaseException - the base class for all BDB exceptions.

current

public V current()
          throws DatabaseException

Description copied from interface: EntityCursor

Returns the value at the cursor position, or null if the value at the cursor position has been deleted.

LockMode.DEFAULT is used implicitly.

Specified by:

current in interface EntityCursor<V>

Returns:

the value at the cursor position, or null if it has been deleted.

Throws:

OperationFailureException - if one of the Read Operation Failures occurs.

EnvironmentFailureException - if an unexpected, internal or environment-wide failure occurs.

DatabaseException - the base class for all BDB exceptions.

current

public V current(LockMode lockMode)
          throws DatabaseException

Description copied from interface: EntityCursor

Returns the value at the cursor position, or null if the value at the cursor position has been deleted.

Specified by:

current in interface EntityCursor<V>

Parameters:

lockMode - the lock mode to use for this operation, or null to use LockMode.DEFAULT.

Returns:

the value at the cursor position, or null if it has been deleted.

Throws:

OperationFailureException - if one of the Read Operation Failures occurs.

EnvironmentFailureException - if an unexpected, internal or environment-wide failure occurs.

DatabaseException - the base class for all BDB exceptions.

count

public int count()
          throws DatabaseException

Description copied from interface: EntityCursor

Returns the number of values (duplicates) for the key at the cursor position, or returns zero if all values for the key have been deleted. Returns one or zero if the underlying index has unique keys.

The cost of this method is directly proportional to the number of values.

LockMode.DEFAULT is used implicitly.

Specified by:

count in interface EntityCursor<V>

Returns:

the number of duplicates, or zero if all values for the current key have been deleted.

Throws:

OperationFailureException - if one of the Read Operation Failures occurs.

EnvironmentFailureException - if an unexpected, internal or environment-wide failure occurs.

DatabaseException - the base class for all BDB exceptions.

countEstimate

public long countEstimate()
                   throws DatabaseException

Description copied from interface: EntityCursor

Returns a rough estimate of the number of values (duplicates) for the key at the cursor position, or returns zero if all values for the key have been deleted. Returns one or zero if the underlying index has unique keys.

If the underlying index has non-unique keys, a quick estimate of the number of values is computed using information in the Btree. Because the Btree is unbalanced, in some cases the estimate may be off by a factor of two or more. The estimate is accurate when the number of records is less than the configured NodeMaxEntries.

The cost of this method is fixed, rather than being proportional to the number of values. Because its accuracy is variable, this method should normally be used when accuracy is not required, such as for query optimization, and a fixed cost operation is needed. For example, this method is used internally for determining the index processing order in an EntityJoin.

Specified by:

countEstimate in interface EntityCursor<V>

Returns:

an estimate of the count of the number of data items for the key to which the cursor refers.

Throws:

OperationFailureException - if one of the Read Operation Failures occurs.

EnvironmentFailureException - if an unexpected, internal or environment-wide failure occurs.

DatabaseException - the base class for all BDB exceptions.

iterator

public java.util.Iterator<V> iterator()

Description copied from interface: EntityCursor

Returns an iterator over the key range, starting with the value following the current position or at the first value if the cursor is uninitialized.

LockMode.DEFAULT is used implicitly.

Specified by:

iterator in interface EntityCursor<V>

Specified by:

iterator in interface ForwardCursor<V>

Specified by:

iterator in interface java.lang.Iterable<V>

Returns:

the iterator.

iterator

public java.util.Iterator<V> iterator(LockMode lockMode)

Description copied from interface: EntityCursor

Returns an iterator over the key range, starting with the value following the current position or at the first value if the cursor is uninitialized.

Specified by:

iterator in interface EntityCursor<V>

Specified by:

iterator in interface ForwardCursor<V>

Parameters:

lockMode - the lock mode to use for all operations performed using the iterator, or null to use LockMode.DEFAULT.

Returns:

the iterator.

update

public boolean update(V entity)
               throws DatabaseException

Description copied from interface: EntityCursor

Replaces the entity at the cursor position with the given entity.

Specified by:

update in interface EntityCursor<V>

Parameters:

entity - the entity to replace the entity at the current position.

Returns:

true if successful or false if the entity at the current position was previously deleted.

Throws:

OperationFailureException - if one of the Write Operation Failures occurs.

EnvironmentFailureException - if an unexpected, internal or environment-wide failure occurs.

DatabaseException - the base class for all BDB exceptions.

delete

public boolean delete()
               throws DatabaseException

Description copied from interface: EntityCursor

Deletes the entity at the cursor position.

Specified by:

delete in interface EntityCursor<V>

Returns:

true if successful or false if the entity at the current position has been deleted.

Throws:

OperationFailureException - if one of the Write Operation Failures occurs.

EnvironmentFailureException - if an unexpected, internal or environment-wide failure occurs.

DatabaseException - the base class for all BDB exceptions.

dup

public EntityCursor<V> dup()
                    throws DatabaseException

Description copied from interface: EntityCursor

Duplicates the cursor at the cursor position. The returned cursor will be initially positioned at the same position as this current cursor, and will inherit this cursor's Transaction and CursorConfig.

Specified by:

dup in interface EntityCursor<V>

Returns:

the duplicated cursor.

Throws:

DatabaseException - the base class for all BDB exceptions.

close

public void close()
           throws DatabaseException

Description copied from interface: EntityCursor

Closes the cursor.

Specified by:

close in interface EntityCursor<V>

Specified by:

close in interface ForwardCursor<V>

Specified by:

close in interface java.io.Closeable

Specified by:

close in interface java.lang.AutoCloseable

Throws:

DatabaseException - the base class for all BDB exceptions.

setCacheMode

public void setCacheMode(CacheMode cacheMode)

Description copied from interface: EntityCursor

Changes the CacheMode used for operations performed using this cursor. For a newly opened cursor, the default is CacheMode.DEFAULT.

Specified by:

setCacheMode in interface EntityCursor<V>

Parameters:

cacheMode - is the CacheMode to use for subsequent operations using this cursor.

See Also:

CacheMode

getCacheMode

public CacheMode getCacheMode()

Description copied from interface: EntityCursor

Returns the CacheMode used for operations performed using this cursor. For a newly opened cursor, the default is CacheMode.DEFAULT.

Specified by:

getCacheMode in interface EntityCursor<V>

Returns:

the CacheMode object used for operations performed with this cursor.

See Also:

CacheMode

checkInitialized

void checkInitialized()
                throws java.lang.IllegalStateException

Throws:

java.lang.IllegalStateException

returnValue

V returnValue(OperationStatus status)