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