com.odi.coll
Interface List

All Superinterfaces:

Collection, IPersistent

All Known Subinterfaces:

Array

public interface List

extends Collection

The List interface is an extension of the Collection interface. The methods of the List interface apply to collections whose elements are ordered, which means that the collection keeps track of a specific order of the elements, independent of the element values or contents. Lists permit duplicates.

ObjectStore begins with position 0 when it orders the elements in a list. So the first element has a position of 0, the second element has a position of 1, the third element has a position of 2, and so on.

You can use a cursor to iterate over the elements in a list. A cursor becomes "null" if it is positioned past the last element, or before the first element. A cursor becomes "invalid" if the element to which it points is deleted. A cursor cannot be both null and invalid.

See Also:

Collection, Array, ListCursor

Fields inherited from interface com.odi.coll.Collection

R5_MAINTAIN_CURSORS, SIGNAL_DUPLICATES

Method Summary

void	insertAfter(java.lang.Object o, Cursor c) Inserts the specified object in the list just after the current position of the cursor.
void	insertAfter(java.lang.Object o, int position) Inserts the object just after the specified position in the list.
void	insertBefore(java.lang.Object o, Cursor c) Inserts the specified object in the list just before the current position of the cursor.
void	insertBefore(java.lang.Object o, int position) Inserts the object just before the specified position in the list.
void	insertFirst(java.lang.Object o) Inserts an element at the beginning of the collection.
void	insertLast(java.lang.Object o) Inserts an element at the end of the collection.
ListCursor	newListCursor(int flags) Creates a new list cursor that is associated with this list and that has the specified flags.
boolean	orderedEqual(List l) Determines whether or not two lists have exactly the same elements in the same order.
void	removeAt(Cursor c) Removes the object in the collection that the cursor is positioned at.
void	removeAt(int position) Removes the object at the specified position.
java.lang.Object	removeFirst() Removes and returns the first element in the list.
java.lang.Object	removeLast() Removes and returns the last element in the list.
void	replaceAt(java.lang.Object o, Cursor c) Replaces the object in the collection that the cursor is positioned at with the specified object.
void	replaceAt(java.lang.Object o, int position) Inserts the specified object at the specified position in the list.
java.lang.Object	retrieve(int position) Returns the element at the specified position in the list.
java.lang.Object	retrieveFirst() Returns the first element in the list.
java.lang.Object	retrieveLast() Returns the last element in the list.

Methods inherited from interface com.odi.coll.Collection

addIndex, addIndex, addIndex, cardinality, cardinalityEstimate, cardinalityIsMaintained, clear, contains, count, differenceWith, dropIndex, elements, empty, equals, exists, exists, getBehavior, hasIndex, insert, intersectionWith, newCursor, only, pick, properSubset, query, query, query, query, queryPick, queryPick, remove, retrieve, set, subset, unionWith, updateCardinality

Methods inherited from interface com.odi.IPersistent

clearContents, flushContents, initializeContents, ODIgetRef, ODIgetState, ODIsetRef, ODIsetState

Method Detail

insertFirst

public void insertFirst(java.lang.Object o)

Inserts an element at the beginning of the collection. This makes the inserted element the first element in the list.

Parameters:

o - The element to insert.

Throws:

java.lang.IllegalArgumentException - If the object is null and ALLOW_NULLS is not specified for the collection.

ModifyTransientCollectionException - If the collection is transient.

ObjectNotExportedException - If the collection and the object being inserted are in different segments and the object is not exported.

ObjectNotPersistenceCapableException - If the object is not persistence-capable.

insertLast

public void insertLast(java.lang.Object o)

Inserts an element at the end of the collection. This makes the inserted element the last element in the list.

Parameters:

o - The element to insert.

Throws:

java.lang.IllegalArgumentException - If the object is null and ALLOW_NULLS is not specified for the collection.

ModifyTransientCollectionException - If the collection is transient.

