org.ozoneDB.collections
Class BaseListImpl

java.lang.Object
  extended byorg.ozoneDB.OzoneObject
      extended byorg.ozoneDB.collections.AbstractOzoneCollection
          extended byorg.ozoneDB.collections.BaseListImpl
All Implemented Interfaces:
BaseList, java.util.Collection, java.util.List, OzoneCollection, org.ozoneDB.OzoneCompatible, org.ozoneDB.OzoneCompatibleOrProxy, OzoneList, org.ozoneDB.OzoneRemote, java.io.Serializable
Direct Known Subclasses:
_BaseList_SubListImpl, FullLinkedListImpl

public abstract class BaseListImpl
extends AbstractOzoneCollection
implements BaseList

A basic implementation of most of the methods in the List interface to make it easier to create a List based on a random-access data structure. If the list is sequential (such as a linked list), use AbstractSequentialList. To create an unmodifiable list, it is only necessary to override the size() and get(int) methods (this contrasts with all other abstract collection classes which require an iterator to be provided). To make the list modifiable, the set(int, Object) method should also be overridden, and to make the list resizable, the add(int, Object) and remove(int) methods should be overridden too. Other methods should be overridden if the backing data structure allows for a more efficient implementation. The precise implementation used by AbstractList is documented, so that subclasses can tell which methods could be implemented more efficiently.

As recommended by Collection and List, the subclass should provide at least a no-argument and a Collection constructor. This class is not synchronized.

Since:
1.2
Author:
Original author unknown, Bryce McKinlay, Eric Blake
See Also:
Collection, List, AbstractSequentialList, AbstractCollection, ListIterator, Serialized Form

Field Summary
protected  int modCount
          A count of the number of structural modifications that have been made to the list (that is, insertions and removals).
 
Constructor Summary
protected BaseListImpl()
          The main constructor, for use by subclasses.
 
Method Summary
 void _org_ozoneDB_removeRange(int fromIndex, int toIndex)
          Remove a subsection of the list.
 void add(int index, java.lang.Object o)
           
 boolean add(java.lang.Object o)
          Add an element to the end of the list (optional operation).
 boolean addAll(int index, java.util.Collection c)
           
 void clear()
          Clear the list, such that a subsequent call to isEmpty() would return true (optional operation).
 boolean equals(java.lang.Object o)
          Test whether this list is equal to another object.
 java.util.List getClientList()
          Returns a List that contains the same entries as this persistent one; it is (by nature of the client-server enviromnent) always a 'deep' copy of this OzoneList.
 int hashCode()
          Obtains a hash code for this list.
 int indexOf(java.lang.Object o)
           
protected  java.util.Iterator internalIterator()
           
 java.util.Iterator iterator()
          Obtain an Iterator over this list, whose sequence is the list order.
 int lastIndexOf(java.lang.Object o)
          Obtain the last index at which a given object is to be found in this list.
 java.util.ListIterator listIterator()
          Obtain a ListIterator over this list, starting at the beginning.
 java.util.ListIterator listIterator(int index)
          Obtain a ListIterator over this list, starting at a given position.
 java.lang.Object remove(int index)
          Remove the element at a given position in this list (optional operation).
 java.lang.Object set(int index, java.lang.Object o)
          Replace an element of this list with another object (optional operation).
 java.util.List subList(int fromIndex, int toIndex)
          Obtain a List view of a subsection of this list, from fromIndex (inclusive) to toIndex (exclusive).
 
Methods inherited from class org.ozoneDB.collections.AbstractOzoneCollection
addAll, contains, containsAll, getClientCollection, isEmpty, remove, removeAll, retainAll, size, toArray, toArray, toString
 
Methods inherited from class org.ozoneDB.OzoneObject
container, database, deleteRecursive, getHandle, getObjectID, handle, onActivate, onCreate, onDelete, onPassivate, requireWriteLocking, self, setContainer, toXML
 
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait
 
Methods inherited from interface org.ozoneDB.collections.BaseList
_org_ozoneDB_emptyClientCollection, _org_ozoneDB_getModCount
 
Methods inherited from interface org.ozoneDB.collections.OzoneCollection
_org_ozoneDB_internalIterator, addAll, getClientCollection, remove, removeAll, retainAll
 
Methods inherited from interface java.util.Collection
contains, containsAll, isEmpty, size, toArray, toArray
 
Methods inherited from interface org.ozoneDB.OzoneCompatibleOrProxy
getObjectID
 
Methods inherited from interface java.util.List
addAll, contains, containsAll, get, isEmpty, remove, removeAll, retainAll, size, toArray, toArray
 

Field Detail

modCount

