KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > jfree > data > DefaultKeyedValues


1 /* ===========================================================
2  * JFreeChart : a free chart library for the Java(tm) platform
3  * ===========================================================
4  *
5  * (C) Copyright 2000-2005, by Object Refinery Limited and Contributors.
6  *
7  * Project Info: http://www.jfree.org/jfreechart/index.html
8  *
9  * This library is free software; you can redistribute it and/or modify it
10  * under the terms of the GNU Lesser General Public License as published by
11  * the Free Software Foundation; either version 2.1 of the License, or
12  * (at your option) any later version.
13  *
14  * This library is distributed in the hope that it will be useful, but
15  * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
16  * or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public
17  * License for more details.
18  *
19  * You should have received a copy of the GNU Lesser General Public License
20  * along with this library; if not, write to the Free Software Foundation,
21  * Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307, USA.
22  *
23  * [Java is a trademark or registered trademark of Sun Microsystems, Inc.
24  * in the United States and other countries.]
25  *
26  * -----------------------
27  * DefaultKeyedValues.java
28  * -----------------------
29  * (C) Copyright 2002-2005, by Object Refinery Limited.
30  *
31  * Original Author: David Gilbert (for Object Refinery Limited);
32  * Contributor(s): -;
33  *
34  * $Id: DefaultKeyedValues.java,v 1.8 2005/05/19 10:34:07 mungady Exp $
35  *
36  * Changes:
37  * --------
38  * 31-Oct-2002 : Version 1 (DG);
39  * 11-Feb-2003 : Fixed bug in getValue(key) method for unrecognised key (DG);
40  * 05-Mar-2003 : Added methods to sort stored data 'by key' or 'by value' (DG);
41  * 13-Mar-2003 : Implemented Serializable (DG);
42  * 08-Apr-2003 : Modified removeValue(Comparable) method to fix bug 717049 (DG);
43  * 18-Aug-2003 : Implemented Cloneable (DG);
44  * 27-Aug-2003 : Moved SortOrder from org.jfree.data --> org.jfree.util (DG);
45  * 09-Feb-2004 : Modified getIndex() method - see bug report 893256 (DG);
46  * 15-Sep-2004 : Updated clone() method and added PublicCloneable
47  * interface (DG);
48  * 25-Nov-2004 : Small update to the clone() implementation (DG);
49  * 24-Feb-2005 : Added methods addValue(Comparable, double) and
50  * setValue(Comparable, double) for convenience (DG);
51  *
52  */

53
54 package org.jfree.data;
55
56 import java.io.Serializable JavaDoc;
57 import java.util.Collections JavaDoc;
58 import java.util.Comparator JavaDoc;
59 import java.util.Iterator JavaDoc;
60 import java.util.List JavaDoc;
61
62 import org.jfree.util.ObjectUtilities;
63 import org.jfree.util.PublicCloneable;
64 import org.jfree.util.SortOrder;
65
66 /**
67  * An ordered list of (key, value) items. This class provides a default
68  * implementation of the {@link KeyedValues} interface.
69  */

