001/* ===========================================================
002 * JFreeChart : a free chart library for the Java(tm) platform
003 * ===========================================================
004 *
005 * (C) Copyright 2000-2020, by Object Refinery Limited and Contributors.
006 *
007 * Project Info:  http://www.jfree.org/jfreechart/index.html
008 *
009 * This library is free software; you can redistribute it and/or modify it
010 * under the terms of the GNU Lesser General Public License as published by
011 * the Free Software Foundation; either version 2.1 of the License, or
012 * (at your option) any later version.
013 *
014 * This library is distributed in the hope that it will be useful, but
015 * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
016 * or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public
017 * License for more details.
018 *
019 * You should have received a copy of the GNU Lesser General Public
020 * License along with this library; if not, write to the Free Software
021 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301,
022 * USA.
023 *
024 * [Oracle and Java are registered trademarks of Oracle and/or its affiliates. 
025 * Other names may be trademarks of their respective owners.]
026 *
027 * -----------------
028 * KeyedObjects.java
029 * -----------------
030 * (C) Copyright 2003-2016, by Object Refinery Limited.
031 *
032 * Original Author:  David Gilbert (for Object Refinery Limited);
033 * Contributor(s):   -;
034 *
035 * Changes:
036 * --------
037 * 31-Oct-2002 : Version 1 (DG);
038 * 11-Jan-2005 : Minor tidy up (DG);
039 * 28-Sep-2007 : Clean up equals() method (DG);
040 * 03-Oct-2007 : Make method behaviour consistent with DefaultKeyedValues (DG);
041 * 03-Jul-2016 : Use ParamChecks (DG);
042 *
043 */
044
045package org.jfree.data;
046
047import java.io.Serializable;
048import java.util.Iterator;
049import java.util.List;
050import org.jfree.chart.util.Args;
051import org.jfree.chart.util.PublicCloneable;
052
053/**
054 * A collection of (key, object) pairs.
055 */
056public class KeyedObjects implements Cloneable, PublicCloneable, Serializable {
057
058    /** For serialization. */
059    private static final long serialVersionUID = 1321582394193530984L;
060
061    /** Storage for the data. */
062    private List data;
063
064    /**
065     * Creates a new collection (initially empty).
066     */
067    public KeyedObjects() {
068        this.data = new java.util.ArrayList();
069    }
070
071    /**
072     * Returns the number of items (values) in the collection.
073     *
074     * @return The item count.
075     */
076    public int getItemCount() {
077        return this.data.size();
078    }
079
080    /**
081     * Returns an object from the list.
082     *
083     * @param item  the item index (zero-based).
084     *
085     * @return The object (possibly {@code null}).
086     *
087     * @throws IndexOutOfBoundsException if {@code item} is out of bounds.
088     */
089    public Object getObject(int item) {
090        Object result = null;
091        KeyedObject kobj = (KeyedObject) this.data.get(item);
092        if (kobj != null) {
093            result = kobj.getObject();
094        }
095        return result;
096    }
097
098    /**
099     * Returns the key at the specified position in the list.
100     *
101     * @param index  the item index (zero-based).
102     *
103     * @return The row key.
104     *
105     * @throws IndexOutOfBoundsException if {@code item} is out of bounds.
106     *
107     * @see #getIndex(Comparable)
108     */
109    public Comparable getKey(int index) {
110        Comparable result = null;
111        KeyedObject item = (KeyedObject) this.data.get(index);
112        if (item != null) {
113            result = item.getKey();
114        }
115        return result;
116    }
117
118    /**
119     * Returns the index for a given key, or {@code -1}.
120     *
121     * @param key  the key ({@code null} not permitted).
122     *
123     * @return The index, or {@code -1} if the key is unrecognised.
124     *
125     * @see #getKey(int)
126     */
127    public int getIndex(Comparable key) {
128        Args.nullNotPermitted(key, "key");
129        int i = 0;
130        Iterator iterator = this.data.iterator();
131        while (iterator.hasNext()) {
132            KeyedObject ko = (KeyedObject) iterator.next();
133            if (ko.getKey().equals(key)) {
134                return i;
135            }
136            i++;
137        }
138        return -1;
139    }
140
141    /**
142     * Returns a list containing all the keys in the list.
143     *
144     * @return The keys (never {@code null}).
145     */
146    public List getKeys() {
147        List result = new java.util.ArrayList();
148        Iterator iterator = this.data.iterator();
149        while (iterator.hasNext()) {
150            KeyedObject ko = (KeyedObject) iterator.next();
151            result.add(ko.getKey());
152        }
153        return result;
154    }
155
156    /**
157     * Returns the object for a given key. If the key is not recognised, the
158     * method should return {@code null}.
159     *
160     * @param key  the key.
161     *
162     * @return The object (possibly {@code null}).
163     *
164     * @see #addObject(Comparable, Object)
165     */
166    public Object getObject(Comparable key) {
167        int index = getIndex(key);
168        if (index < 0) {
169            throw new UnknownKeyException("The key (" + key
170                    + ") is not recognised.");
171        }
172        return getObject(index);
173    }
174
175    /**
176     * Adds a new object to the collection, or overwrites an existing object.
177     * This is the same as the {@link #setObject(Comparable, Object)} method.
178     *
179     * @param key  the key.
180     * @param object  the object.
181     *
182     * @see #getObject(Comparable)
183     */
184    public void addObject(Comparable key, Object object) {
185        setObject(key, object);
186    }
187
188    /**
189     * Replaces an existing object, or adds a new object to the collection.
190     * This is the same as the {@link #addObject(Comparable, Object)}
191     * method.
192     *
193     * @param key  the key ({@code null} not permitted).
194     * @param object  the object.
195     *
196     * @see #getObject(Comparable)
197     */
198    public void setObject(Comparable key, Object object) {
199        int keyIndex = getIndex(key);
200        if (keyIndex >= 0) {
201            KeyedObject ko = (KeyedObject) this.data.get(keyIndex);
202            ko.setObject(object);
203        }
204        else {
205            KeyedObject ko = new KeyedObject(key, object);
206            this.data.add(ko);
207        }
208    }
209
210    /**
211     * Inserts a new value at the specified position in the dataset or, if
212     * there is an existing item with the specified key, updates the value
213     * for that item and moves it to the specified position.
214     *
215     * @param position  the position (in the range {@code 0} to
216     *                  {@code getItemCount()}).
217     * @param key  the key ({@code null} not permitted).
218     * @param value  the value ({@code null} permitted).
219     *
220     * @since 1.0.7
221     */
222    public void insertValue(int position, Comparable key, Object value) {
223        if (position < 0 || position > this.data.size()) {
224            throw new IllegalArgumentException("'position' out of bounds.");
225        }
226        Args.nullNotPermitted(key, "key");
227        int pos = getIndex(key);
228        if (pos >= 0) {
229            this.data.remove(pos);
230        }
231        KeyedObject item = new KeyedObject(key, value);
232        if (position <= this.data.size()) {
233            this.data.add(position, item);
234        }
235        else {
236            this.data.add(item);
237        }
238    }
239
240    /**
241     * Removes a value from the collection.
242     *
243     * @param index  the index of the item to remove.
244     *
245     * @see #removeValue(Comparable)
246     */
247    public void removeValue(int index) {
248        this.data.remove(index);
249    }
250
251    /**
252     * Removes a value from the collection.
253     *
254     * @param key  the key ({@code null} not permitted).
255     *
256     * @see #removeValue(int)
257     *
258     * @throws UnknownKeyException if the key is not recognised.
259     */
260    public void removeValue(Comparable key) {
261        // defer argument checking
262        int index = getIndex(key);
263        if (index < 0) {
264            throw new UnknownKeyException("The key (" + key.toString()
265                    + ") is not recognised.");
266        }
267        removeValue(index);
268    }
269
270    /**
271     * Clears all values from the collection.
272     *
273     * @since 1.0.7
274     */
275    public void clear() {
276        this.data.clear();
277    }
278
279    /**
280     * Returns a clone of this object.  Keys in the list should be immutable
281     * and are not cloned.  Objects in the list are cloned only if they
282     * implement {@link PublicCloneable}.
283     *
284     * @return A clone.
285     *
286     * @throws CloneNotSupportedException if there is a problem cloning.
287     */
288    @Override
289    public Object clone() throws CloneNotSupportedException {
290        KeyedObjects clone = (KeyedObjects) super.clone();
291        clone.data = new java.util.ArrayList();
292        Iterator iterator = this.data.iterator();
293        while (iterator.hasNext()) {
294            KeyedObject ko = (KeyedObject) iterator.next();
295            clone.data.add(ko.clone());
296        }
297        return clone;
298    }
299
300    /**
301     * Tests this object for equality with an arbitrary object.
302     *
303     * @param obj  the object ({@code null} permitted).
304     *
305     * @return A boolean.
306     */
307    @Override
308    public boolean equals(Object obj) {
309
310        if (obj == this) {
311            return true;
312        }
313        if (!(obj instanceof KeyedObjects)) {
314            return false;
315        }
316        KeyedObjects that = (KeyedObjects) obj;
317        int count = getItemCount();
318        if (count != that.getItemCount()) {
319            return false;
320        }
321
322        for (int i = 0; i < count; i++) {
323            Comparable k1 = getKey(i);
324            Comparable k2 = that.getKey(i);
325            if (!k1.equals(k2)) {
326                return false;
327            }
328            Object o1 = getObject(i);
329            Object o2 = that.getObject(i);
330            if (o1 == null) {
331                if (o2 != null) {
332                    return false;
333                }
334            }
335            else {
336                if (!o1.equals(o2)) {
337                    return false;
338                }
339            }
340        }
341        return true;
342
343    }
344
345    /**
346     * Returns a hash code.
347     *
348     * @return A hash code.
349     */
350    @Override
351    public int hashCode() {
352        return (this.data != null ? this.data.hashCode() : 0);
353    }
354
355}