com.sleepycat.collections

Class StoredCollection<E>

java.lang.Object

com.sleepycat.collections.StoredContainer

com.sleepycat.collections.StoredCollection<E>

All Implemented Interfaces:

java.lang.Cloneable, java.lang.Iterable<E>, java.util.Collection<E>

Direct Known Subclasses:

StoredEntrySet, StoredKeySet, StoredList, StoredValueSet

public abstract class StoredCollection<E>
extends StoredContainer
implements java.util.Collection<E>

A abstract base class for all stored collections. This class, and its base class StoredContainer, provide implementations of most methods in the Collection interface. Other methods, such as add(java.lang.Object, java.lang.Object) and Collection.remove(java.lang.Object), are provided by concrete classes that extend this class.

In addition, this class provides the following methods for stored collections only. Note that the use of these methods is not compatible with the standard Java collections interface.

• getIteratorBlockSize()
• setIteratorBlockSize(int)
• storedIterator()
• storedIterator(boolean)
• join(com.sleepycat.collections.StoredContainer[], java.lang.Object[], com.sleepycat.je.JoinConfig)
• toList()

Author:

Mark Hayes

Field Summary

Fields

Modifier and Type	Field and Description
static int	DEFAULT_ITERATOR_BLOCK_SIZE The default number of records read at one time by iterators.

Fields inherited from class com.sleepycat.collections.StoredContainer

view

Constructor Summary

Constructors

Constructor and Description
StoredCollection(DataView view)

Method Summary

Methods

Modifier and Type	Method and Description
(package private) boolean	add(java.lang.Object key, java.lang.Object value)
boolean	addAll(java.util.Collection<? extends E> coll) Adds all of the elements in the specified collection to this collection (optional operation).
(package private) BlockIterator	blockIterator()
(package private) void	checkIterAddAllowed()
boolean	containsAll(java.util.Collection<?> coll) Returns true if this collection contains all of the elements in the specified collection.
boolean	equals(java.lang.Object other) Compares the specified object with this collection for equality.
(package private) E	getFirstOrLast(boolean doGetFirst)
(package private) int	getIndexOffset()
int	getIteratorBlockSize() Returns the number of records read at one time by iterators returned by the iterator() method.
int	hashCode()
(package private) abstract boolean	hasValues()
(package private) boolean	iterateDuplicates()
java.util.Iterator<E>	iterator() Returns an iterator over the elements in this collection.
StoredIterator<E>	iterator(boolean writeAllowed) Deprecated. Please use storedIterator() or storedIterator(boolean) instead. Because the iterator returned must be closed, the method name iterator is confusing since standard Java iterators do not need to be closed.
StoredIterator<E>	join(StoredContainer[] indices, java.lang.Object[] indexKeys, JoinConfig joinConfig) Returns an iterator representing an equality join of the indices and index key values specified.
(package private) abstract E	makeIteratorData(BaseIterator iterator, DatabaseEntry keyEntry, DatabaseEntry priKeyEntry, DatabaseEntry valueEntry)
(package private) E	makeIteratorData(BaseIterator iterator, DataCursor cursor)
boolean	removeAll(java.util.Collection<?> coll) Removes all this collection's elements that are also contained in the specified collection (optional operation).
boolean	retainAll(java.util.Collection<?> coll) Retains only the elements in this collection that are contained in the specified collection (optional operation).
void	setIteratorBlockSize(int blockSize) Changes the number of records read at one time by iterators returned by the iterator() method.
int	size() Returns a non-transactional count of the records in the collection or map.
StoredIterator<E>	storedIterator() Returns an iterator over the elements in this collection.
StoredIterator<E>	storedIterator(boolean writeAllowed) Returns a read or read-write iterator over the elements in this collection.
java.lang.Object[]	toArray() Returns an array of all the elements in this collection.
<T> T[]	toArray(T[] a) Returns an array of all the elements in this collection whose runtime type is that of the specified array.
java.util.List<E>	toList() Returns a copy of this collection as an ArrayList.
java.lang.String	toString() Converts the collection to a string representation for debugging.

Methods inherited from class com.sleepycat.collections.StoredContainer

areDuplicatesAllowed, areDuplicatesOrdered, areKeyRangesAllowed, areKeysRenumbered, beginAutoCommit, clear, closeCursor, commitAutoCommit, configuredClone, containsKey, containsValue, convertException, getCursorConfig, getValue, handleException, initAfterClone, isDirtyRead, isDirtyReadAllowed, isEmpty, isOrdered, isSecondary, isTransactional, isWriteAllowed, putKeyValue, removeKey, removeValue, storedOrExternalIterator

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Methods inherited from interface java.util.Collection

