Interface COM.odi.coll.List

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

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

insertFirst

  public abstract void insertFirst(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: IllegalArgumentException: If the object is null and ALLOW_NULLS is not specified for the collection.
Throws: ModifyTransientCollectionException: If the collection is transient.
Throws: ObjectNotExportedException: If the collection and the object being inserted are in different segments and the object is not exported.
Throws: ObjectNotPersistenceCapableException: If the object is not persistence-capable.

insertLast

  public abstract void insertLast(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: IllegalArgumentException: If the object is null and ALLOW_NULLS is not specified for the collection.
Throws: ModifyTransientCollectionException: If the collection is transient.
Throws: ObjectNotExportedException: If the collection and the object being inserted are in different segments and the object is not exported.
Throws: ObjectNotPersistenceCapableException: If the object is not persistence-capable.

removeFirst

  public abstract 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.
Throws: NoSuchElementException: If the list is empty.

removeLast

  public abstract 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.
Throws: NoSuchElementException: If the list is empty.

retrieveFirst

  public abstract 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: NoSuchElementException: If the list is empty.

retrieveLast

  public abstract 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: NoSuchElementException: If the list is empty.

retrieve

  public abstract 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: IndexOutOfBoundsException: If the position is negative or greater than the number of elements in the list.

insertBefore

  public abstract void insertBefore(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: IllegalArgumentException: If the object is null and the collection behavior does not specify ALLOW_NULLS.
Throws: IndexOutOfBoundsException: If the position is negative or greater than the number of elements in the list, or if the list is empty.
Throws: ModifyTransientCollectionException: If the collection is transient.
Throws: ObjectNotExportedException: If the collection and the object being inserted are in different segments and the object is not exported.
Throws: ObjectNotPersistenceCapableException: If the object is not persistence-capable.

insertAfter

  public abstract void insertAfter(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: IllegalArgumentException: If the object is null and the collection behavior does not specify ALLOW_NULLS.
Throws: IndexOutOfBoundsException: If the position is negative or greater than the number of elements in the list, or if the list is empty.
Throws: ModifyTransientCollectionException: If the collection is transient.
Throws: ObjectNotExportedException: If the collection and the object being inserted are in different segments and the object is not exported.
Throws: ObjectNotPersistenceCapableException: If the object is not persistence-capable.

removeAt

  public abstract void removeAt(int position)

Removes the object at the specified position.

Parameters:: position - The position of the object that you want to remove.
Throws: IndexOutOfBoundsException: If the position is negative or greater than the number of elements in the list, or if the list is empty.
Throws: ModifyTransientCollectionException: If the collection is transient.

replaceAt

  public abstract void replaceAt(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: IllegalArgumentException: If the object is null and the collection behavior does not specify ALLOW_NULLS.
Throws: IndexOutOfBoundsException: If the position is negative or greater than the number of elements in the list, or if the list is empty.
Throws: ModifyTransientCollectionException: If the collection is transient.
Throws: ObjectNotExportedException: If the collection and the object being inserted are in different segments and the object is not exported.
Throws: ObjectNotPersistenceCapableException: If the object is not persistence-capable.

insertBefore

  public abstract void insertBefore(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: IllegalArgumentException: If the object is null and the collection behavior does not specify ALLOW_NULLS.
Throws: InvalidCursorException: If the cursor is invalid.
Throws: ModifyTransientCollectionException: If the collection is transient.
Throws: NullCursorException: If the cursor is null.
Throws: ObjectNotExportedException: If the collection and the object being inserted are in different segments and the object is not exported.
Throws: ObjectNotPersistenceCapableException: If the object is not persistence-capable.

insertAfter

  public abstract void insertAfter(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: IllegalArgumentException: If the object is null and the collection behavior does not specify ALLOW_NULLS.
Throws: InvalidCursorException: If the cursor is invalid.
Throws: ModifyTransientCollectionException: If the collection is transient.
Throws: NullCursorException: If the cursor is null.
Throws: ObjectNotExportedException: If the collection and the object being inserted are in different segments and the object is not exported.
Throws: ObjectNotPersistenceCapableException: If the object is not persistence-capable.

removeAt

  public abstract 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: IndexOutOfBoundsException: If the collection is empty.
Throws: InvalidCursorException: If the cursor is invalid.
Throws: ModifyTransientCollectionException: If the collection is transient.
Throws: NullCursorException: If the cursor is null.

replaceAt

  public abstract void replaceAt(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: IllegalArgumentException: If the object is null and the collection behavior does not specify ALLOW_NULLS.
Throws: IndexOutOfBoundsException: If the collection is empty.
Throws: InvalidCursorException: If the cursor is invalid.
Throws: ModifyTransientCollectionException: If the collection is transient.
Throws: NullCursorException: If the cursor is null.
Throws: ObjectNotExportedException: If the collection and the object being inserted are in different segments and the object is not exported.
Throws: ObjectNotPersistenceCapableException: If the object is not persistence-capable.

orderedEqual

  public abstract 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 abstract 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.