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 * CategoryTableXYDataset.java
029 * ---------------------------
030 * (C) Copyright 2004-2011, by Andreas Schroeder and Contributors.
031 *
032 * Original Author:  Andreas Schroeder;
033 * Contributor(s):   David Gilbert (for Object Refinery Limited);
034 *
035 * Changes
036 * -------
037 * 31-Mar-2004 : Version 1 (AS);
038 * 05-May-2004 : Now extends AbstractIntervalXYDataset (DG);
039 * 15-Jul-2004 : Switched interval access method names (DG);
040 * 18-Aug-2004 : Moved from org.jfree.data --> org.jfree.data.xy (DG);
041 * 17-Nov-2004 : Updates required by changes to DomainInfo interface (DG);
042 * 11-Jan-2005 : Removed deprecated code in preparation for 1.0.0 release (DG);
043 * 05-Oct-2005 : Made the interval delegate a dataset change listener (DG);
044 * 02-Feb-2007 : Removed author tags all over JFreeChart sources (DG);
045 * 22-Apr-2008 : Implemented PublicCloneable, and fixed clone() method (DG);
046 * 18-Oct-2011 : Fixed bug 3190615 - added clear() method (DG);
047 *
048 */
049
050package org.jfree.data.xy;
051
052import org.jfree.data.DefaultKeyedValues2D;
053import org.jfree.data.DomainInfo;
054import org.jfree.data.Range;
055import org.jfree.data.general.DatasetChangeEvent;
056import org.jfree.data.general.DatasetUtilities;
057import org.jfree.util.PublicCloneable;
058
059/**
060 * An implementation variant of the {@link TableXYDataset} where every series
061 * shares the same x-values (required for generating stacked area charts).
062 * This implementation uses a {@link DefaultKeyedValues2D} Object as backend
063 * implementation and is hence more "category oriented" than the {@link
064 * DefaultTableXYDataset} implementation.
065 * <p>
066 * This implementation provides no means to remove data items yet.
067 * This is due to the lack of such facility in the DefaultKeyedValues2D class.
068 * <p>
069 * This class also implements the {@link IntervalXYDataset} interface, but this
070 * implementation is provisional.
071 */
072public class CategoryTableXYDataset extends AbstractIntervalXYDataset
073        implements TableXYDataset, IntervalXYDataset, DomainInfo,
074                   PublicCloneable {
075
076    /**
077     * The backing data structure.
078     */
079    private DefaultKeyedValues2D values;
080
081    /** A delegate for controlling the interval width. */
082    private IntervalXYDelegate intervalDelegate;
083
084    /**
085     * Creates a new empty CategoryTableXYDataset.
086     */
087    public CategoryTableXYDataset() {
088        this.values = new DefaultKeyedValues2D(true);
089        this.intervalDelegate = new IntervalXYDelegate(this);
090        addChangeListener(this.intervalDelegate);
091    }
092
093    /**
094     * Adds a data item to this dataset and sends a {@link DatasetChangeEvent}
095     * to all registered listeners.
096     *
097     * @param x  the x value.
098     * @param y  the y value.
099     * @param seriesName  the name of the series to add the data item.
100     */
101    public void add(double x, double y, String seriesName) {
102        add(new Double(x), new Double(y), seriesName, true);
103    }
104
105    /**
106     * Adds a data item to this dataset and, if requested, sends a
107     * {@link DatasetChangeEvent} to all registered listeners.
108     *
109     * @param x  the x value.
110     * @param y  the y value.
111     * @param seriesName  the name of the series to add the data item.
112     * @param notify  notify listeners?
113     */
114    public void add(Number x, Number y, String seriesName, boolean notify) {
115        this.values.addValue(y, (Comparable) x, seriesName);
116        if (notify) {
117            fireDatasetChanged();
118        }
119    }
120
121    /**
122     * Removes a value from the dataset.
123     *
124     * @param x  the x-value.
125     * @param seriesName  the series name.
126     */
127    public void remove(double x, String seriesName) {
128        remove(new Double(x), seriesName, true);
129    }
130
131    /**
132     * Removes an item from the dataset.
133     *
134     * @param x  the x-value.
135     * @param seriesName  the series name.
136     * @param notify  notify listeners?
137     */
138    public void remove(Number x, String seriesName, boolean notify) {
139        this.values.removeValue((Comparable) x, seriesName);
140        if (notify) {
141            fireDatasetChanged();
142        }
143    }
144
145    /**
146     * Clears all data from the dataset and sends a {@link DatasetChangeEvent}
147     * to all registered listeners.
148     * 
149     * @since 1.0.14
150     */
151    public void clear() {
152        this.values.clear();
153        fireDatasetChanged();
154    }
155
156    /**
157     * Returns the number of series in the collection.
158     *
159     * @return The series count.
160     */
161    public int getSeriesCount() {
162        return this.values.getColumnCount();
163    }
164
165    /**
166     * Returns the key for a series.
167     *
168     * @param series  the series index (zero-based).
169     *
170     * @return The key for a series.
171     */
172    public Comparable getSeriesKey(int series) {
173        return this.values.getColumnKey(series);
174    }
175
176    /**
177     * Returns the number of x values in the dataset.
178     *
179     * @return The item count.
180     */
181    public int getItemCount() {
182        return this.values.getRowCount();
183    }
184
185    /**
186     * Returns the number of items in the specified series.
187     * Returns the same as {@link CategoryTableXYDataset#getItemCount()}.
188     *
189     * @param series  the series index (zero-based).
190     *
191     * @return The item count.
192     */
193    public int getItemCount(int series) {
194        return getItemCount();  // all series have the same number of items in
195                                // this dataset
196    }
197
198    /**
199     * Returns the x-value for the specified series and item.
200     *
201     * @param series  the series index (zero-based).
202     * @param item  the item index (zero-based).
203     *
204     * @return The value.
205     */
206    public Number getX(int series, int item) {
207        return (Number) this.values.getRowKey(item);
208    }
209
210    /**
211     * Returns the starting X value for the specified series and item.
212     *
213     * @param series  the series index (zero-based).
214     * @param item  the item index (zero-based).
215     *
216     * @return The starting X value.
217     */
218    public Number getStartX(int series, int item) {
219        return this.intervalDelegate.getStartX(series, item);
220    }
221
222    /**
223     * Returns the ending X value for the specified series and item.
224     *
225     * @param series  the series index (zero-based).
226     * @param item  the item index (zero-based).
227     *
228     * @return The ending X value.
229     */
230    public Number getEndX(int series, int item) {
231        return this.intervalDelegate.getEndX(series, item);
232    }
233
234    /**
235     * Returns the y-value for the specified series and item.
236     *
237     * @param series  the series index (zero-based).
238     * @param item  the item index (zero-based).
239     *
240     * @return The y value (possibly <code>null</code>).
241     */
242    public Number getY(int series, int item) {
243        return this.values.getValue(item, series);
244    }
245
246    /**
247     * Returns the starting Y value for the specified series and item.
248     *
249     * @param series  the series index (zero-based).
250     * @param item  the item index (zero-based).
251     *
252     * @return The starting Y value.
253     */
254    public Number getStartY(int series, int item) {
255        return getY(series, item);
256    }
257
258    /**
259     * Returns the ending Y value for the specified series and item.
260     *
261     * @param series  the series index (zero-based).
262     * @param item  the item index (zero-based).
263     *
264     * @return The ending Y value.
265     */
266    public Number getEndY(int series, int item) {
267        return getY(series, item);
268    }
269
270    /**
271     * Returns the minimum x-value in the dataset.
272     *
273     * @param includeInterval  a flag that determines whether or not the
274     *                         x-interval is taken into account.
275     *
276     * @return The minimum value.
277     */
278    public double getDomainLowerBound(boolean includeInterval) {
279        return this.intervalDelegate.getDomainLowerBound(includeInterval);
280    }
281
282    /**
283     * Returns the maximum x-value in the dataset.
284     *
285     * @param includeInterval  a flag that determines whether or not the
286     *                         x-interval is taken into account.
287     *
288     * @return The maximum value.
289     */
290    public double getDomainUpperBound(boolean includeInterval) {
291        return this.intervalDelegate.getDomainUpperBound(includeInterval);
292    }
293
294    /**
295     * Returns the range of the values in this dataset's domain.
296     *
297     * @param includeInterval  a flag that determines whether or not the
298     *                         x-interval is taken into account.
299     *
300     * @return The range.
301     */
302    public Range getDomainBounds(boolean includeInterval) {
303        if (includeInterval) {
304            return this.intervalDelegate.getDomainBounds(includeInterval);
305        }
306        else {
307            return DatasetUtilities.iterateDomainBounds(this, includeInterval);
308        }
309    }
310
311    /**
312     * Returns the interval position factor.
313     *
314     * @return The interval position factor.
315     */
316    public double getIntervalPositionFactor() {
317        return this.intervalDelegate.getIntervalPositionFactor();
318    }
319
320    /**
321     * Sets the interval position factor. Must be between 0.0 and 1.0 inclusive.
322     * If the factor is 0.5, the gap is in the middle of the x values. If it
323     * is lesser than 0.5, the gap is farther to the left and if greater than
324     * 0.5 it gets farther to the right.
325     *
326     * @param d  the new interval position factor.
327     */
328    public void setIntervalPositionFactor(double d) {
329        this.intervalDelegate.setIntervalPositionFactor(d);
330        fireDatasetChanged();
331    }
332
333    /**
334     * Returns the full interval width.
335     *
336     * @return The interval width to use.
337     */
338    public double getIntervalWidth() {
339        return this.intervalDelegate.getIntervalWidth();
340    }
341
342    /**
343     * Sets the interval width to a fixed value, and sends a
344     * {@link DatasetChangeEvent} to all registered listeners.
345     *
346     * @param d  the new interval width (must be > 0).
347     */
348    public void setIntervalWidth(double d) {
349        this.intervalDelegate.setFixedIntervalWidth(d);
350        fireDatasetChanged();
351    }
352
353    /**
354     * Returns whether the interval width is automatically calculated or not.
355     *
356     * @return whether the width is automatically calculated or not.
357     */
358    public boolean isAutoWidth() {
359        return this.intervalDelegate.isAutoWidth();
360    }
361
362    /**
363     * Sets the flag that indicates whether the interval width is automatically
364     * calculated or not.
365     *
366     * @param b  the flag.
367     */
368    public void setAutoWidth(boolean b) {
369        this.intervalDelegate.setAutoWidth(b);
370        fireDatasetChanged();
371    }
372
373    /**
374     * Tests this dataset for equality with an arbitrary object.
375     *
376     * @param obj  the object (<code>null</code> permitted).
377     *
378     * @return A boolean.
379     */
380    public boolean equals(Object obj) {
381        if (!(obj instanceof CategoryTableXYDataset)) {
382            return false;
383        }
384        CategoryTableXYDataset that = (CategoryTableXYDataset) obj;
385        if (!this.intervalDelegate.equals(that.intervalDelegate)) {
386            return false;
387        }
388        if (!this.values.equals(that.values)) {
389            return false;
390        }
391        return true;
392    }
393
394    /**
395     * Returns an independent copy of this dataset.
396     *
397     * @return A clone.
398     *
399     * @throws CloneNotSupportedException if there is some reason that cloning
400     *     cannot be performed.
401     */
402    public Object clone() throws CloneNotSupportedException {
403        CategoryTableXYDataset clone = (CategoryTableXYDataset) super.clone();
404        clone.values = (DefaultKeyedValues2D) this.values.clone();
405        clone.intervalDelegate = new IntervalXYDelegate(clone);
406        // need to configure the intervalDelegate to match the original
407        clone.intervalDelegate.setFixedIntervalWidth(getIntervalWidth());
408        clone.intervalDelegate.setAutoWidth(isAutoWidth());
409        clone.intervalDelegate.setIntervalPositionFactor(
410                getIntervalPositionFactor());
411        return clone;
412    }
413
414}