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}