When a stored collection is created it is based on either a Database or a SecondaryDatabase. When a database is used, the primary key of the database is used as the collection key. When a secondary database is used, the index key is used as the collection key. Indexed collections can be used for reading elements and removing elements but not for adding or updating elements.
The use of stored collections is constrained in certain respects as described below. Most of these restrictions have to do with List interfaces; for Map interfaces, most all access modes are fully supported since the Berkeley DB model is map-like.
SortedSet and SortedMap interfaces may only be used if keys are ordered. This means ordered keys are required for creating a StoredSortedEntrySet, StoredSortedKeySet, StoredSortedMap, or StoredSortedValueSet.
All iterators for stored collections implement the ListIterator interface as well as the Iterator interface. ListIterator.hasPrevious() and ListIterator.previous() work in all cases. However, the following ListIterator method behavior is dependent on the access method.
ListIterator.nextIndex() and ListIterator.previousIndex() only work when record number keys are used, and throw UnsupportedOperationException otherwise.
ListIterator.add() inserts before the current position and renumbers following keys if the RECNO-RENUMBER access method is used.
For all access methods other than RECNO-RENUMBER:
ListIterator.add() throws UnsupportedOperationException if duplicates are not allowed.
ListIterator.add() inserts a duplicate before the current position if duplicates are unsorted.
ListIterator.add() inserts a duplicate in sorted order if duplicates are sorted.
ListIterator.set() throws UnsupportedOperationException if sorted duplicates are configured, since updating with sorted duplicates would change the iterator position.
Map.Entry.setValue() throws UnsupportedOperationException if duplicates are sorted.
Only the access methods that use a record number key may be used
with a
List
List
view.
To create a stored List that supports the
List.add()
List.add()
method, only the RECNO-RENUMBER access method may be used.
For List access methods that do not support
List.add()
List.add()
(RECNO, QUEUE, and BTREE-RECNUM):
List.add()
List.add()
and
ListIterator.add()
ListIterator.add()
always throw
UnsupportedOperationException .
List.remove()
List.remove()
and
ListIterator.remove()
ListIterator.remove()
do not cause list indices to be renumbered. However, iterators will skip
the removed values.
For these access methods, stored Lists are most useful as read-only collections where indices are not required to be sequential.
When duplicates are allowed the Collection interfaces are modified in several ways as described in the next section.
Stored collections have the following differences with the standard Java collection interfaces. Some of these are interface contract violations.
The Java collections interface does not support duplicate keys (multi-maps or multi-sets). When the access method allows (m ListIterator.previousIndex() only work when record number keys are used, and throw UnsupportedOperationException otherwise.
ListIterator.add() inserts before the current position and renumbers following keys if the RECNO-RENUMBER access method is used.
For all access methods other than RECNO-RENUMBER:
ListIterator.add() throws UnsupportedOperationException if duplicates are not allowed.
ListIterator.add() inserts a duplicate before the current position if duplicates are unsorted.
ListIterator.add() inserts a duplicate in sorted order if duplicates are sorted.
ListIterator.set() throws UnsupportedOperationException if sorted duplicates are configured, since updating with sorted duplicates would change the iterator position.
Map.Entry.setValue() throws UnsupportedOperationException if duplicates are sorted.
Only the access methods that use a record number key may be used
with a
List
List
view.
To create a stored List that supports the
List.add()
List.add()
method, only the RECNO-RENUMBER access method may be used.
For List access methods that do not support
List.add()
List.add()
(RECNO, QUEUE, and BTREE-RECNUM):
List.add()
List.add()
and
ListIterator.add()
ListIterator.add()
always throw
UnsupportedOperationException .
List.remove()
List.remove()
and
ListIterator.remove()
ListIterator.remove()
do not cause list indices to be renumbered. However, iterators will skip
the removed values.
For these access methods, stored Lists are most useful as read-only collections where indices are not required to be sequential.
When duplicates are allowed the Collection interfaces are modified in several ways as described in the next section.
Stored collections have the following differences with the standard Java collection interfaces. Some of these are interface contract violations.
The Java collections interface does not support duplicate keys (multi-maps or multi-sets). When the access method allows (m ListIterator.previousIndex() only work when record number keys are used, and throw UnsupportedOperationException otherwise.
ListIterator.add() inserts before the current position and renumbers following keys if the RECNO-RENUMBER access method is used.
For all access methods other than RECNO-RENUMBER:
ListIterator.add() throws UnsupportedOperationException if duplicates are not allowed.
ListIterator.add() inserts a duplicate before the current position if duplicates are unsorted.
ListIterator.add() inserts a duplicate in sorted order if duplicates are sorted.
ListIterator.set() throws UnsupportedOperationException if sorted duplicates are configured, since updating with sorted duplicates would change the iterator position.
Map.Entry.setValue() throws UnsupportedOperationException if duplicates are sorted.
Only the access methods that use a record number key may be used
with a
List
List
view.
To create a stored List that supports the
List.add()
List.add()
method, only the RECNO-RENUMBER access method may be used.
For List access methods that do not support
List.add()
List.add()
(RECNO, QUEUE, and BTREE-RECNUM):
List.add()
List.add()
and
ListIterator.add()
ListIterator.add()
always throw
UnsupportedOperationException .
List.remove()
List.remove()
and
ListIterator.remove()
ListIterator.remove()
do not cause list indices to be renumbered. However, iterators will skip
the removed values.
For these access methods, stored Lists are most useful as read-only collections where indices are not required to be sequential.
When duplicates are allowed the Collection interfaces are modified in several ways as described in the next section.
Stored collections have the following differences with the standard Java collection interfaces. Some of these are interface contract violations.
The Java collections interface does not support duplicate keys (multi-maps or multi-sets). When the access method allows (m ListIterator.previousIndex() only work when record number keys are used, and throw UnsupportedOperationException otherwise.
ListIterator.add() inserts before the current position and renumbers following keys if the RECNO-RENUMBER access method is used.
For all access methods other than RECNO-RENUMBER:
ListIterator.add() throws UnsupportedOperationException if duplicates are not allowed.
ListIterator.add() inserts a duplicate before the current position if duplicates are unsorted.
ListIterator.add() inserts a duplicate in sorted order if duplicates are sorted.
ListIterator.set() throws UnsupportedOperationException if sorted duplicates are configured, since updating with sorted duplicates would change the iterator position.
Map.Entry.setValue() throws UnsupportedOperationException if duplicates are sorted.
Only the access methods that use a record number key may be used
with a
List
List
view.
To create a stored List that supports the
List.add()
List.add()
method, only the RECNO-RENUMBER access method may be used.
For List access methods that do not support
List.add()
List.add()
(RECNO, QUEUE, and BTREE-RECNUM):
List.add()
List.add()
and
ListIterator.add()
ListIterator.add()
always throw
UnsupportedOperationException .
List.remove()
List.remove()
and
ListIterator.remove()
ListIterator.remove()
do not cause list indices to be renumbered. However, iterators will skip
the removed values.
For these access methods, stored Lists are most useful as read-only collections where indices are not required to be sequential.
When duplicates are allowed the Collection interfaces are modified in several ways as described in the next section.
Stored collections have the following differences with the standard Java collection interfaces. Some of these are interface contract violations.
The Java collections interface does not support duplicate keys (multi-maps or multi-sets). When the access method allows (m