70 public class DefaultKeyedValues implements KeyedValues,
71                                            Cloneable JavaDoc, PublicCloneable,
72                                            Serializable JavaDoc {
73
74     /** For serialization. */
75     private static final long serialVersionUID = 8468154364608194797L;
76     
77     /** Storage for the data. */
78     private List JavaDoc data;
79
80     /**
81      * Creates a new collection (initially empty).
82      */

83     public DefaultKeyedValues() {
84         this.data = new java.util.ArrayList JavaDoc();
85     }
86
87     /**
88      * Returns the number of items (values) in the collection.
89      *
90      * @return The item count.
91      */

92     public int getItemCount() {
93         return this.data.size();
94     }
95
96     /**
97      * Returns a value.
98      *
99      * @param item the item of interest (zero-based index).
100      *
101      * @return The value.
102      *
103      * @throws IndexOutOfBoundsException if <code>item</code> is out of bounds.
104      */

105     public Number JavaDoc getValue(int item) {
106         Number JavaDoc result = null;
107         KeyedValue kval = (KeyedValue) this.data.get(item);
108         if (kval != null) {
109             result = kval.getValue();
110         }
111         return result;
112     }
113
114     /**
115      * Returns a key.
116      *
117      * @param index the item index (zero-based).
118      *
119      * @return The row key.
120      *
121      * @throws IndexOutOfBoundsException if <code>item</code> is out of bounds.
122      */

123     public Comparable JavaDoc getKey(int index) {
124         Comparable JavaDoc result = null;
125         KeyedValue item = (KeyedValue) this.data.get(index);
126         if (item != null) {
127             result = item.getKey();
128         }
129         return result;
130     }
131
132     /**
133      * Returns the index for a given key.
134      *
135      * @param key the key.
136      *
137      * @return The index, or <code>-1</code> if the key is unrecognised.
138      */

139     public int getIndex(Comparable JavaDoc key) {
140         int i = 0;
141         Iterator JavaDoc iterator = this.data.iterator();
142         while (iterator.hasNext()) {
143             KeyedValue kv = (KeyedValue) iterator.next();
144             if (kv.getKey().equals(key)) {
145                 return i;
146             }
147             i++;
148         }
149         return -1; // key not found
150
}
151
152     /**
153      * Returns the keys for the values in the collection.
154      *
155      * @return The keys (never <code>null</code>).
156      */

157     public List JavaDoc getKeys() {
158         List JavaDoc result = new java.util.ArrayList JavaDoc();
159         Iterator JavaDoc iterator = this.data.iterator();
160         while (iterator.hasNext()) {
161             KeyedValue kv = (KeyedValue) iterator.next();
162             result.add(kv.getKey());
163         }
164         return result;
165     }
166
167     /**
168      * Returns the value for a given key.
169      *
170      * @param key the key.
171      *
172      * @return The value (possibly <code>null</code>).
173      *
174      * @throws UnknownKeyException if the key is not recognised.
175      */

176     public Number JavaDoc getValue(Comparable JavaDoc key) {
177         int index = getIndex(key);
178         if (index < 0) {
179             throw new UnknownKeyException("Key not found: " + key);
180         }
181         return getValue(index);
182     }
183
184     /**
185      * Updates an existing value, or adds a new value to the collection.
186      *
187      * @param key the key (<code>null</code> not permitted).
188      * @param value the value.
189      */

190     public void addValue(Comparable JavaDoc key, double value) {
191         addValue(key, new Double JavaDoc(value));
192     }
193     
194     /**
195      * Adds a new value to the collection, or updates an existing value.
196      * This method passes control directly to the
197      * {@link #setValue(Comparable, Number)} method.
198      *
199      * @param key the key (<code>null</code> not permitted).
200      * @param value the value (<code>null</code> permitted).
201      */

202     public void addValue(Comparable JavaDoc key, Number JavaDoc value) {
203         setValue(key, value);
204     }
205
206     /**
207      * Updates an existing value, or adds a new value to the collection.
208      *
209      * @param key the key (<code>null</code> not permitted).
210      * @param value the value.
211      */

212     public void setValue(Comparable JavaDoc key, double value) {
213         setValue(key, new Double JavaDoc(value));
214     }
215     
216     /**
217      * Updates an existing value, or adds a new value to the collection.
218      *
219      * @param key the key (<code>null</code> not permitted).
220      * @param value the value (<code>null</code> permitted).
221      */

222     public void setValue(Comparable JavaDoc key, Number JavaDoc value) {
223         if (key == null) {
224             throw new IllegalArgumentException JavaDoc("Null 'key' argument.");
225         }
226         int keyIndex = getIndex(key);
227         if (keyIndex >= 0) {
228             DefaultKeyedValue kv = (DefaultKeyedValue) this.data.get(keyIndex);
229             kv.setValue(value);
230         }
231         else {
232             KeyedValue kv = new DefaultKeyedValue(key, value);
233             this.data.add(kv);
234         }
235     }
236
237     /**
238      * Removes a value from the collection.
239      *
240      * @param index the index of the item to remove.
241      */

242     public void removeValue(int index) {
243         this.data.remove(index);
244     }
245
246     /**
247      * Removes a value from the collection.
248      *
249      * @param key the item key.
250      *
251      * @throws UnknownKeyException if the key is not recognised.
252      */

253     public void removeValue(Comparable JavaDoc key) {
254         int index = getIndex(key);
255         if (index >= 0) {
256             removeValue(index);
257         }
258     }
259
260     /**
261      * Sorts the items in the list by key.
262      *
263      * @param order the sort order (<code>null</code> not permitted).
264      */

265     public void sortByKeys(SortOrder order) {
266         Comparator JavaDoc comparator = new KeyedValueComparator(
267             KeyedValueComparatorType.BY_KEY, order
268         );
269         Collections.sort(this.data, comparator);
270     }
271
272     /**
273      * Sorts the items in the list by value. If the list contains
274      * <code>null</code> values, they will sort to the end of the list,
275      * irrespective of the sort order.
276      *
277      * @param order the sort order (<code>null</code> not permitted).
278      */

279     public void sortByValues(SortOrder order) {
280         Comparator JavaDoc comparator = new KeyedValueComparator(
281             KeyedValueComparatorType.BY_VALUE, order
282         );
283         Collections.sort(this.data, comparator);
284     }
285
286     /**
287      * Tests if this object is equal to another.
288      *
289      * @param obj the object (<code>null</code> permitted).
290      *
291      * @return A boolean.
292      */

293     public boolean equals(Object JavaDoc obj) {
294         if (obj == this) {
295             return true;
296         }
297
298         if (!(obj instanceof KeyedValues)) {
299             return false;
300         }
301
302         KeyedValues that = (KeyedValues) obj;
303         int count = getItemCount();
304         if (count != that.getItemCount()) {
305             return false;
306         }
307
308         for (int i = 0; i < count; i++) {
309             Comparable JavaDoc k1 = getKey(i);
310             Comparable JavaDoc k2 = that.getKey(i);
311             if (!k1.equals(k2)) {
312                 return false;
313             }
314             Number JavaDoc v1 = getValue(i);
315             Number JavaDoc v2 = that.getValue(i);
316             if (v1 == null) {
317                 if (v2 != null) {
318                     return false;
319                 }
320             }
321             else {
322                 if (!v1.equals(v2)) {
323                     return false;
324                 }
325             }
326         }
327         return true;
328     }
329
330     /**
331      * Returns a hash code.
332      *
333      * @return A hash code.
334      */

335     public int hashCode() {
336         return (this.data != null ? this.data.hashCode() : 0);
337     }
338
339     /**
340      * Returns a clone.
341      *
342      * @return A clone.
343      *
344      * @throws CloneNotSupportedException this class will not throw this
345      * exception, but subclasses might.
346      */

347     public Object JavaDoc clone() throws CloneNotSupportedException JavaDoc {
348         DefaultKeyedValues clone = (DefaultKeyedValues) super.clone();
349         clone.data = (List JavaDoc) ObjectUtilities.deepClone(this.data);
350         return clone;
351     }
352     
353 }
354
Popular Tags