    001/* ===========================================================
    002 * JFreeChart : a free chart library for the Java(tm) platform
    003 * ===========================================================
    004 *
    005 * (C) Copyright 2000-2011, 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 * DefaultTableXYDataset.java
    029 * --------------------------
    030 * (C) Copyright 2003-2009, by Richard Atkinson and Contributors.
    031 *
    032 * Original Author:  Richard Atkinson;
    033 * Contributor(s):   Jody Brownell;
    034 *                   David Gilbert (for Object Refinery Limited);
    035 *                   Andreas Schroeder;
    036 *
    037 * Changes:
    038 * --------
    039 * 27-Jul-2003 : XYDataset that forces each series to have a value for every
    040 *               X-point which is essential for stacked XY area charts (RA);
    041 * 18-Aug-2003 : Fixed event notification when removing and updating
    042 *               series (RA);
    043 * 22-Sep-2003 : Functionality moved from TableXYDataset to
    044 *               DefaultTableXYDataset (RA);
    045 * 23-Dec-2003 : Added patch for large datasets, submitted by Jody
    046 *               Brownell (DG);
    047 * 16-Feb-2004 : Added pruning methods (DG);
    048 * 31-Mar-2004 : Provisional implementation of IntervalXYDataset (AS);
    049 * 01-Apr-2004 : Sound implementation of IntervalXYDataset (AS);
    050 * 05-May-2004 : Now extends AbstractIntervalXYDataset (DG);
    051 * 15-Jul-2004 : Switched getX() with getXValue() and getY() with
    052 *               getYValue() (DG);
    053 * 18-Aug-2004 : Moved from org.jfree.data --> org.jfree.data.xy (DG);
    054 * 11-Jan-2005 : Removed deprecated code in preparation for the 1.0.0
    055 *               release (DG);
    056 * 05-Oct-2005 : Made the interval delegate a dataset listener (DG);
    057 * 02-Feb-2007 : Removed author tags all over JFreeChart sources (DG);
    058 * 22-Apr-2008 : Implemented PublicCloneable (DG);
    059 * 10-Jun-2009 : Simplified getX() and getY() (DG);
    060 *
    061 */
    062
    063package org.jfree.data.xy;
    064
    065import java.util.ArrayList;
    066import java.util.HashSet;
    067import java.util.Iterator;
    068import java.util.List;
    069
    070import org.jfree.data.DomainInfo;
    071import org.jfree.data.Range;
    072import org.jfree.data.general.DatasetChangeEvent;
    073import org.jfree.data.general.DatasetUtilities;
    074import org.jfree.data.general.SeriesChangeEvent;
    075import org.jfree.util.ObjectUtilities;
    076import org.jfree.util.PublicCloneable;
    077
    078/**
    079 * An {@link XYDataset} where every series shares the same x-values (required
    080 * for generating stacked area charts).
    081 */
    082public class DefaultTableXYDataset extends AbstractIntervalXYDataset
    083        implements TableXYDataset, IntervalXYDataset, DomainInfo,
    084                   PublicCloneable {
    085
    086    /**
    087     * Storage for the data - this list will contain zero, one or many
    088     * XYSeries objects.
    089     */
    090    private List data = null;
    091
    092    /** Storage for the x values. */
    093    private HashSet xPoints = null;
    094
    095    /** A flag that controls whether or not events are propogated. */
    096    private boolean propagateEvents = true;
    097
    098    /** A flag that controls auto pruning. */
    099    private boolean autoPrune = false;
    100
    101    /** The delegate used to control the interval width. */
    102    private IntervalXYDelegate intervalDelegate;
    103
    104    /**
    105     * Creates a new empty dataset.
    106     */
    107    public DefaultTableXYDataset() {
    108        this(false);
    109    }
    110
    111    /**
    112     * Creates a new empty dataset.
    113     *
    114     * @param autoPrune  a flag that controls whether or not x-values are
    115     *                   removed whenever the corresponding y-values are all
    116     *                   <code>null</code>.
    117     */
    118    public DefaultTableXYDataset(boolean autoPrune) {
    119        this.autoPrune = autoPrune;
    120        this.data = new ArrayList();
    121        this.xPoints = new HashSet();
    122        this.intervalDelegate = new IntervalXYDelegate(this, false);
    123        addChangeListener(this.intervalDelegate);
    124    }
    125
    126    /**
    127     * Returns the flag that controls whether or not x-values are removed from
    128     * the dataset when the corresponding y-values are all <code>null</code>.
    129     *
    130     * @return A boolean.
    131     */
    132    public boolean isAutoPrune() {
    133        return this.autoPrune;
    134    }
    135
    136    /**
    137     * Adds a series to the collection and sends a {@link DatasetChangeEvent}
    138     * to all registered listeners.  The series should be configured to NOT
    139     * allow duplicate x-values.
    140     *
    141     * @param series  the series (<code>null</code> not permitted).
    142     */
    143    public void addSeries(XYSeries series) {
    144        if (series == null) {
    145            throw new IllegalArgumentException("Null 'series' argument.");
    146        }
    147        if (series.getAllowDuplicateXValues()) {
    148            throw new IllegalArgumentException(
    149                "Cannot accept XYSeries that allow duplicate values. "
    150                + "Use XYSeries(seriesName, <sort>, false) constructor."
    151            );
    152        }
    153        updateXPoints(series);
    154        this.data.add(series);
    155        series.addChangeListener(this);
    156        fireDatasetChanged();
    157    }
    158
    159    /**
    160     * Adds any unique x-values from 'series' to the dataset, and also adds any
    161     * x-values that are in the dataset but not in 'series' to the series.
    162     *
    163     * @param series  the series (<code>null</code> not permitted).
    164     */
    165    private void updateXPoints(XYSeries series) {
    166        if (series == null) {
    167            throw new IllegalArgumentException("Null 'series' not permitted.");
    168        }
    169        HashSet seriesXPoints = new HashSet();
    170        boolean savedState = this.propagateEvents;
    171        this.propagateEvents = false;
    172        for (int itemNo = 0; itemNo < series.getItemCount(); itemNo++) {
    173            Number xValue = series.getX(itemNo);
    174            seriesXPoints.add(xValue);
    175            if (!this.xPoints.contains(xValue)) {
    176                this.xPoints.add(xValue);
    177                int seriesCount = this.data.size();
    178                for (int seriesNo = 0; seriesNo < seriesCount; seriesNo++) {
    179                    XYSeries dataSeries = (XYSeries) this.data.get(seriesNo);
    180                    if (!dataSeries.equals(series)) {
    181                        dataSeries.add(xValue, null);
    182                    }
    183                }
    184            }
    185        }
    186        Iterator iterator = this.xPoints.iterator();
    187        while (iterator.hasNext()) {
    188            Number xPoint = (Number) iterator.next();
    189            if (!seriesXPoints.contains(xPoint)) {
    190                series.add(xPoint, null);
    191            }
    192        }
    193        this.propagateEvents = savedState;
    194    }
    195
    196    /**
    197     * Updates the x-values for all the series in the dataset.
    198     */
    199    public void updateXPoints() {
    200        this.propagateEvents = false;
    201        for (int s = 0; s < this.data.size(); s++) {
    202            updateXPoints((XYSeries) this.data.get(s));
    203        }
    204        if (this.autoPrune) {
    205            prune();
    206        }
    207        this.propagateEvents = true;
    208    }
    209
    210    /**
    211     * Returns the number of series in the collection.
    212     *
    213     * @return The series count.
    214     */
    215    public int getSeriesCount() {
    216        return this.data.size();
    217    }
    218
    219    /**
    220     * Returns the number of x values in the dataset.
    221     *
    222     * @return The number of x values in the dataset.
    223     */
    224    public int getItemCount() {
    225        if (this.xPoints == null) {
    226            return 0;
    227        }
    228        else {
    229            return this.xPoints.size();
    230        }
    231    }
    232
    233    /**
    234     * Returns a series.
    235     *
    236     * @param series  the series (zero-based index).
    237     *
    238     * @return The series (never <code>null</code>).
    239     */
    240    public XYSeries getSeries(int series) {
    241        if ((series < 0) || (series >= getSeriesCount())) {
    242            throw new IllegalArgumentException("Index outside valid range.");
    243        }
    244        return (XYSeries) this.data.get(series);
    245    }
    246
    247    /**
    248     * Returns the key for a series.
    249     *
    250     * @param series  the series (zero-based index).
    251     *
    252     * @return The key for a series.
    253     */
    254    public Comparable getSeriesKey(int series) {
    255        // check arguments...delegated
    256        return getSeries(series).getKey();
    257    }
    258
    259    /**
    260     * Returns the number of items in the specified series.
    261     *
    262     * @param series  the series (zero-based index).
    263     *
    264     * @return The number of items in the specified series.
    265     */
    266    public int getItemCount(int series) {
    267        // check arguments...delegated
    268        return getSeries(series).getItemCount();
    269    }
    270
    271    /**
    272     * Returns the x-value for the specified series and item.
    273     *
    274     * @param series  the series (zero-based index).
    275     * @param item  the item (zero-based index).
    276     *
    277     * @return The x-value for the specified series and item.
    278     */
    279    public Number getX(int series, int item) {
    280        XYSeries s = (XYSeries) this.data.get(series);
    281        return s.getX(item);
    282
    283    }
    284
    285    /**
    286     * Returns the starting X value for the specified series and item.
    287     *
    288     * @param series  the series (zero-based index).
    289     * @param item  the item (zero-based index).
    290     *
    291     * @return The starting X value.
    292     */
    293    public Number getStartX(int series, int item) {
    294        return this.intervalDelegate.getStartX(series, item);
    295    }
    296
    297    /**
    298     * Returns the ending X value for the specified series and item.
    299     *
    300     * @param series  the series (zero-based index).
    301     * @param item  the item (zero-based index).
    302     *
    303     * @return The ending X value.
    304     */
    305    public Number getEndX(int series, int item) {
    306        return this.intervalDelegate.getEndX(series, item);
    307    }
    308
    309    /**
    310     * Returns the y-value for the specified series and item.
    311     *
    312     * @param series  the series (zero-based index).
    313     * @param index  the index of the item of interest (zero-based).
    314     *
    315     * @return The y-value for the specified series and item (possibly
    316     *         <code>null</code>).
    317     */
    318    public Number getY(int series, int index) {
    319        XYSeries s = (XYSeries) this.data.get(series);
    320        return s.getY(index);
    321    }
    322
    323    /**
    324     * Returns the starting Y value for the specified series and item.
    325     *
    326     * @param series  the series (zero-based index).
    327     * @param item  the item (zero-based index).
    328     *
    329     * @return The starting Y value.
    330     */
    331    public Number getStartY(int series, int item) {
    332        return getY(series, item);
    333    }
    334
    335    /**
    336     * Returns the ending Y value for the specified series and item.
    337     *
    338     * @param series  the series (zero-based index).
    339     * @param item  the item (zero-based index).
    340     *
    341     * @return The ending Y value.
    342     */
    343    public Number getEndY(int series, int item) {
    344        return getY(series, item);
    345    }
    346
    347    /**
    348     * Removes all the series from the collection and sends a
    349     * {@link DatasetChangeEvent} to all registered listeners.
    350     */
    351    public void removeAllSeries() {
    352
    353        // Unregister the collection as a change listener to each series in
    354        // the collection.
    355        for (int i = 0; i < this.data.size(); i++) {
    356            XYSeries series = (XYSeries) this.data.get(i);
    357            series.removeChangeListener(this);
    358        }
    359
    360        // Remove all the series from the collection and notify listeners.
    361        this.data.clear();
    362        this.xPoints.clear();
    363        fireDatasetChanged();
    364    }
    365
    366    /**
    367     * Removes a series from the collection and sends a
    368     * {@link DatasetChangeEvent} to all registered listeners.
    369     *
    370     * @param series  the series (<code>null</code> not permitted).
    371     */
    372    public void removeSeries(XYSeries series) {
    373
    374        // check arguments...
    375        if (series == null) {
    376            throw new IllegalArgumentException("Null 'series' argument.");
    377        }
    378
    379        // remove the series...
    380        if (this.data.contains(series)) {
    381            series.removeChangeListener(this);
    382            this.data.remove(series);
    383            if (this.data.size() == 0) {
    384                this.xPoints.clear();
    385            }
    386            fireDatasetChanged();
    387        }
    388
    389    }
    390
    391    /**
    392     * Removes a series from the collection and sends a
    393     * {@link DatasetChangeEvent} to all registered listeners.
    394     *
    395     * @param series  the series (zero based index).
    396     */
    397    public void removeSeries(int series) {
    398
    399        // check arguments...
    400        if ((series < 0) || (series > getSeriesCount())) {
    401            throw new IllegalArgumentException("Index outside valid range.");
    402        }
    403
    404        // fetch the series, remove the change listener, then remove the series.
    405        XYSeries s = (XYSeries) this.data.get(series);
    406        s.removeChangeListener(this);
    407        this.data.remove(series);
    408        if (this.data.size() == 0) {
    409            this.xPoints.clear();
    410        }
    411        else if (this.autoPrune) {
    412            prune();
    413        }
    414        fireDatasetChanged();
    415
    416    }
    417
    418    /**
    419     * Removes the items from all series for a given x value.
    420     *
    421     * @param x  the x-value.
    422     */
    423    public void removeAllValuesForX(Number x) {
    424        if (x == null) {
    425            throw new IllegalArgumentException("Null 'x' argument.");
    426        }
    427        boolean savedState = this.propagateEvents;
    428        this.propagateEvents = false;
    429        for (int s = 0; s < this.data.size(); s++) {
    430            XYSeries series = (XYSeries) this.data.get(s);
    431            series.remove(x);
    432        }
    433        this.propagateEvents = savedState;
    434        this.xPoints.remove(x);
    435        fireDatasetChanged();
    436    }
    437
    438    /**
    439     * Returns <code>true</code> if all the y-values for the specified x-value
    440     * are <code>null</code> and <code>false</code> otherwise.
    441     *
    442     * @param x  the x-value.
    443     *
    444     * @return A boolean.
    445     */
    446    protected boolean canPrune(Number x) {
    447        for (int s = 0; s < this.data.size(); s++) {
    448            XYSeries series = (XYSeries) this.data.get(s);
    449            if (series.getY(series.indexOf(x)) != null) {
    450                return false;
    451            }
    452        }
    453        return true;
    454    }
    455
    456    /**
    457     * Removes all x-values for which all the y-values are <code>null</code>.
    458     */
    459    public void prune() {
    460        HashSet hs = (HashSet) this.xPoints.clone();
    461        Iterator iterator = hs.iterator();
    462        while (iterator.hasNext()) {
    463            Number x = (Number) iterator.next();
    464            if (canPrune(x)) {
    465                removeAllValuesForX(x);
    466            }
    467        }
    468    }
    469
    470    /**
    471     * This method receives notification when a series belonging to the dataset
    472     * changes.  It responds by updating the x-points for the entire dataset
    473     * and sending a {@link DatasetChangeEvent} to all registered listeners.
    474     *
    475     * @param event  information about the change.
    476     */
    477    public void seriesChanged(SeriesChangeEvent event) {
    478        if (this.propagateEvents) {
    479            updateXPoints();
    480            fireDatasetChanged();
    481        }
    482    }
    483
    484    /**
    485     * Tests this collection for equality with an arbitrary object.
    486     *
    487     * @param obj  the object (<code>null</code> permitted).
    488     *
    489     * @return A boolean.
    490     */
    491    public boolean equals(Object obj) {
    492        if (obj == this) {
    493            return true;
    494        }
    495        if (!(obj instanceof DefaultTableXYDataset)) {
    496            return false;
    497        }
    498        DefaultTableXYDataset that = (DefaultTableXYDataset) obj;
    499        if (this.autoPrune != that.autoPrune) {
    500            return false;
    501        }
    502        if (this.propagateEvents != that.propagateEvents) {
    503            return false;
    504        }
    505        if (!this.intervalDelegate.equals(that.intervalDelegate)) {
    506            return false;
    507        }
    508        if (!ObjectUtilities.equal(this.data, that.data)) {
    509            return false;
    510        }
    511        return true;
    512    }
    513
    514    /**
    515     * Returns a hash code.
    516     *
    517     * @return A hash code.
    518     */
    519    public int hashCode() {
    520        int result;
    521        result = (this.data != null ? this.data.hashCode() : 0);
    522        result = 29 * result
    523                 + (this.xPoints != null ? this.xPoints.hashCode() : 0);
    524        result = 29 * result + (this.propagateEvents ? 1 : 0);
    525        result = 29 * result + (this.autoPrune ? 1 : 0);
    526        return result;
    527    }
    528
    529    /**
    530     * Returns an independent copy of this dataset.
    531     *
    532     * @return A clone.
    533     *
    534     * @throws CloneNotSupportedException if there is some reason that cloning
    535     *     cannot be performed.
    536     */
    537    public Object clone() throws CloneNotSupportedException {
    538        DefaultTableXYDataset clone = (DefaultTableXYDataset) super.clone();
    539        int seriesCount = this.data.size();
    540        clone.data = new java.util.ArrayList(seriesCount);
    541        for (int i = 0; i < seriesCount; i++) {
    542            XYSeries series = (XYSeries) this.data.get(i);
    543            clone.data.add(series.clone());
    544        }
    545
    546        clone.intervalDelegate = new IntervalXYDelegate(clone);
    547        // need to configure the intervalDelegate to match the original
    548        clone.intervalDelegate.setFixedIntervalWidth(getIntervalWidth());
    549        clone.intervalDelegate.setAutoWidth(isAutoWidth());
    550        clone.intervalDelegate.setIntervalPositionFactor(
    551                getIntervalPositionFactor());
    552        clone.updateXPoints();
    553        return clone;
    554    }
    555
    556    /**
    557     * Returns the minimum x-value in the dataset.
    558     *
    559     * @param includeInterval  a flag that determines whether or not the
    560     *                         x-interval is taken into account.
    561     *
    562     * @return The minimum value.
    563     */
    564    public double getDomainLowerBound(boolean includeInterval) {
    565        return this.intervalDelegate.getDomainLowerBound(includeInterval);
    566    }
    567
    568    /**
    569     * Returns the maximum x-value in the dataset.
    570     *
    571     * @param includeInterval  a flag that determines whether or not the
    572     *                         x-interval is taken into account.
    573     *
    574     * @return The maximum value.
    575     */
    576    public double getDomainUpperBound(boolean includeInterval) {
    577        return this.intervalDelegate.getDomainUpperBound(includeInterval);
    578    }
    579
    580    /**
    581     * Returns the range of the values in this dataset's domain.
    582     *
    583     * @param includeInterval  a flag that determines whether or not the
    584     *                         x-interval is taken into account.
    585     *
    586     * @return The range.
    587     */
    588    public Range getDomainBounds(boolean includeInterval) {
    589        if (includeInterval) {
    590            return this.intervalDelegate.getDomainBounds(includeInterval);
    591        }
    592        else {
    593            return DatasetUtilities.iterateDomainBounds(this, includeInterval);
    594        }
    595    }
    596
    597    /**
    598     * Returns the interval position factor.
    599     *
    600     * @return The interval position factor.
    601     */
    602    public double getIntervalPositionFactor() {
    603        return this.intervalDelegate.getIntervalPositionFactor();
    604    }
    605
    606    /**
    607     * Sets the interval position factor. Must be between 0.0 and 1.0 inclusive.
    608     * If the factor is 0.5, the gap is in the middle of the x values. If it
    609     * is lesser than 0.5, the gap is farther to the left and if greater than
    610     * 0.5 it gets farther to the right.
    611     *
    612     * @param d the new interval position factor.
    613     */
    614    public void setIntervalPositionFactor(double d) {
    615        this.intervalDelegate.setIntervalPositionFactor(d);
    616        fireDatasetChanged();
    617    }
    618
    619    /**
    620     * returns the full interval width.
    621     *
    622     * @return The interval width to use.
    623     */
    624    public double getIntervalWidth() {
    625        return this.intervalDelegate.getIntervalWidth();
    626    }
    627
    628    /**
    629     * Sets the interval width to a fixed value, and sends a
    630     * {@link DatasetChangeEvent} to all registered listeners.
    631     *
    632     * @param d  the new interval width (must be > 0).
    633     */
    634    public void setIntervalWidth(double d) {
    635        this.intervalDelegate.setFixedIntervalWidth(d);
    636        fireDatasetChanged();
    637    }
    638
    639    /**
    640     * Returns whether the interval width is automatically calculated or not.
    641     *
    642     * @return A flag that determines whether or not the interval width is
    643     *         automatically calculated.
    644     */
    645    public boolean isAutoWidth() {
    646        return this.intervalDelegate.isAutoWidth();
    647    }
    648
    649    /**
    650     * Sets the flag that indicates whether the interval width is automatically
    651     * calculated or not.
    652     *
    653     * @param b  a boolean.
    654     */
    655    public void setAutoWidth(boolean b) {
    656        this.intervalDelegate.setAutoWidth(b);
    657        fireDatasetChanged();
    658    }
    659
    660}