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 * DefaultKeyedValues.java 029 * ----------------------- 030 * (C) Copyright 2002-2016, by Object Refinery Limited. 031 * 032 * Original Author: David Gilbert (for Object Refinery Limited); 033 * Contributor(s): Thomas Morgner; 034 * 035 * Changes: 036 * -------- 037 * 31-Oct-2002 : Version 1 (DG); 038 * 11-Feb-2003 : Fixed bug in getValue(key) method for unrecognised key (DG); 039 * 05-Mar-2003 : Added methods to sort stored data 'by key' or 'by value' (DG); 040 * 13-Mar-2003 : Implemented Serializable (DG); 041 * 08-Apr-2003 : Modified removeValue(Comparable) method to fix bug 717049 (DG); 042 * 18-Aug-2003 : Implemented Cloneable (DG); 043 * 27-Aug-2003 : Moved SortOrder from org.jfree.data --> org.jfree.util (DG); 044 * 09-Feb-2004 : Modified getIndex() method - see bug report 893256 (DG); 045 * 15-Sep-2004 : Updated clone() method and added PublicCloneable 046 * interface (DG); 047 * 25-Nov-2004 : Small update to the clone() implementation (DG); 048 * 24-Feb-2005 : Added methods addValue(Comparable, double) and 049 * setValue(Comparable, double) for convenience (DG); 050 * ------------- JFREECHART 1.0.x --------------------------------------------- 051 * 31-Jul-2006 : Added a clear() method (DG); 052 * 01-Aug-2006 : Added argument check to getIndex() method (DG); 053 * 30-Apr-2007 : Added insertValue() methods (DG); 054 * 31-Oct-2007 : Performance improvements by using separate lists for keys and 055 * values (TM); 056 * 21-Nov-2007 : Fixed bug in removeValue() method from previous patch (DG); 057 * 03-Jul-2013 : Use ParamChecks (DG); 058 * 059 */ 060 061package org.jfree.data; 062 063import java.io.Serializable; 064import java.util.ArrayList; 065import java.util.Arrays; 066import java.util.Comparator; 067import java.util.HashMap; 068import java.util.List; 069import org.jfree.chart.util.Args; 070import org.jfree.chart.util.PublicCloneable; 071import org.jfree.chart.util.SortOrder; 072 073/** 074 * An ordered list of (key, value) items. This class provides a default 075 * implementation of the {@link KeyedValues} interface. 076 */ 077public class DefaultKeyedValues implements KeyedValues, Cloneable, 078 PublicCloneable, Serializable { 079 080 /** For serialization. */ 081 private static final long serialVersionUID = 8468154364608194797L; 082 083 /** Storage for the keys. */ 084 private ArrayList keys; 085 086 /** Storage for the values. */ 087 private ArrayList values; 088 089 /** 090 * Contains (key, Integer) mappings, where the Integer is the index for 091 * the key in the list. 092 */ 093 private HashMap indexMap; 094 095 /** 096 * Creates a new collection (initially empty). 097 */ 098 public DefaultKeyedValues() { 099 this.keys = new ArrayList(); 100 this.values = new ArrayList(); 101 this.indexMap = new HashMap(); 102 } 103 104 /** 105 * Returns the number of items (values) in the collection. 106 * 107 * @return The item count. 108 */ 109 @Override 110 public int getItemCount() { 111 return this.indexMap.size(); 112 } 113 114 /** 115 * Returns a value. 116 * 117 * @param item the item of interest (zero-based index). 118 * 119 * @return The value (possibly {@code null}). 120 * 121 * @throws IndexOutOfBoundsException if {@code item} is out of bounds. 122 */ 123 @Override 124 public Number getValue(int item) { 125 return (Number) this.values.get(item); 126 } 127 128 /** 129 * Returns a key. 130 * 131 * @param index the item index (zero-based). 132 * 133 * @return The row key. 134 * 135 * @throws IndexOutOfBoundsException if {@code item} is out of bounds. 136 */ 137 @Override 138 public Comparable getKey(int index) { 139 return (Comparable) this.keys.get(index); 140 } 141 142 /** 143 * Returns the index for a given key. 144 * 145 * @param key the key ({@code null} not permitted). 146 * 147 * @return The index, or {@code -1} if the key is not recognised. 148 * 149 * @throws IllegalArgumentException if {@code key} is 150 * {@code null}. 151 */ 152 @Override 153 public int getIndex(Comparable key) { 154 Args.nullNotPermitted(key, "key"); 155 final Integer i = (Integer) this.indexMap.get(key); 156 if (i == null) { 157 return -1; // key not found 158 } 159 return i; 160 } 161 162 /** 163 * Returns the keys for the values in the collection. 164 * 165 * @return The keys (never {@code null}). 166 */ 167 @Override 168 public List getKeys() { 169 return (List) this.keys.clone(); 170 } 171 172 /** 173 * Returns the value for a given key. 174 * 175 * @param key the key ({@code null} not permitted). 176 * 177 * @return The value (possibly {@code null}). 178 * 179 * @throws UnknownKeyException if the key is not recognised. 180 * 181 * @see #getValue(int) 182 */ 183 @Override 184 public Number getValue(Comparable key) { 185 int index = getIndex(key); 186 if (index < 0) { 187 throw new UnknownKeyException("Key not found: " + key); 188 } 189 return getValue(index); 190 } 191 192 /** 193 * Updates an existing value, or adds a new value to the collection. 194 * 195 * @param key the key ({@code null} not permitted). 196 * @param value the value. 197 * 198 * @see #addValue(Comparable, Number) 199 */ 200 public void addValue(Comparable key, double value) { 201 addValue(key, Double.valueOf(value)); 202 } 203 204 /** 205 * Adds a new value to the collection, or updates an existing value. 206 * This method passes control directly to the 207 * {@link #setValue(Comparable, Number)} method. 208 * 209 * @param key the key ({@code null} not permitted). 210 * @param value the value ({@code null} permitted). 211 */ 212 public void addValue(Comparable key, Number value) { 213 setValue(key, 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} not permitted). 220 * @param value the value. 221 */ 222 public void setValue(Comparable key, double value) { 223 setValue(key, Double.valueOf(value)); 224 } 225 226 /** 227 * Updates an existing value, or adds a new value to the collection. 228 * 229 * @param key the key ({@code null} not permitted). 230 * @param value the value ({@code null} permitted). 231 */ 232 public void setValue(Comparable key, Number value) { 233 Args.nullNotPermitted(key, "key"); 234 int keyIndex = getIndex(key); 235 if (keyIndex >= 0) { 236 this.keys.set(keyIndex, key); 237 this.values.set(keyIndex, value); 238 } 239 else { 240 this.keys.add(key); 241 this.values.add(value); 242 this.indexMap.put(key, this.keys.size() - 1); 243 } 244 } 245 246 /** 247 * Inserts a new value at the specified position in the dataset or, if 248 * there is an existing item with the specified key, updates the value 249 * for that item and moves it to the specified position. 250 * 251 * @param position the position (in the range 0 to getItemCount()). 252 * @param key the key ({@code null} not permitted). 253 * @param value the value. 254 * 255 * @since 1.0.6 256 */ 257 public void insertValue(int position, Comparable key, double value) { 258 insertValue(position, key, Double.valueOf(value)); 259 } 260 261 /** 262 * Inserts a new value at the specified position in the dataset or, if 263 * there is an existing item with the specified key, updates the value 264 * for that item and moves it to the specified position. 265 * 266 * @param position the position (in the range 0 to getItemCount()). 267 * @param key the key ({@code null} not permitted). 268 * @param value the value ({@code null} permitted). 269 * 270 * @since 1.0.6 271 */ 272 public void insertValue(int position, Comparable key, Number value) { 273 if (position < 0 || position > getItemCount()) { 274 throw new IllegalArgumentException("'position' out of bounds."); 275 } 276 Args.nullNotPermitted(key, "key"); 277 int pos = getIndex(key); 278 if (pos == position) { 279 this.keys.set(pos, key); 280 this.values.set(pos, value); 281 } 282 else { 283 if (pos >= 0) { 284 this.keys.remove(pos); 285 this.values.remove(pos); 286 } 287 288 this.keys.add(position, key); 289 this.values.add(position, value); 290 rebuildIndex(); 291 } 292 } 293 294 /** 295 * Rebuilds the key to indexed-position mapping after an positioned insert 296 * or a remove operation. 297 */ 298 private void rebuildIndex () { 299 this.indexMap.clear(); 300 for (int i = 0; i < this.keys.size(); i++) { 301 final Object key = this.keys.get(i); 302 this.indexMap.put(key, i); 303 } 304 } 305 306 /** 307 * Removes a value from the collection. 308 * 309 * @param index the index of the item to remove (in the range 310 * {@code 0} to {@code getItemCount() -1}). 311 * 312 * @throws IndexOutOfBoundsException if {@code index} is not within 313 * the specified range. 314 */ 315 public void removeValue(int index) { 316 this.keys.remove(index); 317 this.values.remove(index); 318 rebuildIndex(); 319 } 320 321 /** 322 * Removes a value from the collection. 323 * 324 * @param key the item key ({@code null} not permitted). 325 * 326 * @throws IllegalArgumentException if {@code key} is 327 * {@code null}. 328 * @throws UnknownKeyException if {@code key} is not recognised. 329 */ 330 public void removeValue(Comparable key) { 331 int index = getIndex(key); 332 if (index < 0) { 333 throw new UnknownKeyException("The key (" + key 334 + ") is not recognised."); 335 } 336 removeValue(index); 337 } 338 339 /** 340 * Clears all values from the collection. 341 * 342 * @since 1.0.2 343 */ 344 public void clear() { 345 this.keys.clear(); 346 this.values.clear(); 347 this.indexMap.clear(); 348 } 349 350 /** 351 * Sorts the items in the list by key. 352 * 353 * @param order the sort order ({@code null} not permitted). 354 */ 355 public void sortByKeys(SortOrder order) { 356 final int size = this.keys.size(); 357 final DefaultKeyedValue[] data = new DefaultKeyedValue[size]; 358 359 for (int i = 0; i < size; i++) { 360 data[i] = new DefaultKeyedValue((Comparable) this.keys.get(i), 361 (Number) this.values.get(i)); 362 } 363 364 Comparator comparator = new KeyedValueComparator( 365 KeyedValueComparatorType.BY_KEY, order); 366 Arrays.sort(data, comparator); 367 clear(); 368 369 for (int i = 0; i < data.length; i++) { 370 final DefaultKeyedValue value = data[i]; 371 addValue(value.getKey(), value.getValue()); 372 } 373 } 374 375 /** 376 * Sorts the items in the list by value. If the list contains 377 * {@code null} values, they will sort to the end of the list, 378 * irrespective of the sort order. 379 * 380 * @param order the sort order ({@code null} not permitted). 381 */ 382 public void sortByValues(SortOrder order) { 383 final int size = this.keys.size(); 384 final DefaultKeyedValue[] data = new DefaultKeyedValue[size]; 385 for (int i = 0; i < size; i++) { 386 data[i] = new DefaultKeyedValue((Comparable) this.keys.get(i), 387 (Number) this.values.get(i)); 388 } 389 390 Comparator comparator = new KeyedValueComparator( 391 KeyedValueComparatorType.BY_VALUE, order); 392 Arrays.sort(data, comparator); 393 394 clear(); 395 for (int i = 0; i < data.length; i++) { 396 final DefaultKeyedValue value = data[i]; 397 addValue(value.getKey(), value.getValue()); 398 } 399 } 400 401 /** 402 * Tests if this object is equal to another. 403 * 404 * @param obj the object ({@code null} permitted). 405 * 406 * @return A boolean. 407 */ 408 @Override 409 public boolean equals(Object obj) { 410 if (obj == this) { 411 return true; 412 } 413 414 if (!(obj instanceof KeyedValues)) { 415 return false; 416 } 417 418 KeyedValues that = (KeyedValues) obj; 419 int count = getItemCount(); 420 if (count != that.getItemCount()) { 421 return false; 422 } 423 424 for (int i = 0; i < count; i++) { 425 Comparable k1 = getKey(i); 426 Comparable k2 = that.getKey(i); 427 if (!k1.equals(k2)) { 428 return false; 429 } 430 Number v1 = getValue(i); 431 Number v2 = that.getValue(i); 432 if (v1 == null) { 433 if (v2 != null) { 434 return false; 435 } 436 } 437 else { 438 if (!v1.equals(v2)) { 439 return false; 440 } 441 } 442 } 443 return true; 444 } 445 446 /** 447 * Returns a hash code. 448 * 449 * @return A hash code. 450 */ 451 @Override 452 public int hashCode() { 453 return (this.keys != null ? this.keys.hashCode() : 0); 454 } 455 456 /** 457 * Returns a clone. 458 * 459 * @return A clone. 460 * 461 * @throws CloneNotSupportedException this class will not throw this 462 * exception, but subclasses might. 463 */ 464 @Override 465 public Object clone() throws CloneNotSupportedException { 466 DefaultKeyedValues clone = (DefaultKeyedValues) super.clone(); 467 clone.keys = (ArrayList) this.keys.clone(); 468 clone.values = (ArrayList) this.values.clone(); 469 clone.indexMap = (HashMap) this.indexMap.clone(); 470 return clone; 471 } 472 473}