orderedset.java

Open DMT GPS server source code

// ----------------------------------------------------------------------------
// Copyright 2006-2008, Martin D. Flynn
// All rights reserved
// ----------------------------------------------------------------------------
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
// 
// http://www.apache.org/licenses/LICENSE-2.0
// 
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
//
// ----------------------------------------------------------------------------
// Description:
//  This class provides an ordered Set
// ----------------------------------------------------------------------------
// Change History:
//  2006/03/26  Martin D. Flynn
//      Initial release
//  2006/06/30  Martin D. Flynn
//     -Repackaged
//  2008/05/14  Martin D. Flynn
//     -Added initial Java 5 'generics'
// ----------------------------------------------------------------------------
package org.opengts.util;

import java.util.*;

public class OrderedSet<K>
    implements Set<K>, java.util.List<K>, Cloneable
{
    
    // ------------------------------------------------------------------------

    protected static final int ENTRY_ADDED   = 1;
    protected static final int ENTRY_REMOVED = 2;
    
    /**
    *** ChangeListener interface
    **/
    public static interface ChangeListener
    {
        public void entryAdded(OrderedSet set, Object obj);
        public void entryRemoved(OrderedSet set, Object obj);
    }
    
    /**
    *** ChangeListener adapter
    **/
    public static class ChangeListenerAdapter
        implements ChangeListener
    {
        public void entryAdded(OrderedSet set, Object obj) {
            //Print.logDebug("Item added: " + obj);
        }
        public void entryRemoved(OrderedSet set, Object obj) {
            //Print.logDebug("Item removed: " + obj);
        }
    }
    
    // ------------------------------------------------------------------------
    
    private java.util.List<K>               elements = null;
    private boolean                         retainOriginalValue = false;
    private java.util.List<ChangeListener>  changeListeners = null;
    private int                             addChangeCount = 0;
    private int                             removeChangeCount = 0;

    /**
    *** Constructor
    **/
    public OrderedSet()
    {
        super();
    }

    /**
    *** Construtor 
    *** @param retainOriginalValue  True to ignore duplicate entries, false overwrite existing entries
    ***                             with any newly added duplicates.
    **/
    public OrderedSet(boolean retainOriginalValue)
    {
        this.setRetainOriginalValue(retainOriginalValue);
    }

    /**
    *** Construtor 
    *** @param c    Collection of Objects used to initialize this set.
    *** @param retainOriginalValue  True to ignore duplicate entries, false overwrite existing entries
    ***                             with any newly added duplicates.
    **/
    public OrderedSet(Collection<? extends K> c, boolean retainOriginalValue)
    {
        this(retainOriginalValue);
        this.addAll(c);
    }

    /**
    *** Construtor 
    *** @param c    Collection of Objects used to initialize this set.
    **/
    public OrderedSet(Collection<? extends K> c)
    {
        this(c, false);
    }

    /**
    *** Construtor 
    *** @param a    Array of Objects used to initialize this set.
    *** @param retainOriginalValue  True to ignore duplicate entries, false overwrite existing entries
    ***                             with any newly added duplicates.
    **/
    public OrderedSet(K a[], boolean retainOriginalValue)
    {
        this(retainOriginalValue);
        this.addAll(a);
    }

    /**
    *** Construtor 
    *** @param a    Array of Objects used to initialize this set.
    **/
    public OrderedSet(K a[])
    {
        this(a, false);
    }

    /**
    *** Copy Construtor 
    *** @param os   Other OrderedSet used to initialize this set
    **/
    public OrderedSet(OrderedSet<K> os)
    {
        super();
        this.setRetainOriginalValue(os.getRetainOriginalValue());
        this.getBackingList().addAll(os.getBackingList());
    }
    
    // ------------------------------------------------------------------------
    
    /**
    *** Returns a clone of this OrderedSet
    *** @return The cloned OrderedSet
    **/
    public Object clone()
    {
        return new OrderedSet<K>(this);
    }
    
    // ------------------------------------------------------------------------

    /**
    *** Gets a list of change listeners
    *** @param create  True to create an empty list if no change listeners have been added
    *** @return The list of change listeners
    **/
    protected java.util.List<ChangeListener> getChangeListeners(boolean create)
    {
        if ((this.changeListeners == null) && create) { 
            this.changeListeners = new Vector<ChangeListener>(); 
        }
        return this.changeListeners;
    }
    
    /**
    *** Returns true if any change listeners have been registered
    *** @return True if any change listeners have been registered
    **/
    protected boolean hasChangeListeners()
    {
        return (this.getChangeListeners(false) != null);
    }
    
    /**
    *** Adds a change listener to this OrderedSet
    *** @param cl  The change listener to add
    **/
    public void addChangeListener(ChangeListener cl)
    {
        if (cl != null) {
            java.util.List<ChangeListener> listeners = this.getChangeListeners(true);
            if (!listeners.contains(cl)) {
                //Print.dprintln("Adding ChangeListener: " + StringTools.className(cl));
                listeners.add(cl);
            }
        }
    }
    
    /**
    *** Removes a change listener to this OrderedSet
    *** @param cl  The change listener to remove
    **/
    public void removeChangeListener(ChangeListener cl)
    {
        if (cl != null) {
            java.util.List<ChangeListener> listeners = this.getChangeListeners(false);
            if (listeners != null) {
                //Print.dprintln("Removing ChangeListener: " + StringTools.className(cl));
                listeners.remove(cl);
            }
        }
    }
    
    /**
    *** Notifies all change listeners of a change to this OrderedSet
    *** @param action   The change action
    *** @param obj      The Object changed
    **/
    protected void notifyChangeListeners(int action, Object obj)
    {
        java.util.List<ChangeListener> listeners = this.getChangeListeners(false);
        if (listeners != null) {
            for (Iterator i = listeners.iterator(); i.hasNext();) {
                ChangeListener cl = (ChangeListener)i.next();
                if (action == ENTRY_ADDED) {
                    cl.entryAdded(this, obj);
                    addChangeCount++;
                } else
                if (action == ENTRY_REMOVED) {
                    cl.entryRemoved(this, obj);
                    removeChangeCount++;
                } else {
                    Print.logError("Unrecognized action: " + action);
                }
            }
        }
    }
    
    // ------------------------------------------------------------------------
    
    /**
    *** Gets the ordered backing list for this OrderedSet
    *** @return The backing list instance
    **/
    protected java.util.List<K> getBackingList()
    {
        if (this.elements == null) { this.elements = new Vector<K>(); }
        return this.elements;
    }
    
    /**
    *** Gets the ordered backing list for this OrderedSet
    *** @return The backing list instance
    **/
    public java.util.List<K> getList()
    {
        return this.getBackingList();
    }
    
    // ------------------------------------------------------------------------

    /**
    *** Returns true if original added entries should be retained if a duplicate entry
    *** is subsequently added.
    *** @return True if original added entries should be retained
    **/
    public boolean getRetainOriginalValue()
    {
        return this.retainOriginalValue;
    }
    
    /**
    *** Sets the retain-original state for this OrderedSet if duplicate entries are added.
    *** @param state  True to retain original added entries
    **/
    public void setRetainOriginalValue(boolean state)
    {
        this.retainOriginalValue = state;
    }
    
    // ------------------------------------------------------------------------
    
    /**
    *** Gets the Objects at the specified index
    *** @param ndx  The index
    *** @return The object at the specified index
    **/
    public K get(int ndx)
    {
        // java.util.List (mandatory)
        // allowed, since this is an ordered set (backed by a List)
        return this.getBackingList().get(ndx);
    }
    
    /**
    *** Throws an UnsupportedOperationException
    *** @param ndx  The index
    *** @param obj  The Object to set
    *** @return The previous Object
    *** @throws UnsupportedOperationException always
    **/
    public K set(int ndx, K obj)
    {
        // java.util.List (optional)
        throw new UnsupportedOperationException();
    }
    
    // ------------------------------------------------------------------------
    
    /**
    *** Adds the Object at the specified index
    *** @param ndx  The index
    *** @param obj  The Object to add
    **/
    protected void _add(int ndx, K obj)
    {
        if ((ndx < 0) || (ndx >= this.getBackingList().size())) {
            this.getBackingList().add(obj); // add to end
        } else {
            this.getBackingList().add(ndx, obj); // insert at index
        }
        this.notifyChangeListeners(ENTRY_ADDED, obj);
    }
    
    /**
    *** Adds the Object to the end of the list
    *** @param obj  The Object to add
    **/
    public boolean add(K obj)
    {
        if (this.getRetainOriginalValue()) {
            boolean contained = this.contains(obj);
            if (!contained) { // retain original
                this._add(-1, obj);
            }
            return !contained;
        } else {
            boolean contained = this.remove(obj);   // remove original
            this._add(-1, obj);
            return !contained;
        }
    }
    
    /**
    *** Adds all Objects in the specified Collection to this set
    *** @param c  The Collection
    *** @return True if any items were added to this list
    **/
    public boolean addAll(Collection<? extends K> c)
    {
        if ((c != null) && (c.size() > 0)) {
            for (Iterator<? extends K> i = c.iterator(); i.hasNext();) {
                this.add(i.next()); // TODO: should check retain-original state for actual changes
            }
            return true;
        } else {
            return false;
        }
    }

    /**
    *** Adds all Objects in the specified array to this set
    *** @param a  The array
    *** @return True if any items were added to this list
    **/
    public boolean addAll(K a[])
    {
        if ((a != null) && (a.length > 0)) {
            for (int i = 0; i < a.length; i++) {
                this.add(a[i]); // TODO: should check retain-original state for actual changes
            }
            return true;
        } else {
            return false;
        }
    }
    
    /**
    *** Adds the Object at the specified index
    *** @param ndx  The index
    *** @param obj  The Object to add
    **/
    public void add(int ndx, K obj)
    {
        if (this.getRetainOriginalValue()) {
            boolean contained = this.contains(obj);
            if (!contained) { // retain original
                this._add(ndx, obj);
            }
            //return !contained;
        } else {
            boolean contained = this.remove(obj);   // remove original
            this._add(ndx, obj);