protected int modCount
A count of the number of structural modifications that have been made to the list (that is, insertions and removals). Structural modifications are ones which change the list size or affect how iterations would behave. This field is available for use by Iterator and ListIterator, in order to throw a ConcurrentModificationException in response to the next operation on the iterator. This fail-fast behavior saves the user from many subtle bugs otherwise possible from concurrent modification during iteration.

To make lists fail-fast, increment this field by just 1 in the add(int, Object) and remove(int) methods. Otherwise, this field may be ignored.

Constructor Detail

BaseListImpl

protected BaseListImpl()
The main constructor, for use by subclasses.

Method Detail

add

public void add(int index,
                java.lang.Object o)
Specified by:
add in interface OzoneList

add

public boolean add(java.lang.Object o)
Add an element to the end of the list (optional operation). If the list imposes restraints on what can be inserted, such as no null elements, this should be documented. This implementation calls add(size(), o);, and will fail if that version does.

Specified by:
add in interface OzoneCollection
Overrides:
add in class AbstractOzoneCollection
Parameters:
o - the object to add
Returns:
true, as defined by Collection for a modified list
Throws:
java.lang.UnsupportedOperationException - if this list does not support the add operation
java.lang.ClassCastException - if o cannot be added to this list due to its type
java.lang.IllegalArgumentException - if o cannot be added to this list for some other reason
See Also:
add(int, Object)

addAll

public boolean addAll(int index,
                      java.util.Collection c)
Specified by:
addAll in interface OzoneList

clear

public void clear()
Clear the list, such that a subsequent call to isEmpty() would return true (optional operation). This implementation calls removeRange(0, size()), so it will fail unless remove or removeRange is overridden.

Specified by:
clear in interface OzoneCollection
Overrides:
clear in class AbstractOzoneCollection
Throws:
java.lang.UnsupportedOperationException - if this list does not support the clear operation
See Also:
remove(int), _org_ozoneDB_removeRange(int, int)

equals

public boolean equals(java.lang.Object o)
Test whether this list is equal to another object. A List is defined to be equal to an object if and only if that object is also a List, and the two lists have the same sequence. Two lists l1 and l2 are equal if and only if l1.size() == l2.size(), and for every integer n between 0 and l1.size() - 1 inclusive, l1.get(n) == null ? l2.get(n) == null : l1.get(n).equals(l2.get(n)).

This implementation returns true if the object is this, or false if the object is not a List. Otherwise, it iterates over both lists (with iterator()), returning false if two elements compare false or one list is shorter, and true if the iteration completes successfully.

Specified by:
equals in interface java.util.Collection
Parameters:
o - the object to test for equality with this list
Returns:
true if o is equal to this list
See Also:
Object.equals(Object), hashCode()

hashCode

public int hashCode()
Obtains a hash code for this list. In order to obey the general contract of the hashCode method of class Object, this value is calculated as follows:
hashCode = 1;
Iterator i = list.iterator();
while (i.hasNext())
{
  Object obj = i.next();
  hashCode = 31 * hashCode + (obj == null ? 0 : obj.hashCode());
}
This ensures that the general contract of Object.hashCode() is adhered to.

Specified by:
hashCode in interface java.util.Collection
Returns:
the hash code of this list
See Also:
Object.hashCode(), equals(Object)

indexOf

public int indexOf(java.lang.Object o)
Specified by:
indexOf in interface java.util.List

iterator

public java.util.Iterator iterator()
Obtain an Iterator over this list, whose sequence is the list order. This implementation uses size(), get(int), and remove(int) of the backing list, and does not support remove unless the list does. This implementation is fail-fast if you correctly maintain modCount. Also, this implementation is specified by Sun to be distinct from listIterator, although you could easily implement it as return listIterator(0).

Specified by:
iterator in interface java.util.Collection
Specified by:
iterator in class AbstractOzoneCollection
Returns:
an Iterator over the elements of this list, in order
See Also:
modCount

lastIndexOf

public int lastIndexOf(java.lang.Object o)
Obtain the last index at which a given object is to be found in this list. This implementation grabs listIterator(size()), then searches backwards for a match or returns -1.

Specified by:
lastIndexOf in interface java.util.List
Returns:
the greatest integer n such that o == null ? get(n) == null : o.equals(get(n)), or -1 if there is no such index

listIterator

public java.util.ListIterator listIterator()
Obtain a ListIterator over this list, starting at the beginning. This implementation returns listIterator(0).

Specified by:
listIterator in interface java.util.List
Returns:
a ListIterator over the elements of this list, in order, starting at the beginning

listIterator

public java.util.ListIterator listIterator(int index)
Obtain a ListIterator over this list, starting at a given position. A first call to next() would return the same as get(index), and a first call to previous() would return the same as get(index - 1).

