/*
    * Copyright (c) 1998, 2005 Gargoyle Software Inc. All rights reserved.
    *
    * Redistribution and use in source and binary forms, with or without
    * modification, are permitted provided that the following conditions are met:
    *
    * 1. Redistributions of source code must retain the above copyright notice,
    *    this list of conditions and the following disclaimer.
    * 2. Redistributions in binary form must reproduce the above copyright notice,
   *    this list of conditions and the following disclaimer in the documentation
   *    and/or other materials provided with the distribution.
   * 3. The end-user documentation included with the redistribution, if any, must
   *    include the following acknowledgment:
   *
   *       "This product includes software developed by Gargoyle Software Inc.
   *        (http://www.GargoyleSoftware.com/)."
   *
   *    Alternately, this acknowledgment may appear in the software itself, if
   *    and wherever such third-party acknowledgments normally appear.
   * 4. The name "Gargoyle Software" must not be used to endorse or promote
   *    products derived from this software without prior written permission.
   *    For written permission, please contact info@GargoyleSoftware.com.
   * 5. Products derived from this software may not be called "GSBase", nor may
   *    "GSBase" appear in their name, without prior written permission of
   *    Gargoyle Software Inc.
   *
   * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED WARRANTIES,
   * INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
   * FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL GARGOYLE
   * SOFTWARE INC. OR ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
   * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
   * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA,
   * OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
   * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
   * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
   * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
   */
  package com.gargoylesoftware.base.collections;
  
  import com.gargoylesoftware.base.util.DetailedNullPointerException;
  import java.util.ArrayList;
  import java.util.Collection;
  import java.util.Collections;
  import java.util.Iterator;
  import java.util.List;
  import java.util.ListIterator;
  
  /***
   * This is a wrapper for a List object that fires
   * {@link com.gargoylesoftware.base.collections.NotificationListEvent}'s
   * whenever the list is modified.
   *
   * @version $Revision: 1.5 $
   * @author <a href="mailto:mbowler@GargoyleSoftware.com">Mike Bowler</a>
   */
  public class NotificationList
     implements
        List {
  
      private final List delegate_;
  
      private final List listenerList_ = new ArrayList();
  
     /***
      * Construct a new NotificationList.
      * @param delegate The list that we will delegate requests to.
      */
     public NotificationList( final List delegate ) {
        delegate_ = delegate;
  
        assertNotNull("delegate", delegate);
     }
  
     /***
      * Appends the specified element to the end of this list (optional
      * operation). <p>
      *
      * 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 object element to be appended to this list.
      * @return <tt>true</tt> (as per the general contract of the
      *            <tt>Collection.add</tt> method).
      *
      * @throws UnsupportedOperationException if the <tt>add</tt> method is not
      *                   supported by this list.
      */
      public boolean add( final Object object ) throws UnsupportedOperationException {
          final int startIndex = delegate_.size();
          final boolean rc = delegate_.add(object);
          fireInsert( startIndex, 1 );
          return rc;
      }
  
      /***
      * 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 element element to be inserted.
      *
      * @throws UnsupportedOperationException if the <tt>add</tt> method is not
      *                  supported by this list.
      */
     public void add(final int index, final Object element) throws UnsupportedOperationException {
         delegate_.add(index, element);
         fireInsert( index, 1 );
     }
 
     /***
      * 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 collection collection whose elements are to be added to this list.
      * @return <tt>true</tt> if this list changed as a result of the call.
      *
      * @throws UnsupportedOperationException if the <tt>addAll</tt> method is
      *         not supported by this list.
      * @see #add(Object)
      */
     public boolean addAll( final Collection collection ) throws UnsupportedOperationException {
         assertNotNull("collection", collection);
         final int startIndex = delegate_.size();
         final boolean rc = delegate_.addAll(collection);
         fireInsert( startIndex, collection.size() );
         return rc;
     }
 
     /***
      * 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 collection elements to be inserted into this list.
      * @return <tt>true</tt> if this list changed as a result of the call.
      *
      * @throws UnsupportedOperationException if the <tt>addAll</tt> method is
      *                  not supported by this list.
      */
     public boolean addAll(int index, final Collection collection) throws UnsupportedOperationException {
         assertNotNull("collection", collection);
 
         final boolean rc = delegate_.addAll(index, collection);
         fireInsert( index, collection.size() );
         return rc;
    }
 
     /***
      * 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.
      */
    public Object get(final int index) {
       return delegate_.get(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 element element to be stored at the specified position.
     * @return the element previously at the specified position.
     *
     * @throws UnsupportedOperationException if the <tt>set</tt> method is not
     *                  supported by this list.
     */
    public Object set(final int index, final Object element) throws UnsupportedOperationException {
        final List oldValues = new ArrayList(1);
        oldValues.add(delegate_.get(index));
 
        final List newValues = new ArrayList(1);
        newValues.add(element);
 
        Object rc = delegate_.set(index, element);
 
        fireChanged( index, oldValues, newValues );
        return rc;
    }
 
    /***
     * 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 <tt>remove</tt> method is
     *                  not supported by this list.
     */
    public Object remove(final int index) throws UnsupportedOperationException {
        final List objectsRemoved = new ArrayList(1);
        objectsRemoved.add(delegate_.get(index));
 
        final Object rc = delegate_.remove(index);
        fireRemove( index, index, objectsRemoved );
        return rc;
    }
 
    /***
     * 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 <tt>(o==null ? get(i)==null : o.equals(get(i)))</tt> (if
     * such an element exists).
     *
     * @param object element to be removed from this list, if present.
     * @return <tt>true</tt> if this list contained the specified element.
     *
     * @throws UnsupportedOperationException if the <tt>remove</tt> method is
     *                  not supported by this list.
     */
     public boolean remove( final Object object ) throws UnsupportedOperationException {
         final List objectsRemoved = new ArrayList(1);
         objectsRemoved.add(object);
 
         final int index = delegate_.indexOf(object);
         final boolean rc = delegate_.remove(object);
         fireRemove( index, index, objectsRemoved );
         return rc;
     }
 
     /***
      * Removes from this list all the elements that are contained in the
      * specified collection (optional operation).
      *
      * <b>Implementation note</b> This is currently unsupported.
      *
      * @param collection collection that defines which elements will be removed from
      *          this list.
      * @return <tt>true</tt> if this list changed as a result of the call.
      *
      * @throws UnsupportedOperationException if the <tt>removeAll</tt> method
      *                   is not supported by this list.
      *
      * @see #remove(Object)
      * @see #contains(Object)
      */
     public boolean removeAll( final Collection collection ) throws UnsupportedOperationException {
         throw new UnsupportedOperationException("Not implemented yet");
         //TODO: Implement this.
         //        return delegate_.removeAll(collection);
     }
 
     /***
      * 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.
      *
      * <b>Implementation note</b> This is currently unsupported.
      *
      * @param collection collection that defines which elements this set will retain.
      *
      * @return <tt>true</tt> if this list changed as a result of the call.
      *
      * @throws UnsupportedOperationException if the <tt>retainAll</tt> method
      *                   is not supported by this list.
      *
      * @see #remove(Object)
      * @see #contains(Object)
      */
     public boolean retainAll( final Collection collection ) throws UnsupportedOperationException {
         throw new UnsupportedOperationException("Not implemented yet");
         //TODO: Implement this.
         //        return delegate_.retainAll(collection);
     }
 
     /***
      * 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 <tt>i</tt> such that
      * <tt>(o==null ? get(i)==null : o.equals(get(i)))</tt>,
      * 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.
      */
    public int indexOf(final Object object) {
       return delegate_.indexOf(object);
    }
 
    /***
     * 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 <tt>i</tt> such that
     * <tt>(o==null ? get(i)==null : o.equals(get(i)))</tt>,
     * 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.
     */
    public int lastIndexOf(final Object object) {
       return delegate_.lastIndexOf(object);
    }
 
    /***
     * Returns a list iterator of the elements in this list (in proper
     * sequence).
     *
     * @return a list iterator of the elements in this list (in proper
     *                sequence).
     */
    public synchronized ListIterator listIterator() {
       return delegate_.listIterator();
    }
 
    /***
     * 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 <tt>next</tt> method.  An initial call to
     * the <tt>previous</tt> method would return the element with the
     * specified index minus one.
     *
     * @param index index of first element to be returned from the
     *                    list iterator (by a call to the <tt>next</tt> method).
     * @return a list iterator of the elements in this list (in proper
     *                sequence), starting at the specified position in this list.
     */
    public ListIterator listIterator(final int index) {
       return delegate_.listIterator(index);
    }
 
    /***
     * Returns a view of the portion of this list between the specified
     * <tt>fromIndex</tt>, inclusive, and <tt>toIndex</tt>, exclusive.  (If
     * <tt>fromIndex</tt> and <tt>toIndex</tt> are equal, the returned list is
     * empty.)  The returned list is backed by this list, so changes in the
     * returned list are reflected in this list, and vice-versa.  The returned
     * list supports all of the optional list operations supported by this
     * list.<p>
     *
     * 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:
     * <pre>
     *            list.subList(from, to).clear();
     * </pre>
     * Similar idioms may be constructed for <tt>indexOf</tt> and
     * <tt>lastIndexOf</tt>, and all of the algorithms in the
     * <tt>Collections</tt> class can be applied to a subList.<p>
     *
     * The semantics of this list returned by this method become undefined if
     * the backing list (i.e., this list) is <i>structurally modified</i> in
     * any way other than via the returned list.  (Structural modifications are
     * those that change the size of this list, or otherwise perturb it in such
     * a fashion that iterations in progress may yield incorrect results.)
     *
     * @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.
     */
    public List subList(final int fromIndex, final int toIndex) {
       return delegate_.subList(fromIndex, toIndex);
    }
 
    /***
     * Returns an iterator over the elements in this list in proper sequence.
     *
     * @return an iterator over the elements in this list in proper sequence.
     */
     public Iterator iterator() {
         return delegate_.iterator();
     }
 
     /***
      * Returns <tt>true</tt> if this list contains all of the elements of the
      * specified collection.
      *
      * @param collection collection to be checked for containment in this list.
      * @return <tt>true</tt> if this list contains all of the elements of the
      *                specified collection.
      *
      * @see #contains(Object)
      */
     public boolean containsAll( final Collection collection ) {
         return delegate_.containsAll(collection);
     }
 
     /***
      * Returns <tt>true</tt> if this list contains the specified element.
      * More formally, returns <tt>true</tt> if and only if this list contains
      * at least one element <tt>e</tt> such that
      * <tt>(o==null&nbsp;?&nbsp;e==null&nbsp;:&nbsp;o.equals(e))</tt>.
      *
      * @param object element whose presence in this list is to be tested.
      * @return <tt>true</tt> if this list contains the specified element.
      */
     public boolean contains( final Object object ) {
         return delegate_.contains(object);
     }
 
     /***
      * 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 <tt>clear</tt> method is
      *                   not supported by this list.
      */
     public void clear() throws UnsupportedOperationException {
         delegate_.clear();
     }
 
     /***
      * Returns <tt>true</tt> if this list contains no elements.
      *
      * @return <tt>true</tt> if this list contains no elements.
      */
     public boolean isEmpty() {
         return delegate_.isEmpty();
     }
 
     /***
      * Returns the number of elements in this list.  If this list contains
      * more than <tt>Integer.MAX_VALUE</tt> elements, returns
      * <tt>Integer.MAX_VALUE</tt>.
      *
      * @return the number of elements in this list.
      */
     public int size() {
         return delegate_.size();
     }
 
     /***
      * Returns an array containing all of the elements in this list in proper
      * sequence.  Obeys the general contract of the
      * <tt>List.toArray</tt> method.
      *
      * @return an array containing all of the elements in this list in proper
      *               sequence.
      * @see List#toArray(Object[])
      */
     public Object[] toArray() {
         return delegate_.toArray();
     }
 
     /***
      * 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
      * <tt>Collection.toArray(Object[])</tt> 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.
      */
     public Object[] toArray( Object array[] ) throws ArrayStoreException {
         return delegate_.toArray(array);
     }
 
     /***
      * Add a NotificationListListener.
      * @param listener The listener to add.
      */
     public synchronized void addNotificationListListener(
         final NotificationListListener listener ) {
 
         assertNotNull("listener", listener);
 
         listenerList_.add( listener );
     }
 
     /***
      * Remove a NotificationListListener.
      * @param listener The listener to remove.
      */
     public synchronized void removeNotificationListListener(
         final NotificationListListener listener ) {
 
         assertNotNull("listener", listener);
         listenerList_.remove( listener );
     }
 
     /***
      * Fire an insert event.
      * @param startIndex The first index
      * @param insertCount The number of items being inserted
      */
     private synchronized void fireInsert( final int startIndex,
                                           final int insertCount ) {
 
         // Is there anything to do?
         if( listenerList_.isEmpty() ) {
             return;
         }
 
         final int endIndex = startIndex + insertCount;
         final NotificationListEvent event
             = new NotificationListEvent( this,
                                          NotificationListEvent.INSERT,
                                          startIndex,
                                          startIndex,
                                          Collections.EMPTY_LIST,
                                          delegate_.subList(startIndex, endIndex) );
 
         final NotificationListListener listeners[]
             = new NotificationListListener[listenerList_.size()];
         listenerList_.toArray( listeners );
 
         int i;
         for( i=0; i<listeners.length; i++ ) {
             listeners[i].listElementsAdded(event);
         }
     }
 
     /***
      * Fire a remove event.
      * @param startIndex The first index
      * @param endIndex The last index
      * @param objectsRemoved A list of all the objects that have been removd.
      */
     private synchronized void fireRemove( final int startIndex,
                                           final int endIndex,
                                           final List objectsRemoved) {
 
         // Is there anything to do?
         if( listenerList_.isEmpty() ) {
             return;
         }
 
         final NotificationListEvent event
             = new NotificationListEvent( this,
                                          NotificationListEvent.REMOVE,
                                          startIndex,
                                          endIndex,
                                          objectsRemoved,
                                          Collections.EMPTY_LIST);
 
         final NotificationListListener listeners[]
             = new NotificationListListener[listenerList_.size()];
         listenerList_.toArray( listeners );
 
         int i;
         for( i=0; i<listeners.length; i++ ) {
             listeners[i].listElementsRemoved(event);
         }
     }
 
     /***
      * Fire a changed event.
      * @param startIndex The first index
      * @param oldValues The old values
      * @param newValues The new values
      */
     private synchronized void fireChanged( final int startIndex,
                                            final List oldValues,
                                            final List newValues ) {
         if( oldValues.size() != newValues.size() ) {
             throw new IllegalArgumentException("Lists must be the same size:"
                                                + " oldValues.size()="
                                                + oldValues.size()
                                                + " newValues.size()="
                                                + newValues.size() );
         }
 
         // Is there anything to do?
         if( listenerList_.isEmpty() ) {
             return;
         }
 
         final NotificationListEvent event
             = new NotificationListEvent( this,
                                          NotificationListEvent.CHANGE,
                                          startIndex,
                                          startIndex,
                                          oldValues,
                                          newValues);
 
         final NotificationListListener listeners[]
             = new NotificationListListener[listenerList_.size()];
         listenerList_.toArray( listeners );
 
         int i;
         for( i=0; i<listeners.length; i++ ) {
             listeners[i].listElementsChanged(event);
         }
 
     }
 
 
     private void assertNotNull( final String fieldName, final Object object ) {
         if( object == null ) {
             throw new DetailedNullPointerException(fieldName);
         }
     }
 }