001 /* ===========================================================
002 * JFreeChart : a free chart library for the Java(tm) platform
003 * ===========================================================
004 *
005 * (C) Copyright 2000-2008, 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 * [Java is a trademark or registered trademark of Sun Microsystems, Inc.
025 * in the United States and other countries.]
026 *
027 * ------------------
028 * KeyedObject2D.java
029 * ------------------
030 * (C) Copyright 2003-2008, by Object Refinery Limited.
031 *
032 * Original Author: David Gilbert (for Object Refinery Limited);
033 * Contributor(s): -;
034 *
035 * Changes
036 * -------
037 * 05-Feb-2003 : Version 1 (DG);
038 * 01-Mar-2004 : Added equals() and clone() methods and implemented
039 * Serializable (DG);
040 * 03-Oct-2007 : Updated getObject() to handle modified behaviour in
041 * KeyedObjects class, added clear() method (DG);
042 *
043 */
044
045 package org.jfree.data;
046
047 import java.io.Serializable;
048 import java.util.Collections;
049 import java.util.Iterator;
050 import java.util.List;
051
052 /**
053 * A data structure that stores zero, one or many objects, where each object is
054 * associated with two keys (a 'row' key and a 'column' key).
055 */
056 public class KeyedObjects2D implements Cloneable, Serializable {
057
058 /** For serialization. */
059 private static final long serialVersionUID = -1015873563138522374L;
060
061 /** The row keys. */
062 private List rowKeys;
063
064 /** The column keys. */
065 private List columnKeys;
066
067 /** The row data. */
068 private List rows;
069
070 /**
071 * Creates a new instance (initially empty).
072 */
073 public KeyedObjects2D() {
074 this.rowKeys = new java.util.ArrayList();
075 this.columnKeys = new java.util.ArrayList();
076 this.rows = new java.util.ArrayList();
077 }
078
079 /**
080 * Returns the row count.
081 *
082 * @return The row count.
083 *
084 * @see #getColumnCount()
085 */
086 public int getRowCount() {
087 return this.rowKeys.size();
088 }
089
090 /**
091 * Returns the column count.
092 *
093 * @return The column count.
094 *
095 * @see #getRowCount()
096 */
097 public int getColumnCount() {
098 return this.columnKeys.size();
099 }
100
101 /**
102 * Returns the object for a given row and column.
103 *
104 * @param row the row index (in the range 0 to getRowCount() - 1).
105 * @param column the column index (in the range 0 to getColumnCount() - 1).
106 *
107 * @return The object (possibly <code>null</code>).
108 *
109 * @see #getObject(Comparable, Comparable)
110 */
111 public Object getObject(int row, int column) {
112 Object result = null;
113 KeyedObjects rowData = (KeyedObjects) this.rows.get(row);
114 if (rowData != null) {
115 Comparable columnKey = (Comparable) this.columnKeys.get(column);
116 if (columnKey != null) {
117 int index = rowData.getIndex(columnKey);
118 if (index >= 0) {
119 result = rowData.getObject(columnKey);
120 }
121 }
122 }
123 return result;
124 }
125
126 /**
127 * Returns the key for a given row.
128 *
129 * @param row the row index (zero based).
130 *
131 * @return The row index.
132 *
133 * @see #getRowIndex(Comparable)
134 */
135 public Comparable getRowKey(int row) {
136 return (Comparable) this.rowKeys.get(row);
137 }
138
139 /**
140 * Returns the row index for a given key, or <code>-1</code> if the key
141 * is not recognised.
142 *
143 * @param key the key (<code>null</code> not permitted).
144 *
145 * @return The row index.
146 *
147 * @see #getRowKey(int)
148 */
149 public int getRowIndex(Comparable key) {
150 if (key == null) {
151 throw new IllegalArgumentException("Null 'key' argument.");
152 }
153 return this.rowKeys.indexOf(key);
154 }
155
156 /**
157 * Returns the row keys.
158 *
159 * @return The row keys (never <code>null</code>).
160 *
161 * @see #getRowKeys()
162 */
163 public List getRowKeys() {
164 return Collections.unmodifiableList(this.rowKeys);
165 }
166
167 /**
168 * Returns the key for a given column.
169 *
170 * @param column the column.
171 *
172 * @return The key.
173 *
174 * @see #getColumnIndex(Comparable)
175 */
176 public Comparable getColumnKey(int column) {
177 return (Comparable) this.columnKeys.get(column);
178 }
179
180 /**
181 * Returns the column index for a given key, or <code>-1</code> if the key
182 * is not recognised.
183 *
184 * @param key the key (<code>null</code> not permitted).
185 *
186 * @return The column index.
187 *
188 * @see #getColumnKey(int)
189 */
190 public int getColumnIndex(Comparable key) {
191 if (key == null) {
192 throw new IllegalArgumentException("Null 'key' argument.");
193 }
194 return this.columnKeys.indexOf(key);
195 }
196
197 /**
198 * Returns the column keys.
199 *
200 * @return The column keys (never <code>null</code>).
201 *
202 * @see #getRowKeys()
203 */
204 public List getColumnKeys() {
205 return Collections.unmodifiableList(this.columnKeys);
206 }
207
208 /**
209 * Returns the object for the given row and column keys.
210 *
211 * @param rowKey the row key (<code>null</code> not permitted).
212 * @param columnKey the column key (<code>null</code> not permitted).
213 *
214 * @return The object (possibly <code>null</code>).
215 *
216 * @throws IllegalArgumentException if <code>rowKey<code> or
217 * <code>columnKey</code> is <code>null</code>.
218 * @throws UnknownKeyException if <code>rowKey</code> or
219 * <code>columnKey</code> is not recognised.
220 */
221 public Object getObject(Comparable rowKey, Comparable columnKey) {
222 if (rowKey == null) {
223 throw new IllegalArgumentException("Null 'rowKey' argument.");
224 }
225 if (columnKey == null) {
226 throw new IllegalArgumentException("Null 'columnKey' argument.");
227 }
228 int row = this.rowKeys.indexOf(rowKey);
229 if (row < 0) {
230 throw new UnknownKeyException("Row key (" + rowKey
231 + ") not recognised.");
232 }
233 int column = this.columnKeys.indexOf(columnKey);
234 if (column < 0) {
235 throw new UnknownKeyException("Column key (" + columnKey
236 + ") not recognised.");
237 }
238 KeyedObjects rowData = (KeyedObjects) this.rows.get(row);
239 int index = rowData.getIndex(columnKey);
240 if (index >= 0) {
241 return rowData.getObject(index);
242 }
243 else {
244 return null;
245 }
246 }
247
248 /**
249 * Adds an object to the table. Performs the same function as setObject().
250 *
251 * @param object the object.
252 * @param rowKey the row key (<code>null</code> not permitted).
253 * @param columnKey the column key (<code>null</code> not permitted).
254 */
255 public void addObject(Object object, Comparable rowKey,
256 Comparable columnKey) {
257 setObject(object, rowKey, columnKey);
258 }
259
260 /**
261 * Adds or updates an object.
262 *
263 * @param object the object.
264 * @param rowKey the row key (<code>null</code> not permitted).
265 * @param columnKey the column key (<code>null</code> not permitted).
266 */
267 public void setObject(Object object, Comparable rowKey,
268 Comparable columnKey) {
269
270 if (rowKey == null) {
271 throw new IllegalArgumentException("Null 'rowKey' argument.");
272 }
273 if (columnKey == null) {
274 throw new IllegalArgumentException("Null 'columnKey' argument.");
275 }
276 KeyedObjects row;
277 int rowIndex = this.rowKeys.indexOf(rowKey);
278 if (rowIndex >= 0) {
279 row = (KeyedObjects) this.rows.get(rowIndex);
280 }
281 else {
282 this.rowKeys.add(rowKey);
283 row = new KeyedObjects();
284 this.rows.add(row);
285 }
286 row.setObject(columnKey, object);
287 int columnIndex = this.columnKeys.indexOf(columnKey);
288 if (columnIndex < 0) {
289 this.columnKeys.add(columnKey);
290 }
291
292 }
293
294 /**
295 * Removes an object from the table by setting it to <code>null</code>. If
296 * all the objects in the specified row and/or column are now
297 * <code>null</code>, the row and/or column is removed from the table.
298 *
299 * @param rowKey the row key (<code>null</code> not permitted).
300 * @param columnKey the column key (<code>null</code> not permitted).
301 *
302 * @see #addObject(Object, Comparable, Comparable)
303 */
304 public void removeObject(Comparable rowKey, Comparable columnKey) {
305 int rowIndex = getRowIndex(rowKey);
306 if (rowIndex < 0) {
307 throw new UnknownKeyException("Row key (" + rowKey
308 + ") not recognised.");
309 }
310 int columnIndex = getColumnIndex(columnKey);
311 if (columnIndex < 0) {
312 throw new UnknownKeyException("Column key (" + columnKey
313 + ") not recognised.");
314 }
315 setObject(null, rowKey, columnKey);
316
317 // 1. check whether the row is now empty.
318 boolean allNull = true;
319 KeyedObjects row = (KeyedObjects) this.rows.get(rowIndex);
320
321 for (int item = 0, itemCount = row.getItemCount(); item < itemCount;
322 item++) {
323 if (row.getObject(item) != null) {
324 allNull = false;
325 break;
326 }
327 }
328
329 if (allNull) {
330 this.rowKeys.remove(rowIndex);
331 this.rows.remove(rowIndex);
332 }
333
334 // 2. check whether the column is now empty.
335 allNull = true;
336
337 for (int item = 0, itemCount = this.rows.size(); item < itemCount;
338 item++) {
339 row = (KeyedObjects) this.rows.get(item);
340 int colIndex = row.getIndex(columnKey);
341 if (colIndex >= 0 && row.getObject(colIndex) != null) {
342 allNull = false;
343 break;
344 }
345 }
346
347 if (allNull) {
348 for (int item = 0, itemCount = this.rows.size(); item < itemCount;
349 item++) {
350 row = (KeyedObjects) this.rows.get(item);
351 int colIndex = row.getIndex(columnKey);
352 if (colIndex >= 0) {
353 row.removeValue(colIndex);
354 }
355 }
356 this.columnKeys.remove(columnKey);
357 }
358 }
359
360 /**
361 * Removes an entire row from the table.
362 *
363 * @param rowIndex the row index.
364 *
365 * @see #removeColumn(int)
366 */
367 public void removeRow(int rowIndex) {
368 this.rowKeys.remove(rowIndex);
369 this.rows.remove(rowIndex);
370 }
371
372 /**
373 * Removes an entire row from the table.
374 *
375 * @param rowKey the row key (<code>null</code> not permitted).
376 *
377 * @throws UnknownKeyException if <code>rowKey</code> is not recognised.
378 *
379 * @see #removeColumn(Comparable)
380 */
381 public void removeRow(Comparable rowKey) {
382 int index = getRowIndex(rowKey);
383 if (index < 0) {
384 throw new UnknownKeyException("Row key (" + rowKey
385 + ") not recognised.");
386 }
387 removeRow(index);
388 }
389
390 /**
391 * Removes an entire column from the table.
392 *
393 * @param columnIndex the column index.
394 *
395 * @see #removeRow(int)
396 */
397 public void removeColumn(int columnIndex) {
398 Comparable columnKey = getColumnKey(columnIndex);
399 removeColumn(columnKey);
400 }
401
402 /**
403 * Removes an entire column from the table.
404 *
405 * @param columnKey the column key (<code>null</code> not permitted).
406 *
407 * @throws UnknownKeyException if <code>rowKey</code> is not recognised.
408 *
409 * @see #removeRow(Comparable)
410 */
411 public void removeColumn(Comparable columnKey) {
412 int index = getColumnIndex(columnKey);
413 if (index < 0) {
414 throw new UnknownKeyException("Column key (" + columnKey
415 + ") not recognised.");
416 }
417 Iterator iterator = this.rows.iterator();
418 while (iterator.hasNext()) {
419 KeyedObjects rowData = (KeyedObjects) iterator.next();
420 int i = rowData.getIndex(columnKey);
421 if (i >= 0) {
422 rowData.removeValue(i);
423 }
424 }
425 this.columnKeys.remove(columnKey);
426 }
427
428 /**
429 * Clears all the data and associated keys.
430 *
431 * @since 1.0.7
432 */
433 public void clear() {
434 this.rowKeys.clear();
435 this.columnKeys.clear();
436 this.rows.clear();
437 }
438
439 /**
440 * Tests this object for equality with an arbitrary object.
441 *
442 * @param obj the object to test (<code>null</code> permitted).
443 *
444 * @return A boolean.
445 */
446 public boolean equals(Object obj) {
447 if (obj == this) {
448 return true;
449 }
450 if (!(obj instanceof KeyedObjects2D)) {
451 return false;
452 }
453
454 KeyedObjects2D that = (KeyedObjects2D) obj;
455 if (!getRowKeys().equals(that.getRowKeys())) {
456 return false;
457 }
458 if (!getColumnKeys().equals(that.getColumnKeys())) {
459 return false;
460 }
461 int rowCount = getRowCount();
462 if (rowCount != that.getRowCount()) {
463 return false;
464 }
465 int colCount = getColumnCount();
466 if (colCount != that.getColumnCount()) {
467 return false;
468 }
469 for (int r = 0; r < rowCount; r++) {
470 for (int c = 0; c < colCount; c++) {
471 Object v1 = getObject(r, c);
472 Object v2 = that.getObject(r, c);
473 if (v1 == null) {
474 if (v2 != null) {
475 return false;
476 }
477 }
478 else {
479 if (!v1.equals(v2)) {
480 return false;
481 }
482 }
483 }
484 }
485 return true;
486 }
487
488 /**
489 * Returns a hashcode for this object.
490 *
491 * @return A hashcode.
492 */
493 public int hashCode() {
494 int result;
495 result = this.rowKeys.hashCode();
496 result = 29 * result + this.columnKeys.hashCode();
497 result = 29 * result + this.rows.hashCode();
498 return result;
499 }
500
501 /**
502 * Returns a clone.
503 *
504 * @return A clone.
505 *
506 * @throws CloneNotSupportedException this class will not throw this
507 * exception, but subclasses (if any) might.
508 */
509 public Object clone() throws CloneNotSupportedException {
510 KeyedObjects2D clone = (KeyedObjects2D) super.clone();
511 clone.columnKeys = new java.util.ArrayList(this.columnKeys);
512 clone.rowKeys = new java.util.ArrayList(this.rowKeys);
513 clone.rows = new java.util.ArrayList(this.rows.size());
514 Iterator iterator = this.rows.iterator();
515 while (iterator.hasNext()) {
516 KeyedObjects row = (KeyedObjects) iterator.next();
517 clone.rows.add(row.clone());
518 }
519 return clone;
520 }
521
522 }