add, clear, contains, isEmpty, remove

Field Detail

DEFAULT_ITERATOR_BLOCK_SIZE

public static final int DEFAULT_ITERATOR_BLOCK_SIZE

The default number of records read at one time by iterators.

See Also:

setIteratorBlockSize(int), Constant Field Values

Constructor Detail

StoredCollection

StoredCollection(DataView view)

Method Detail

getIteratorBlockSize

public int getIteratorBlockSize()

Returns the number of records read at one time by iterators returned by the iterator() method. By default this value is DEFAULT_ITERATOR_BLOCK_SIZE.

setIteratorBlockSize

public void setIteratorBlockSize(int blockSize)

Changes the number of records read at one time by iterators returned by the iterator() method. By default this value is DEFAULT_ITERATOR_BLOCK_SIZE.

Throws:

java.lang.IllegalArgumentException - if the blockSize is less than two.

add

final boolean add(java.lang.Object key,
          java.lang.Object value)

blockIterator

BlockIterator blockIterator()

iterator

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

Returns an iterator over the elements in this collection. The iterator will be read-only if the collection is read-only. This method conforms to the Collection.iterator() interface.

The iterator returned by this method does not keep a database cursor open and therefore it does not need to be closed. It reads blocks of records as needed, opening and closing a cursor to read each block of records. The number of records per block is 10 by default and can be changed with setIteratorBlockSize(int).

Because this iterator does not keep a cursor open, if it is used without transactions, the iterator does not have cursor stability characteristics. In other words, the record at the current iterator position can be changed or deleted by another thread. To prevent this from happening, call this method within a transaction or use the storedIterator() method instead.

Specified by:

iterator in interface java.lang.Iterable<E>

Specified by:

iterator in interface java.util.Collection<E>

Returns:

a standard Iterator for this collection.

See Also:

StoredContainer.isWriteAllowed()

storedIterator

public StoredIterator<E> storedIterator()

Returns an iterator over the elements in this collection. The iterator will be read-only if the collection is read-only. This method does not exist in the standard Collection interface.

If Iterator.set or Iterator.remove will be called and the underlying Database is transactional, then a transaction must be active when calling this method and must remain active while using the iterator.

Warning: The iterator returned must be explicitly closed using StoredIterator.close() or StoredIterator.close(java.util.Iterator) to release the underlying database cursor resources.

Returns:

a StoredIterator for this collection.

See Also:

StoredContainer.isWriteAllowed()

storedIterator

public StoredIterator<E> storedIterator(boolean writeAllowed)

Returns a read or read-write iterator over the elements in this collection. This method does not exist in the standard Collection interface.

If Iterator.set or Iterator.remove will be called and the underlying Database is transactional, then a transaction must be active when calling this method and must remain active while using the iterator.

Warning: The iterator returned must be explicitly closed using StoredIterator.close() or StoredIterator.close(java.util.Iterator) to release the underlying database cursor resources.

Parameters:

writeAllowed - is true to open a read-write iterator or false to open a read-only iterator. If the collection is read-only the iterator will always be read-only.

Returns:

a StoredIterator for this collection.

Throws:

java.lang.IllegalStateException - if writeAllowed is true but the collection is read-only.

RuntimeExceptionWrapper - if a DatabaseException is thrown.

See Also:

StoredContainer.isWriteAllowed()

iterator

public StoredIterator<E> iterator(boolean writeAllowed)

Deprecated. Please use storedIterator() or storedIterator(boolean) instead. Because the iterator returned must be closed, the method name iterator is confusing since standard Java iterators do not need to be closed.

toArray

public java.lang.Object[] toArray()

Returns an array of all the elements in this collection. This method conforms to the Collection.toArray() interface.

Specified by:

toArray in interface java.util.Collection<E>

Throws:

RuntimeExceptionWrapper - if a DatabaseException is thrown.

toArray

public <T> T[] toArray(T[] a)

Returns an array of all the elements in this collection whose runtime type is that of the specified array. This method conforms to the Collection.toArray(Object[]) interface.

Specified by:

toArray in interface java.util.Collection<E>

Throws:

RuntimeExceptionWrapper - if a DatabaseException is thrown.

containsAll

public boolean containsAll(java.util.Collection<?> coll)

Returns true if this collection contains all of the elements in the specified collection. This method conforms to the Collection.containsAll(java.util.Collection<?>) interface.

Specified by:

containsAll in interface java.util.Collection<E>

Throws:

RuntimeExceptionWrapper - if a DatabaseException is thrown.

addAll

