Source for org.jfree.data.time.TimeTableXYDataset

   1: /* ===========================================================
   2:  * JFreeChart : a free chart library for the Java(tm) platform
   3:  * ===========================================================
   4:  *
   5:  * (C) Copyright 2000-2007, 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
  20:  * License along with this library; if not, write to the Free Software
  21:  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, 
  22:  * USA.  
  23:  *
  24:  * [Java is a trademark or registered trademark of Sun Microsystems, Inc. 
  25:  * in the United States and other countries.]
  26:  *
  27:  * -----------------------
  28:  * TimeTableXYDataset.java
  29:  * -----------------------
  30:  * (C) Copyright 2004, 2005, 2007, by Andreas Schroeder and Contributors.
  31:  *
  32:  * Original Author:  Andreas Schroeder;
  33:  * Contributor(s):   David Gilbert (for Object Refinery Limited);
  34:  *                   Rob Eden;
  35:  *
  36:  * Changes
  37:  * -------
  38:  * 01-Apr-2004 : Version 1 (AS);
  39:  * 05-May-2004 : Now implements AbstractIntervalXYDataset (DG);
  40:  * 15-Jul-2004 : Switched getX() with getXValue() and getY() with 
  41:  *               getYValue() (DG);
  42:  * 15-Sep-2004 : Added getXPosition(), setXPosition(), equals() and 
  43:  *               clone() (DG);
  44:  * 17-Nov-2004 : Updated methods for changes in DomainInfo interface (DG);
  45:  * 25-Nov-2004 : Added getTimePeriod(int) method (DG);
  46:  * 11-Jan-2005 : Removed deprecated code in preparation for the 1.0.0 
  47:  *               release (DG);
  48:  * 27-Jan-2005 : Modified to use TimePeriod rather than RegularTimePeriod (DG);
  49:  * 02-Feb-2007 : Removed author tags all over JFreeChart sources (DG);
  50:  * 25-Jul-2007 : Added clear() method by Rob Eden, see patch 1752205 (DG);
  51:  *
  52:  */
  53: 
  54: package org.jfree.data.time;
  55: 
  56: import java.util.Calendar;
  57: import java.util.List;
  58: import java.util.Locale;
  59: import java.util.TimeZone;
  60: 
  61: import org.jfree.data.DefaultKeyedValues2D;
  62: import org.jfree.data.DomainInfo;
  63: import org.jfree.data.Range;
  64: import org.jfree.data.general.DatasetChangeEvent;
  65: import org.jfree.data.xy.AbstractIntervalXYDataset;
  66: import org.jfree.data.xy.IntervalXYDataset;
  67: import org.jfree.data.xy.TableXYDataset;
  68: import org.jfree.util.PublicCloneable;
  69: 
  70: /**
  71:  * A dataset for regular time periods that implements the 
  72:  * {@link TableXYDataset} interface.
  73:  * 
  74:  * @see org.jfree.data.xy.TableXYDataset
  75:  */
  76: public class TimeTableXYDataset extends AbstractIntervalXYDataset
  77:                                 implements Cloneable, PublicCloneable,
  78:                                            IntervalXYDataset, 
  79:                                            DomainInfo, 
  80:                                            TableXYDataset {
  81:     
  82:     /**
  83:      * The data structure to store the values.  Each column represents
  84:      * a series (elsewhere in JFreeChart rows are typically used for series,
  85:      * but it doesn't matter that much since this data structure is private 
  86:      * and symmetrical anyway), each row contains values for the same 
  87:      * {@link RegularTimePeriod} (the rows are sorted into ascending order).
  88:      */
  89:     private DefaultKeyedValues2D values;
  90:     
  91:     /**
  92:      * A flag that indicates that the domain is 'points in time'.  If this flag
  93:      * is true, only the x-value (and not the x-interval) is used to determine 
  94:      * the range of values in the domain.
  95:      */
  96:     private boolean domainIsPointsInTime;
  97:     
  98:     /** 
  99:      * The point within each time period that is used for the X value when this
 100:      * collection is used as an {@link org.jfree.data.xy.XYDataset}.  This can 
 101:      * be the start, middle or end of the time period.   
 102:      */
 103:     private TimePeriodAnchor xPosition;
 104: 
 105:     /** A working calendar (to recycle) */
 106:     private Calendar workingCalendar;
 107: 
 108:     /**
 109:      * Creates a new dataset.
 110:      */
 111:     public TimeTableXYDataset() {
 112:         // defer argument checking
 113:         this(TimeZone.getDefault(), Locale.getDefault());
 114:     }
 115:     
 116:     /**
 117:      * Creates a new dataset with the given time zone.
 118:      * 
 119:      * @param zone  the time zone to use (<code>null</code> not permitted).
 120:      */
 121:     public TimeTableXYDataset(TimeZone zone) {
 122:         // defer argument checking
 123:         this(zone, Locale.getDefault());
 124:     }
 125: 
 126:     /**
 127:      * Creates a new dataset with the given time zone and locale.
 128:      * 
 129:      * @param zone  the time zone to use (<code>null</code> not permitted).
 130:      * @param locale  the locale to use (<code>null</code> not permitted).
 131:      */
 132:     public TimeTableXYDataset(TimeZone zone, Locale locale) {
 133:         if (zone == null) {
 134:             throw new IllegalArgumentException("Null 'zone' argument.");
 135:         }
 136:         if (locale == null) {
 137:             throw new IllegalArgumentException("Null 'locale' argument.");
 138:         }
 139:         this.values = new DefaultKeyedValues2D(true);
 140:         this.workingCalendar = Calendar.getInstance(zone, locale);
 141:         this.xPosition = TimePeriodAnchor.START;
 142:     }
 143:     
 144:     /**
 145:      * Returns a flag that controls whether the domain is treated as 'points in
 146:      * time'.
 147:      * <P>
 148:      * This flag is used when determining the max and min values for the domain.
 149:      * If true, then only the x-values are considered for the max and min 
 150:      * values.  If false, then the start and end x-values will also be taken 
 151:      * into consideration.
 152:      *
 153:      * @return The flag.
 154:      */
 155:     public boolean getDomainIsPointsInTime() {
 156:         return this.domainIsPointsInTime;
 157:     }
 158: 
 159:     /**
 160:      * Sets a flag that controls whether the domain is treated as 'points in 
 161:      * time', or time periods.  A {@link DatasetChangeEvent} is sent to all
 162:      * registered listeners.
 163:      *
 164:      * @param flag  the new value of the flag.
 165:      */
 166:     public void setDomainIsPointsInTime(boolean flag) {
 167:         this.domainIsPointsInTime = flag;
 168:         notifyListeners(new DatasetChangeEvent(this, this));
 169:     }
 170:     
 171:     /**
 172:      * Returns the position within each time period that is used for the X 
 173:      * value.
 174:      * 
 175:      * @return The anchor position (never <code>null</code>).
 176:      */
 177:     public TimePeriodAnchor getXPosition() {
 178:         return this.xPosition;
 179:     }
 180: 
 181:     /**
 182:      * Sets the position within each time period that is used for the X values,
 183:      * then sends a {@link DatasetChangeEvent} to all registered listeners.
 184:      * 
 185:      * @param anchor  the anchor position (<code>null</code> not permitted).
 186:      */
 187:     public void setXPosition(TimePeriodAnchor anchor) {
 188:         if (anchor == null) {
 189:             throw new IllegalArgumentException("Null 'anchor' argument.");
 190:         }
 191:         this.xPosition = anchor;
 192:         notifyListeners(new DatasetChangeEvent(this, this));    
 193:     }
 194:         
 195:     /**
 196:      * Adds a new data item to the dataset and sends a 
 197:      * {@link org.jfree.data.general.DatasetChangeEvent} to all registered
 198:      * listeners.
 199:      * 
 200:      * @param period  the time period.
 201:      * @param y  the value for this period.
 202:      * @param seriesName  the name of the series to add the value.
 203:      */
 204:     public void add(TimePeriod period, double y, String seriesName) {
 205:         add(period, new Double(y), seriesName, true);
 206:     }
 207:     
 208:     /**
 209:      * Adds a new data item to the dataset.
 210:      * 
 211:      * @param period  the time period (<code>null</code> not permitted).
 212:      * @param y  the value for this period (<code>null</code> permitted).
 213:      * @param seriesName  the name of the series to add the value 
 214:      *                    (<code>null</code> not permitted).
 215:      * @param notify  whether dataset listener are notified or not.
 216:      */
 217:     public void add(TimePeriod period, Number y, String seriesName, 
 218:                     boolean notify) {
 219:         this.values.addValue(y, period, seriesName);
 220:         if (notify) {
 221:             fireDatasetChanged();
 222:         }
 223:     }
 224: 
 225:     /**
 226:      * Removes an existing data item from the dataset.
 227:      * 
 228:      * @param period  the (existing!) time period of the value to remove 
 229:      *                (<code>null</code> not permitted).
 230:      * @param seriesName  the (existing!) series name to remove the value 
 231:      *                    (<code>null</code> not permitted).
 232:      */
 233:     public void remove(TimePeriod period, String seriesName) {
 234:         remove(period, seriesName, true);
 235:     }
 236:     
 237:     /**
 238:      * Removes an existing data item from the dataset.
 239:      * 
 240:      * @param period  the (existing!) time period of the value to remove 
 241:      *                (<code>null</code> not permitted).
 242:      * @param seriesName  the (existing!) series name to remove the value 
 243:      *                    (<code>null</code> not permitted).
 244:      * @param notify  whether dataset listener are notified or not.
 245:      */
 246:     public void remove(TimePeriod period, String seriesName, boolean notify) {
 247:         this.values.removeValue(period, seriesName);
 248:         if (notify) {
 249:             fireDatasetChanged();
 250:         }
 251:     }
 252: 
 253:     /**
 254:      * Removes all data items from the dataset and sends a
 255:      * {@link DatasetChangeEvent} to all registered listeners.
 256:      * 
 257:      * @since 1.0.7
 258:      */
 259:     public void clear() {
 260:         if (this.values.getRowCount() > 0) {
 261:             this.values.clear();
 262:             fireDatasetChanged();
 263:         }
 264:     }
 265:     
 266:     /**
 267:      * Returns the time period for the specified item.  Bear in mind that all
 268:      * series share the same set of time periods.
 269:      * 
 270:      * @param item  the item index (0 <= i <= {@link #getItemCount()}).
 271:      * 
 272:      * @return The time period.
 273:      */
 274:     public TimePeriod getTimePeriod(int item) {
 275:         return (TimePeriod) this.values.getRowKey(item);    
 276:     }
 277:     
 278:     /**
 279:      * Returns the number of items in ALL series.
 280:      *
 281:      * @return The item count.
 282:      */
 283:     public int getItemCount() {
 284:         return this.values.getRowCount();
 285:     }
 286: 
 287:     /**
 288:      * Returns the number of items in a series.  This is the same value
 289:      * that is returned by {@link #getItemCount()} since all series
 290:      * share the same x-values (time periods).
 291:      *
 292:      * @param series  the series (zero-based index, ignored).
 293:      *
 294:      * @return The number of items within the series.
 295:      */
 296:     public int getItemCount(int series) {
 297:         return getItemCount();
 298:     }
 299:     
 300:     /**
 301:      * Returns the number of series in the dataset.
 302:      *
 303:      * @return The series count.
 304:      */
 305:     public int getSeriesCount() {
 306:         return this.values.getColumnCount();
 307:     }
 308: 
 309:     /**
 310:      * Returns the key for a series.
 311:      *
 312:      * @param series  the series (zero-based index).
 313:      *
 314:      * @return The key for the series.
 315:      */
 316:     public Comparable getSeriesKey(int series) {
 317:         return this.values.getColumnKey(series);
 318:     }
 319:     
 320:     /**
 321:      * Returns the x-value for an item within a series.  The x-values may or 
 322:      * may not be returned in ascending order, that is up to the class 
 323:      * implementing the interface.
 324:      *
 325:      * @param series  the series (zero-based index).
 326:      * @param item  the item (zero-based index).
 327:      *
 328:      * @return The x-value.
 329:      */
 330:     public Number getX(int series, int item) {
 331:         return new Double(getXValue(series, item));
 332:     }
 333:     
 334:     /**
 335:      * Returns the x-value (as a double primitive) for an item within a series.
 336:      * 
 337:      * @param series  the series index (zero-based).
 338:      * @param item  the item index (zero-based).
 339:      * 
 340:      * @return The value.
 341:      */
 342:     public double getXValue(int series, int item) {
 343:         TimePeriod period = (TimePeriod) this.values.getRowKey(item);
 344:         return getXValue(period);
 345:     }
 346: 
 347:     /**
 348:      * Returns the starting X value for the specified series and item.
 349:      *
 350:      * @param series  the series (zero-based index).
 351:      * @param item  the item within a series (zero-based index).
 352:      *
 353:      * @return The starting X value for the specified series and item.
 354:      */
 355:     public Number getStartX(int series, int item) {
 356:         return new Double(getStartXValue(series, item));
 357:     }
 358: 
 359:     /**
 360:      * Returns the start x-value (as a double primitive) for an item within 
 361:      * a series.
 362:      * 
 363:      * @param series  the series index (zero-based).
 364:      * @param item  the item index (zero-based).
 365:      * 
 366:      * @return The value.
 367:      */
 368:     public double getStartXValue(int series, int item) {
 369:         TimePeriod period = (TimePeriod) this.values.getRowKey(item);
 370:         return period.getStart().getTime();
 371:     }
 372: 
 373:     /**
 374:      * Returns the ending X value for the specified series and item.
 375:      *
 376:      * @param series  the series (zero-based index).
 377:      * @param item  the item within a series (zero-based index).
 378:      *
 379:      * @return The ending X value for the specified series and item.
 380:      */
 381:     public Number getEndX(int series, int item) {
 382:         return new Double(getEndXValue(series, item));
 383:     }
 384: 
 385:     /**
 386:      * Returns the end x-value (as a double primitive) for an item within 
 387:      * a series.
 388:      * 
 389:      * @param series  the series index (zero-based).
 390:      * @param item  the item index (zero-based).
 391:      * 
 392:      * @return The value.
 393:      */
 394:     public double getEndXValue(int series, int item) {
 395:         TimePeriod period = (TimePeriod) this.values.getRowKey(item);
 396:         return period.getEnd().getTime();
 397:     }
 398:  
 399:     /**
 400:      * Returns the y-value for an item within a series.
 401:      *
 402:      * @param series  the series (zero-based index).
 403:      * @param item  the item (zero-based index).
 404:      *
 405:      * @return The y-value (possibly <code>null</code>).
 406:      */
 407:     public Number getY(int series, int item) {
 408:         return this.values.getValue(item, series);
 409:     }
 410:     
 411:     /**
 412:      * Returns the starting Y value for the specified series and item.
 413:      *
 414:      * @param series  the series (zero-based index).
 415:      * @param item  the item within a series (zero-based index).
 416:      *
 417:      * @return The starting Y value for the specified series and item.
 418:      */
 419:     public Number getStartY(int series, int item) {
 420:         return getY(series, item);
 421:     }
 422:     
 423:     /**
 424:      * Returns the ending Y value for the specified series and item.
 425:      *
 426:      * @param series  the series (zero-based index).
 427:      * @param item  the item within a series (zero-based index).
 428:      *
 429:      * @return The ending Y value for the specified series and item.
 430:      */
 431:     public Number getEndY(int series, int item) {
 432:         return getY(series, item);
 433:     }
 434:     
 435:     /**
 436:      * Returns the x-value for a time period.
 437:      *
 438:      * @param period  the time period.
 439:      *
 440:      * @return The x-value.
 441:      */
 442:     private long getXValue(TimePeriod period) {
 443:         long result = 0L;
 444:         if (this.xPosition == TimePeriodAnchor.START) {
 445:             result = period.getStart().getTime();
 446:         }
 447:         else if (this.xPosition == TimePeriodAnchor.MIDDLE) {
 448:             long t0 = period.getStart().getTime();
 449:             long t1 = period.getEnd().getTime();
 450:             result = t0 + (t1 - t0) / 2L;
 451:         }
 452:         else if (this.xPosition == TimePeriodAnchor.END) {
 453:             result = period.getEnd().getTime();
 454:         }
 455:         return result;
 456:     }
 457:     
 458:     /**
 459:      * Returns the minimum x-value in the dataset.
 460:      *
 461:      * @param includeInterval  a flag that determines whether or not the
 462:      *                         x-interval is taken into account.
 463:      * 
 464:      * @return The minimum value.
 465:      */
 466:     public double getDomainLowerBound(boolean includeInterval) {
 467:         double result = Double.NaN;
 468:         Range r = getDomainBounds(includeInterval);
 469:         if (r != null) {
 470:             result = r.getLowerBound();
 471:         }
 472:         return result;
 473:     }
 474: 
 475:     /**
 476:      * Returns the maximum x-value in the dataset.
 477:      *
 478:      * @param includeInterval  a flag that determines whether or not the
 479:      *                         x-interval is taken into account.
 480:      * 
 481:      * @return The maximum value.
 482:      */
 483:     public double getDomainUpperBound(boolean includeInterval) {
 484:         double result = Double.NaN;
 485:         Range r = getDomainBounds(includeInterval);
 486:         if (r != null) {
 487:             result = r.getUpperBound();
 488:         }
 489:         return result;
 490:     }
 491: 
 492:     /**
 493:      * Returns the range of the values in this dataset's domain.
 494:      * 
 495:      * @param includeInterval  a flag that controls whether or not the
 496:      *                         x-intervals are taken into account.
 497:      *
 498:      * @return The range.
 499:      */
 500:     public Range getDomainBounds(boolean includeInterval) {
 501:         List keys = this.values.getRowKeys();
 502:         if (keys.isEmpty()) {
 503:             return null;
 504:         }
 505:         
 506:         TimePeriod first = (TimePeriod) keys.get(0);
 507:         TimePeriod last = (TimePeriod) keys.get(keys.size() - 1);
 508:         
 509:         if (!includeInterval || this.domainIsPointsInTime) {
 510:             return new Range(getXValue(first), getXValue(last));
 511:         }
 512:         else {
 513:             return new Range(first.getStart().getTime(), 
 514:                     last.getEnd().getTime());
 515:         }
 516:     }
 517:     
 518:     /**
 519:      * Tests this dataset for equality with an arbitrary object.
 520:      * 
 521:      * @param obj  the object (<code>null</code> permitted).
 522:      * 
 523:      * @return A boolean.
 524:      */
 525:     public boolean equals(Object obj) {
 526:         if (obj == this) {
 527:             return true;
 528:         }
 529:         if (!(obj instanceof TimeTableXYDataset)) {
 530:             return false;
 531:         }
 532:         TimeTableXYDataset that = (TimeTableXYDataset) obj;
 533:         if (this.domainIsPointsInTime != that.domainIsPointsInTime) {
 534:             return false;
 535:         }
 536:         if (this.xPosition != that.xPosition) {
 537:             return false;
 538:         }
 539:         if (!this.workingCalendar.getTimeZone().equals(
 540:             that.workingCalendar.getTimeZone())
 541:         ) {
 542:             return false;
 543:         }
 544:         if (!this.values.equals(that.values)) {
 545:             return false;
 546:         }
 547:         return true;
 548:     }
 549:     
 550:     /**
 551:      * Returns a clone of this dataset.
 552:      * 
 553:      * @return A clone.
 554:      * 
 555:      * @throws CloneNotSupportedException if the dataset cannot be cloned.
 556:      */
 557:     public Object clone() throws CloneNotSupportedException {
 558:         TimeTableXYDataset clone = (TimeTableXYDataset) super.clone();
 559:         clone.values = (DefaultKeyedValues2D) this.values.clone();
 560:         clone.workingCalendar = (Calendar) this.workingCalendar.clone();
 561:         return clone;
 562:     }
 563: 
 564: }