This implementation uses size(), get(int), set(int, Object), add(int, Object), and remove(int) of the backing list, and does not support remove, set, or add unless the list does. This implementation is fail-fast if you correctly maintain modCount.

Specified by:
listIterator in interface java.util.List
Parameters:
index - the position, between 0 and size() inclusive, to begin the iteration from
Returns:
a ListIterator over the elements of this list, in order, starting at index
Throws:
java.lang.IndexOutOfBoundsException - if index < 0 || index > size()
See Also:
modCount

remove

public java.lang.Object remove(int index)
Remove the element at a given position in this list (optional operation). Shifts all remaining elements to the left to fill the gap. This implementation always throws an UnsupportedOperationException. If you want fail-fast iterators, be sure to increment modCount when overriding this.

Specified by:
remove in interface OzoneList
Parameters:
index - the position within the list of the object to remove
Returns:
the object that was removed
Throws:
java.lang.UnsupportedOperationException - if this list does not support the remove operation
java.lang.IndexOutOfBoundsException - if index < 0 || index >= size()
See Also:
modCount

_org_ozoneDB_removeRange

public void _org_ozoneDB_removeRange(int fromIndex,
                                     int toIndex)
Remove a subsection of the list. This is called by the clear and removeRange methods of the class which implements subList, which are difficult for subclasses to override directly. Therefore, this method should be overridden instead by the more efficient implementation, if one exists. Overriding this can reduce quadratic efforts to constant time in some cases!

This implementation first checks for illegal or out of range arguments. It then obtains a ListIterator over the list using listIterator(fromIndex). It then calls next() and remove() on this iterator repeatedly, toIndex - fromIndex times.

Specified by:
_org_ozoneDB_removeRange in interface BaseList
Parameters:
fromIndex - the index, inclusive, to remove from.
toIndex - the index, exclusive, to remove to.

set

public java.lang.Object set(int index,
                            java.lang.Object o)
Replace an element of this list with another object (optional operation). This implementation always throws an UnsupportedOperationException.

Specified by:
set in interface OzoneList
Parameters:
index - the position within this list of the element to be replaced
o - the object to replace it with
Returns:
the object that was replaced
Throws:
java.lang.UnsupportedOperationException - if this list does not support the set operation
java.lang.IndexOutOfBoundsException - if index < 0 || index >= size()
java.lang.ClassCastException - if o cannot be added to this list due to its type
java.lang.IllegalArgumentException - if o cannot be added to this list for some other reason

subList

public java.util.List subList(int fromIndex,
                              int toIndex)
Obtain a List view of a subsection of this list, from fromIndex (inclusive) to toIndex (exclusive). If the two indices are equal, the sublist is empty. The returned list should be modifiable if and only if this list is modifiable. Changes to the returned list should be reflected in this list. If this list is structurally modified in any way other than through the returned list, the result of any subsequent operations on the returned list is undefined.

This implementation returns a subclass of AbstractList. It stores, in private fields, the offset and size of the sublist, and the expected modCount of the backing list. If the backing list implements RandomAccess, the sublist will also.

The subclass's set(int, Object), get(int), add(int, Object), remove(int), addAll(int, Collection) and removeRange(int, int) methods all delegate to the corresponding methods on the backing abstract list, after bounds-checking the index and adjusting for the offset. The addAll(Collection c) method merely returns addAll(size, c). The listIterator(int) method returns a "wrapper object" over a list iterator on the backing list, which is created with the corresponding method on the backing list. The iterator() method merely returns listIterator(), and the size() method merely returns the subclass's size field.

All methods first check to see if the actual modCount of the backing list is equal to its expected value, and throw a ConcurrentModificationException if it is not.

Specified by:
subList in interface java.util.List
Parameters:
fromIndex - the index that the returned list should start from (inclusive)
toIndex - the index that the returned list should go to (exclusive)
Returns:
a List backed by a subsection of this list
Throws:
java.lang.IndexOutOfBoundsException - if fromIndex < 0 || toIndex > size()
java.lang.IllegalArgumentException - if fromIndex > toIndex
See Also:
ConcurrentModificationException, RandomAccess

getClientList

public java.util.List getClientList()
Description copied from interface: OzoneList

Returns a List that contains the same entries as this persistent one; it is (by nature of the client-server enviromnent) always a 'deep' copy of this OzoneList. I.e. the contents of this OzoneList instance are always copied to the client by use of serialization.

Note that the difference of calling iterator() compared to getClientList().iterator() is that in the first case you go through the real collection on the server and in the second case you go through a local copy on the client side.

Specified by:
getClientList in interface OzoneList

internalIterator

protected java.util.Iterator internalIterator()


Copyright © 2004 The Ozone Database Project - www.ozone-db.org. All Rights Reserved.