public boolean addAll(java.util.Collection<? extends E> coll)

Adds all of the elements in the specified collection to this collection (optional operation). This method calls the Collection.add(Object) method of the concrete collection class, which may or may not be supported. This method conforms to the Collection.addAll(java.util.Collection<? extends E>) interface.

Specified by:

addAll in interface java.util.Collection<E>

Throws:

java.lang.UnsupportedOperationException - if the collection is read-only, or if the collection is indexed, or if the add method is not supported by the concrete collection.

RuntimeExceptionWrapper - if a DatabaseException is thrown.

removeAll

public boolean removeAll(java.util.Collection<?> coll)

Removes all this collection's elements that are also contained in the specified collection (optional operation). This method conforms to the Collection.removeAll(java.util.Collection<?>) interface.

Specified by:

removeAll in interface java.util.Collection<E>

Throws:

java.lang.UnsupportedOperationException - if the collection is read-only.

RuntimeExceptionWrapper - if a DatabaseException is thrown.

retainAll

public boolean retainAll(java.util.Collection<?> coll)

Retains only the elements in this collection that are contained in the specified collection (optional operation). This method conforms to the Collection.removeAll(java.util.Collection<?>) interface.

Specified by:

retainAll in interface java.util.Collection<E>

Throws:

java.lang.UnsupportedOperationException - if the collection is read-only.

RuntimeExceptionWrapper - if a DatabaseException is thrown.

equals

public boolean equals(java.lang.Object other)

Compares the specified object with this collection for equality. A value comparison is performed by this method and the stored values are compared rather than calling the equals() method of each element. This method conforms to the Collection.equals(java.lang.Object) interface.

Specified by:

equals in interface java.util.Collection<E>

Overrides:

equals in class java.lang.Object

Throws:

RuntimeExceptionWrapper - if a DatabaseException is thrown.

hashCode

public int hashCode()

Specified by:

hashCode in interface java.util.Collection<E>

Overrides:

hashCode in class java.lang.Object

toList

public java.util.List<E> toList()

Returns a copy of this collection as an ArrayList. This is the same as toArray() but returns a collection instead of an array.

Returns:

an ArrayList containing a copy of all elements in this collection.

Throws:

RuntimeExceptionWrapper - if a DatabaseException is thrown.

toString

public java.lang.String toString()

Converts the collection to a string representation for debugging. WARNING: The returned string may be very large.

Overrides:

toString in class java.lang.Object

Returns:

the string representation.

Throws:

RuntimeExceptionWrapper - if a DatabaseException is thrown.

size

public int size()

Description copied from class: StoredContainer

Returns a non-transactional count of the records in the collection or map. This method conforms to the Collection.size() and Map.size() interfaces.

This operation is faster than obtaining a count by scanning the collection manually, and will not perturb the current contents of the cache. However, the count is not guaranteed to be accurate if there are concurrent updates.

Specified by:

size in interface java.util.Collection<E>

Specified by:

size in class StoredContainer

join

public StoredIterator<E> join(StoredContainer[] indices,
                     java.lang.Object[] indexKeys,
                     JoinConfig joinConfig)

Returns an iterator representing an equality join of the indices and index key values specified. This method does not exist in the standard Collection interface.

Warning: The iterator returned must be explicitly closed using StoredIterator.close() or StoredIterator.close(java.util.Iterator) to release the underlying database cursor resources.

The returned iterator supports only the two methods: hasNext() and next(). All other methods will throw UnsupportedOperationException.

Parameters:

indices - is an array of indices with elements corresponding to those in the indexKeys array.

indexKeys - is an array of index key values identifying the elements to be selected.

joinConfig - is the join configuration, or null to use the default configuration.

Returns:

an iterator over the elements in this collection that match all specified index key values.

Throws:

java.lang.IllegalArgumentException - if this collection is indexed or if a given index does not have the same store as this collection.

RuntimeExceptionWrapper - if a DatabaseException is thrown.

getFirstOrLast

final E getFirstOrLast(boolean doGetFirst)

makeIteratorData

E makeIteratorData(BaseIterator iterator,
                 DataCursor cursor)

makeIteratorData

abstract E makeIteratorData(BaseIterator iterator,
                 DatabaseEntry keyEntry,
                 DatabaseEntry priKeyEntry,
                 DatabaseEntry valueEntry)

hasValues

abstract boolean hasValues()

iterateDuplicates

boolean iterateDuplicates()

checkIterAddAllowed

void checkIterAddAllowed()
                   throws java.lang.UnsupportedOperationException

Throws:

java.lang.UnsupportedOperationException

getIndexOffset

int getIndexOffset()