ObjectNotExportedException - If the collection and the object being inserted are in different segments and the object is not exported.

ObjectNotPersistenceCapableException - If the object is not persistence-capable.

removeFirst

public java.lang.Object removeFirst()

Removes and returns the first element in the list. If the element is null, ObjectStore returns it just as it would return any other element.

Returns:

The element that was first in the list.

Throws:

ModifyTransientCollectionException - If the collection is transient.

java.util.NoSuchElementException - If the list is empty.

removeLast

public java.lang.Object removeLast()

Removes and returns the last element in the list. If the element is null, ObjectStore returns it just as it would return any other element.

Returns:

The element that was last in the list.

Throws:

ModifyTransientCollectionException - If the collection is transient.

java.util.NoSuchElementException - If the list is empty.

retrieveFirst

public java.lang.Object retrieveFirst()

Returns the first element in the list. If the element is null, ObjectStore returns it just as it would return any other element.

This method does not modify the list.

Returns:

The element that is first in the list.

Throws:

java.util.NoSuchElementException - If the list is empty.

retrieveLast

public java.lang.Object retrieveLast()

Returns the last element in the list. If the element is null, ObjectStore returns it just as it would return any other element.

This method does not modify the list.

Returns:

The element that is last in the list.

Throws:

java.util.NoSuchElementException - If the list is empty.

retrieve

public java.lang.Object retrieve(int position)

Returns the element at the specified position in the list. A position of zero returns the first item in the list. A position of, for example, 5, returns the element at position 5, which is the sixth element in the list. This method does not modify the list.

Parameters:

position - The position in the list (zero-based).

Returns:

The element at the specified position.

Throws:

java.lang.IndexOutOfBoundsException - If the position is negative or greater than the number of elements in the list.

insertBefore

public void insertBefore(java.lang.Object o,
                         int position)

Inserts the object just before the specified position in the list. For example, specification of a position of 4 puts this object after the element at position 3 and before the element at position 4. After this method is executed, the position of the just-added object is 4. A position of 0 inserts this object as the first element in the list.

Parameters:

object - The object to insert in the list.

position - The position before which to insert the new object.

Throws:

java.lang.IllegalArgumentException - If the object is null and the collection behavior does not specify ALLOW_NULLS.

java.lang.IndexOutOfBoundsException - If the position is negative or greater than the number of elements in the list, or if the list is empty.

ModifyTransientCollectionException - If the collection is transient.

ObjectNotExportedException - If the collection and the object being inserted are in different segments and the object is not exported.

ObjectNotPersistenceCapableException - If the object is not persistence-capable.

insertAfter

public void insertAfter(java.lang.Object o,
                        int position)

Inserts the object just after the specified position in the list. For example, specification of a position of 2 puts this object after the element at position 2 and before the element at position 3. After this method is executed, the position of the just-added element is 3. A position of 0 makes this object the second object in the list; it has a position of 1.

Parameters:

object - The object to insert in the list.

position - The position after which to insert the object.

Throws:

java.lang.IllegalArgumentException - If the object is null and the collection behavior does not specify ALLOW_NULLS.

java.lang.IndexOutOfBoundsException - If the position is negative or greater than the number of elements in the list, or if the list is empty.

ModifyTransientCollectionException - If the collection is transient.

ObjectNotExportedException - If the collection and the object being inserted are in different segments and the object is not exported.

ObjectNotPersistenceCapableException - If the object is not persistence-capable.

removeAt

public void removeAt(int position)

Removes the object at the specified position.

Parameters:

position - The position of the object that you want to remove.

Throws:

java.lang.IndexOutOfBoundsException - If the position is negative or greater than the number of elements in the list, or if the list is empty.

ModifyTransientCollectionException - If the collection is transient.

replaceAt

public void replaceAt(java.lang.Object o,
                      int position)

Inserts the specified object at the specified position in the list. If an object exists at the specified position, it is replaced with the specified object.

