/* Glazed Lists (c) 2003-2006 */ /* http://publicobject.com/glazedlists/ publicobject.com,*/ /* O'Dell Engineering Ltd.*/ package ca.odell.glazedlists; // the Glazed Lists' change objects import ca.odell.glazedlists.event.ListEventAssembler; import ca.odell.glazedlists.event.ListEventListener; import ca.odell.glazedlists.event.ListEventPublisher; import ca.odell.glazedlists.impl.EventListIterator; import ca.odell.glazedlists.impl.GlazedListsImpl; import ca.odell.glazedlists.impl.SimpleIterator; import ca.odell.glazedlists.impl.SubEventList; import ca.odell.glazedlists.util.concurrent.ReadWriteLock; import java.lang.reflect.Array; import java.util.*; /** * A convenience class that implements common functionality for all {@link EventList}s. * *

If you are creating a custom {@link EventList}, consider extending the more * feature-rich {@link TransformedList}. * *

Documentation Note: Javadoc tags have been copied from the {@link List} API * because the javadoc tool does not inherit external descriptions. * * @author Jesse Wilson */ public abstract class AbstractEventList implements EventList { /** the change event and notification system */ protected ListEventAssembler updates = null; /** the read/write lock provides mutual exclusion to access */ protected ReadWriteLock readWriteLock = null; /** the publisher manages the distribution of changes */ protected ListEventPublisher publisher = null; /** * Creates an {@link AbstractEventList} that sends events using the specified * {@link ListEventPublisher}. * * @param publisher the channel for event distribution. If this is null, * then a new {@link ListEventPublisher} will be created. */ protected AbstractEventList(ListEventPublisher publisher) { if(publisher == null) publisher = ListEventAssembler.createListEventPublisher(); this.publisher = publisher; updates = new ListEventAssembler(this, publisher); } /** * Create an {@link AbstractEventList} that sends events with the default * {@link ListEventPublisher}. */ protected AbstractEventList() { this(null); } /** {@inheritDoc} */ public ListEventPublisher getPublisher() { return publisher; } /** {@inheritDoc} */ public ReadWriteLock getReadWriteLock() { return readWriteLock; } /** {@inheritDoc} */ public void addListEventListener(ListEventListener listChangeListener) { updates.addListEventListener(listChangeListener); } /** {@inheritDoc} */ public void removeListEventListener(ListEventListener listChangeListener) { updates.removeListEventListener(listChangeListener); } /** * Returns the number of elements in this list. If this list contains * more than Integer.MAX_VALUE elements, returns * Integer.MAX_VALUE. * * @return the number of elements in this list. */ public abstract int size(); /** * Returns true if this list contains no elements. * * @return true if this list contains no elements. */ public boolean isEmpty() { return (size() == 0); } /** * Returns true if this list contains the specified element. * More formally, returns true if and only if this list contains * at least one element e such that * (o==null ? e==null : o.equals(e)). * * @param object element whose presence in this list is to be tested. * @return true if this list contains the specified element. * @throws ClassCastException if the type of the specified element * is incompatible with this list (optional). * @throws NullPointerException if the specified element is null and this * list does not support null elements (optional). */ public boolean contains(Object object) { // for through this, looking for the lucky object for(Iterator i = iterator(); i.hasNext(); ) { if(GlazedListsImpl.equal(object, i.next())) return true; } // not found return false; } /** * Returns an iterator over the elements in this list in proper sequence. * *

The returned {@link Iterator} will become inconsistent if the * {@link EventList} that it views is modified. To overcome this problem, * use {@link #listIterator()}. When used concurrently, the returned * {@link Iterator} requires locking via this list's * {@link #getReadWriteLock() ReadWriteLock}. * * @return an iterator over the elements in this list in proper sequence. */ public Iterator iterator() { return new SimpleIterator(this); } /** * Returns an array containing all of the elements in this list in proper * sequence. Obeys the general contract of the * Collection.toArray method. * * @return an array containing all of the elements in this list in proper * sequence. * @see Arrays#asList */ public Object[] toArray() { // copy values into the array Object[] array = new Object[size()]; int index = 0; for(Iterator i = iterator(); i.hasNext(); ) { array[index] = i.next(); index++; } return array; } /** * Returns an array containing all of the elements in this list in proper * sequence; the runtime type of the returned array is that of the * specified array. Obeys the general contract of the * Collection.toArray(Object[]) method. * * @param array the array into which the elements of this list are to * be stored, if it is big enough; otherwise, a new array of the * same runtime type is allocated for this purpose. * @return an array containing the elements of this list. * * @throws ArrayStoreException if the runtime type of the specified array * is not a supertype of the runtime type of every element in * this list. * @throws NullPointerException if the specified array is null. */ public T[] toArray(T[] array) { // create an array of the same type as the array passed if (array.length < size()) { array = (T[]) Array.newInstance(array.getClass().getComponentType(), size()); } else if(array.length > size()) { array[size()] = null; } // copy values into the array int index = 0; for(Iterator i = iterator(); i.hasNext(); ) { array[index] = (T) i.next(); index++; } return array; } /** * Appends the specified element to the end of this list (optional * operation). * *

Lists that support this operation may place limitations on what * elements may be added to this list. In particular, some * lists will refuse to add null elements, and others will impose * restrictions on the type of elements that may be added. List * classes should clearly specify in their documentation any restrictions * on what elements may be added. * * @param value element to be appended to this list. * @return true (as per the general contract of the * Collection.add method). * * @throws UnsupportedOperationException if the add method is not * supported by this list. * @throws ClassCastException if the class of the specified element * prevents it from being added to this list. * @throws NullPointerException if the specified element is null and this * list does not support null elements. * @throws IllegalArgumentException if some aspect of this element * prevents it from being added to this list. */ public boolean add(E value) { final int initialSize = this.size(); this.add(this.size(), value); return this.size() != initialSize; } /** * Removes the first occurrence in this list of the specified element * (optional operation). If this list does not contain the element, it is * unchanged. More formally, removes the element with the lowest index i * such that (o==null ? get(i)==null : o.equals(get(i))) (if * such an element exists). * * @param toRemove element to be removed from this list, if present. * @return true if this list contained the specified element. * @throws ClassCastException if the type of the specified element * is incompatible with this list (optional). * @throws NullPointerException if the specified element is null and this * list does not support null elements (optional). * @throws UnsupportedOperationException if the remove method is * not supported by this list. */ public boolean remove(Object toRemove) { int index = indexOf(toRemove); if(index == -1) return false; this.remove(index); return true; } /** * Returns true if this list contains all of the elements of the * specified collection. * * @param values collection to be checked for containment in this list. * @return true if this list contains all of the elements of the * specified collection. * @throws ClassCastException if the types of one or more elements * in the specified collection are incompatible with this * list (optional). * @throws NullPointerException if the specified collection contains one * or more null elements and this list does not support null * elements (optional). * @throws NullPointerException if the specified collection is * null. * @see #contains(Object) */ public boolean containsAll(Collection values) { // look for something that is missing for(Iterator i = values.iterator(); i.hasNext(); ) { Object a = i.next(); if(!contains(a)) return false; } // contained everything we looked for return true; } /** * Appends all of the elements in the specified collection to the end of * this list, in the order that they are returned by the specified * collection's iterator (optional operation). The behavior of this * operation is unspecified if the specified collection is modified while * the operation is in progress. (Note that this will occur if the * specified collection is this list, and it's nonempty.) * * @param values collection whose elements are to be added to this list. * @return true if this list changed as a result of the call. * * @throws UnsupportedOperationException if the addAll method is * not supported by this list. * @throws ClassCastException if the class of an element in the specified * collection prevents it from being added to this list. * @throws NullPointerException if the specified collection contains one * or more null elements and this list does not support null * elements, or if the specified collection is null. * @throws IllegalArgumentException if some aspect of an element in the * specified collection prevents it from being added to this * list. * @see #add(Object) */ public boolean addAll(Collection values) { return addAll(size(), values); } /** * Inserts all of the elements in the specified collection into this * list at the specified position (optional operation). Shifts the * element currently at that position (if any) and any subsequent * elements to the right (increases their indices). The new elements * will appear in this list in the order that they are returned by the * specified collection's iterator. The behavior of this operation is * unspecified if the specified collection is modified while the * operation is in progress. (Note that this will occur if the specified * collection is this list, and it's nonempty.) * * @param index index at which to insert first element from the specified * collection. * @param values elements to be inserted into this list. * @return true if this list changed as a result of the call. * * @throws UnsupportedOperationException if the addAll method is * not supported by this list. * @throws ClassCastException if the class of one of elements of the * specified collection prevents it from being added to this * list. * @throws NullPointerException if the specified collection contains one * or more null elements and this list does not support null * elements, or if the specified collection is null. * @throws IllegalArgumentException if some aspect of one of elements of * the specified collection prevents it from being added to * this list. * @throws IndexOutOfBoundsException if the index is out of range (index * < 0 || index > size()). */ public boolean addAll(int index, Collection values) { // don't do an add of an empty set if(index < 0 || index > size()) throw new IndexOutOfBoundsException("Cannot add at " + index + " on list of size " + size()); if(values.size() == 0) return false; final int initializeSize = this.size(); for (Iterator iter = values.iterator(); iter.hasNext();) { this.add(index, iter.next()); // advance the insertion location if its within the size of the list if (index < this.size()) index++; } return this.size() != initializeSize; } /** * Removes from this list all the elements that are contained in the * specified collection (optional operation). * * @param values collection that defines which elements will be removed from * this list. * @return true if this list changed as a result of the call. * * @throws UnsupportedOperationException if the removeAll method * is not supported by this list. * @throws ClassCastException if the types of one or more elements * in this list are incompatible with the specified * collection (optional). * @throws NullPointerException if this list contains one or more * null elements and the specified collection does not support * null elements (optional). * @throws NullPointerException if the specified collection is * null. * @see #remove(Object) * @see #contains(Object) */ public boolean removeAll(Collection values) { boolean changed = false; for(Iterator i = iterator(); i.hasNext(); ) { if(values.contains(i.next())) { i.remove(); changed = true; } } return changed; } /** * Retains only the elements in this list that are contained in the * specified collection (optional operation). In other words, removes * from this list all the elements that are not contained in the specified * collection. * * @param values collection that defines which elements this set will retain. * * @return true if this list changed as a result of the call. * * @throws UnsupportedOperationException if the retainAll method * is not supported by this list. * @throws ClassCastException if the types of one or more elements * in this list are incompatible with the specified * collection (optional). * @throws NullPointerException if this list contains one or more * null elements and the specified collection does not support * null elements (optional). * @throws NullPointerException if the specified collection is * null. * @see #remove(Object) * @see #contains(Object) */ public boolean retainAll(Collection values) { boolean changed = false; for(Iterator i = iterator(); i.hasNext();) { if(!values.contains(i.next())) { i.remove(); changed = true; } } return changed; } /** * Removes all of the elements from this list (optional operation). This * list will be empty after this call returns (unless it throws an * exception). * * @throws UnsupportedOperationException if the clear method is * not supported by this list. */ public void clear() { for(Iterator i = iterator(); i.hasNext();) { i.next(); i.remove(); } } /** * Compares the specified object with this list for equality. Returns * true if and only if the specified object is also a list, both * lists have the same size, and all corresponding pairs of elements in * the two lists are equal. (Two elements e1 and * e2 are equal if (e1==null ? e2==null : * e1.equals(e2)).) In other words, two lists are defined to be * equal if they contain the same elements in the same order. This * definition ensures that the equals method works properly across * different implementations of the List interface. * * @param object the object to be compared for equality with this list. * @return true if the specified object is equal to this list. */ @Override public boolean equals(Object object) { if(object == this) return true; if(object == null) return false; if(!(object instanceof List)) return false; // ensure the lists are the same size List otherList = (List)object; if(otherList.size() != size()) return false; // compare element wise, via iterators Iterator iterA = iterator(); Iterator iterB = otherList.iterator(); while(iterA.hasNext() && iterB.hasNext()) { if(!GlazedListsImpl.equal(iterA.next(), iterB.next())) return false; } // if we haven't failed yet, they match return true; } /** * Returns the hash code value for this list. The hash code of a list * is defined to be the result of the following calculation: * 

     *  hashCode = 1;
     *  Iterator i = list.iterator();
     *  while (i.hasNext()) {
     *      Object obj = i.next();
     *      hashCode = 31*hashCode + (obj==null ? 0 : obj.hashCode());
     *  }
     *
* This ensures that list1.equals(list2) implies that * list1.hashCode()==list2.hashCode() for any two lists, * list1 and list2, as required by the general * contract of Object.hashCode. * * @return the hash code value for this list. * @see Object#hashCode() * @see Object#equals(Object) * @see #equals(Object) */ @Override public int hashCode() { int hashCode = 1; for(Iterator i = iterator(); i.hasNext(); ) { E a = i.next(); hashCode = 31 * hashCode + (a == null ? 0 : a.hashCode()); } return hashCode; } /** * Returns the element at the specified position in this list. * * @param index index of element to return. * @return the element at the specified position in this list. * * @throws IndexOutOfBoundsException if the index is out of range (index * < 0 || index >= size()). */ public abstract E get(int index); /** * Replaces the element at the specified position in this list with the * specified element (optional operation). * * @param index index of element to replace. * @param value element to be stored at the specified position. * @return the element previously at the specified position. * * @throws UnsupportedOperationException if the set method is not * supported by this list. * @throws ClassCastException if the class of the specified element * prevents it from being added to this list. * @throws NullPointerException if the specified element is null and * this list does not support null elements. * @throws IllegalArgumentException if some aspect of the specified * element prevents it from being added to this list. * @throws IndexOutOfBoundsException if the index is out of range * (index < 0 || index >= size()). */ public E set(int index, E value) { throw new UnsupportedOperationException("this list does not support set()"); } /** * Inserts the specified element at the specified position in this list * (optional operation). Shifts the element currently at that position * (if any) and any subsequent elements to the right (adds one to their * indices). * * @param index index at which the specified element is to be inserted. * @param value element to be inserted. * * @throws UnsupportedOperationException if the add method is not * supported by this list. * @throws ClassCastException if the class of the specified element * prevents it from being added to this list. * @throws NullPointerException if the specified element is null and * this list does not support null elements. * @throws IllegalArgumentException if some aspect of the specified * element prevents it from being added to this list. * @throws IndexOutOfBoundsException if the index is out of range * (index < 0 || index > size()). */ public void add(int index, E value) { throw new UnsupportedOperationException("this list does not support add()"); } /** * Removes the element at the specified position in this list (optional * operation). Shifts any subsequent elements to the left (subtracts one * from their indices). Returns the element that was removed from the * list. * * @param index the index of the element to removed. * @return the element previously at the specified position. * * @throws UnsupportedOperationException if the remove method is * not supported by this list. * @throws IndexOutOfBoundsException if the index is out of range (index * < 0 || index >= size()). */ public E remove(int index) { throw new UnsupportedOperationException("this list does not support remove()"); } /** * Returns the index in this list of the first occurrence of the specified * element, or -1 if this list does not contain this element. * More formally, returns the lowest index i such that * (o==null ? get(i)==null : o.equals(get(i))), * or -1 if there is no such index. * * @param object element to search for. * @return the index in this list of the first occurrence of the specified * element, or -1 if this list does not contain this element. * @throws ClassCastException if the type of the specified element * is incompatible with this list (optional). * @throws NullPointerException if the specified element is null and this * list does not support null elements (optional). */ public int indexOf(Object object) { // for through this, looking for the lucky object int index = 0; for(Iterator i = iterator(); i.hasNext(); ) { if(GlazedListsImpl.equal(object, i.next())) return index; else index++; } // not found return -1; } /** * Returns the index in this list of the last occurrence of the specified * element, or -1 if this list does not contain this element. * More formally, returns the highest index i such that * (o==null ? get(i)==null : o.equals(get(i))), * or -1 if there is no such index. * * @param object element to search for. * @return the index in this list of the last occurrence of the specified * element, or -1 if this list does not contain this element. * @throws ClassCastException if the type of the specified element * is incompatible with this list (optional). * @throws NullPointerException if the specified element is null and this * list does not support null elements (optional). */ public int lastIndexOf(Object object) { // for through this, looking for the lucky object for(int i = size() - 1; i >= 0; i--) { if(GlazedListsImpl.equal(object, get(i))) return i; } // not found return -1; } /** * Returns a list iterator of the elements in this list (in proper * sequence). * *

Unlike the {@link ListIterator} from a regular {@link List}, the * {@link EventList}'s {@link ListIterator} will remain consistent even if the * {@link EventList} is changed externally. Note that when used concurrently, * the returned {@link ListIterator} requires locking via this list's * {@link #getReadWriteLock() ReadWriteLock}. * * @return a list iterator of the elements in this list (in proper * sequence). */ public ListIterator listIterator() { return listIterator(0); } /** * Returns a list iterator of the elements in this list (in proper * sequence), starting at the specified position in this list. The * specified index indicates the first element that would be returned by * an initial call to the next method. An initial call to * the previous method would return the element with the * specified index minus one. * *

Unlike the {@link ListIterator} from a regular {@link List}, the * {@link EventList}'s {@link ListIterator} will remain consistent even if the * {@link EventList} is changed externally. Note that when used concurrently, * the returned {@link ListIterator} requires locking via this list's * {@link #getReadWriteLock() ReadWriteLock}. * * @param index index of first element to be returned from the * list iterator (by a call to the next method). * @return a list iterator of the elements in this list (in proper * sequence), starting at the specified position in this list. * @throws IndexOutOfBoundsException if the index is out of range (index * < 0 || index > size()). */ public ListIterator listIterator(int index) { return new EventListIterator(this, index); } /** * Returns a view of the portion of this list between the specified * fromIndex, inclusive, and toIndex, exclusive. (If * fromIndex and toIndex are equal, the returned list is * empty.) *

Unlike the standard {@link List#subList(int,int) List.subList()} * method, the {@link List} returned by this method will continue to be * consistent even if the {@link EventList} it views is modified, * structurally or otherwise. The returned {@link List} can always be safely * cast to {@link EventList}. Note that when used concurrently, the returned * {@link List} requires locking via this list's * {@link #getReadWriteLock() ReadWriteLock}. * *

This method eliminates the need for explicit range operations (of * the sort that commonly exist for arrays). Any operation that expects * a list can be used as a range operation by passing a subList view * instead of a whole list. For example, the following idiom * removes a range of elements from a list: * 

     *      list.subList(from, to).clear();
     *
* Similar idioms may be constructed for indexOf and * lastIndexOf, and all of the algorithms in the * Collections class can be applied to a subList. * * @param fromIndex low endpoint (inclusive) of the subList. * @param toIndex high endpoint (exclusive) of the subList. * @return a view of the specified range within this list. * * @throws IndexOutOfBoundsException for an illegal endpoint index value * (fromIndex < 0 || toIndex > size || fromIndex > toIndex). */ public List subList(int fromIndex, int toIndex) { return new SubEventList(this, fromIndex, toIndex, true); } /** * Returns a string representation of this collection. The string * representation consists of a list of the collection's elements in the * order they are returned by its iterator, enclosed in square brackets * ("[]"). Adjacent elements are separated by the characters * ", " (comma and space). Elements are converted to strings as * by String.valueOf(Object). * *

This implementation creates an empty string buffer, appends a left * square bracket, and iterates over the collection appending the string * representation of each element in turn. After appending each element * except the last, the string ", " is appended. Finally a right * bracket is appended. A string is obtained from the string buffer, and * returned. * * @return a string representation of this collection. */ @Override public String toString() { StringBuffer result = new StringBuffer(); result.append("["); for(Iterator i = iterator(); i.hasNext(); ) { result.append(String.valueOf(i.next())); if(i.hasNext()) result.append(", "); } result.append("]"); return result.toString(); } }