Parameters:

o - The object to insert.

position - The position at which to insert the specified object.

Throws:

java.lang.IllegalArgumentException - If the object is null and the collection behavior does not specify ALLOW_NULLS.

java.lang.IndexOutOfBoundsException - If the position is negative or greater than the number of elements in the list, or if the list is empty.

ModifyTransientCollectionException - If the collection is transient.

ObjectNotExportedException - If the collection and the object being inserted are in different segments and the object is not exported.

ObjectNotPersistenceCapableException - If the object is not persistence-capable.

insertBefore

public void insertBefore(java.lang.Object o,
                         Cursor c)

Inserts the specified object in the list just before the current position of the cursor.

Parameters:

object - The object to insert into the list.

cursor - The position before which to insert the specified object.

Throws:

java.lang.IllegalArgumentException - If the object is null and the collection behavior does not specify ALLOW_NULLS.

InvalidCursorException - If the cursor is invalid.

ModifyTransientCollectionException - If the collection is transient.

NullCursorException - If the cursor is null.

ObjectNotExportedException - If the collection and the object being inserted are in different segments and the object is not exported.

ObjectNotPersistenceCapableException - If the object is not persistence-capable.

insertAfter

public void insertAfter(java.lang.Object o,
                        Cursor c)

Inserts the specified object in the list just after the current position of the cursor.

Parameters:

object - The object to insert into the list.

cursor - The position after which to insert the specified object.

Throws:

java.lang.IllegalArgumentException - If the object is null and the collection behavior does not specify ALLOW_NULLS.

InvalidCursorException - If the cursor is invalid.

ModifyTransientCollectionException - If the collection is transient.

NullCursorException - If the cursor is null.

ObjectNotExportedException - If the collection and the object being inserted are in different segments and the object is not exported.

ObjectNotPersistenceCapableException - If the object is not persistence-capable.

removeAt

public void removeAt(Cursor c)

Removes the object in the collection that the cursor is positioned at. After execution of this method, the cursor is invalid.

Parameters:

cursor - The position at which to remove the object.

Throws:

java.lang.IndexOutOfBoundsException - If the collection is empty.

InvalidCursorException - If the cursor is invalid.

ModifyTransientCollectionException - If the collection is transient.

NullCursorException - If the cursor is null.

replaceAt

public void replaceAt(java.lang.Object o,
                      Cursor c)

Replaces the object in the collection that the cursor is positioned at with the specified object.

Parameters:

object - The object to insert into the list.

cursor - The position at which to replace the object.

Throws:

java.lang.IllegalArgumentException - If the object is null and the collection behavior does not specify ALLOW_NULLS.

java.lang.IndexOutOfBoundsException - If the collection is empty.

InvalidCursorException - If the cursor is invalid.

ModifyTransientCollectionException - If the collection is transient.

NullCursorException - If the cursor is null.

ObjectNotExportedException - If the collection and the object being inserted are in different segments and the object is not exported.

ObjectNotPersistenceCapableException - If the object is not persistence-capable.

orderedEqual

public boolean orderedEqual(List l)

Determines whether or not two lists have exactly the same elements in the same order. Equality of elements means that the elements are the same Java object as determined by ==, not that they are equal Java objects.

Parameters:

l - The list to compare with.

Returns:

True if the lists have the same elements in the same order.

newListCursor

public ListCursor newListCursor(int flags)

Creates a new list cursor that is associated with this list and that has the specified flags. The meaningful flags are defined by the constants inherited from the Collection interface. A transaction must be in progress. You should destroy the cursor before you commit the transaction.

When you create a safe list cursor, ObjectStore modifies the database. Consequently, the database that contains the list must be open for update, an update transaction must be in progress, and you must have permission to modify the database.

Parameters:

flags - The flag bits describing this cursor's properties.

Throws:

UpdateReadOnlyException - If you try to create a safe list cursor and the database is not open for update or the transaction is not an update transaction.