001/* ===========================================================
002 * JFreeChart : a free chart library for the Java(tm) platform
003 * ===========================================================
004 *
005 * (C) Copyright 2000-2020, 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 * TimePeriodValuesCollection.java
029 * -------------------------------
030 * (C) Copyright 2003-2016, by Object Refinery Limited.
031 *
032 * Original Author:  David Gilbert (for Object Refinery Limited);
033 * Contributor(s):   -;
034 *
035 * Changes
036 * -------
037 * 22-Apr-2003 : Version 1 (DG);
038 * 05-May-2004 : Now extends AbstractIntervalXYDataset (DG);
039 * 15-Jul-2004 : Switched getX() with getXValue() and getY() with
040 *               getYValue() (DG);
041 * 06-Oct-2004 : Updated for changes in DomainInfo interface (DG);
042 * 11-Jan-2005 : Removed deprecated code in preparation for 1.0.0 release (DG);
043 * ------------- JFREECHART 1.0.x ---------------------------------------------
044 * 03-Oct-2006 : Deprecated get/setDomainIsPointsInTime() (DG);
045 * 11-Jun-2007 : Fixed bug in getDomainBounds() method, and changed default
046 *               value for domainIsPointsInTime to false (DG);
047 * 03-Jul-2013 : Use ParamChecks (DG);
048 *
049 */
050
051package org.jfree.data.time;
052
053import java.io.Serializable;
054import java.util.Iterator;
055import java.util.List;
056import org.jfree.chart.util.ObjectUtils;
057import org.jfree.chart.util.Args;
058
059import org.jfree.data.DomainInfo;
060import org.jfree.data.Range;
061import org.jfree.data.xy.AbstractIntervalXYDataset;
062import org.jfree.data.xy.IntervalXYDataset;
063
064/**
065 * A collection of {@link TimePeriodValues} objects.
066 * <P>
067 * This class implements the {@link org.jfree.data.xy.XYDataset} interface, as
068 * well as the extended {@link IntervalXYDataset} interface.  This makes it a
069 * convenient dataset for use with the {@link org.jfree.chart.plot.XYPlot}
070 * class.
071 */
072public class TimePeriodValuesCollection extends AbstractIntervalXYDataset
073        implements IntervalXYDataset, DomainInfo, Serializable {
074
075    /** For serialization. */
076    private static final long serialVersionUID = -3077934065236454199L;
077
078    /** Storage for the time series. */
079    private List data;
080
081    /**
082     * The position within a time period to return as the x-value (START,
083     * MIDDLE or END).
084     */
085    private TimePeriodAnchor xPosition;
086
087    /**
088     * Constructs an empty dataset.
089     */
090    public TimePeriodValuesCollection() {
091        this((TimePeriodValues) null);
092    }
093
094    /**
095     * Constructs a dataset containing a single series.  Additional series can
096     * be added.
097     *
098     * @param series  the series ({@code null} ignored).
099     */
100    public TimePeriodValuesCollection(TimePeriodValues series) {
101        this.data = new java.util.ArrayList();
102        this.xPosition = TimePeriodAnchor.MIDDLE;
103        if (series != null) {
104            this.data.add(series);
105            series.addChangeListener(this);
106        }
107    }
108
109    /**
110     * Returns the position of the X value within each time period.
111     *
112     * @return The position (never {@code null}).
113     *
114     * @see #setXPosition(TimePeriodAnchor)
115     */
116    public TimePeriodAnchor getXPosition() {
117        return this.xPosition;
118    }
119
120    /**
121     * Sets the position of the x axis within each time period.
122     *
123     * @param position  the position ({@code null} not permitted).
124     *
125     * @see #getXPosition()
126     */
127    public void setXPosition(TimePeriodAnchor position) {
128        Args.nullNotPermitted(position, "position");
129        this.xPosition = position;
130    }
131
132    /**
133     * Returns the number of series in the collection.
134     *
135     * @return The series count.
136     */
137    @Override
138    public int getSeriesCount() {
139        return this.data.size();
140    }
141
142    /**
143     * Returns a series.
144     *
145     * @param series  the index of the series (zero-based).
146     *
147     * @return The series.
148     */
149    public TimePeriodValues getSeries(int series) {
150        if ((series < 0) || (series >= getSeriesCount())) {
151            throw new IllegalArgumentException("Index 'series' out of range.");
152        }
153        return (TimePeriodValues) this.data.get(series);
154    }
155
156    /**
157     * Returns the key for a series.
158     *
159     * @param series  the index of the series (zero-based).
160     *
161     * @return The key for a series.
162     */
163    @Override
164    public Comparable getSeriesKey(int series) {
165        // defer argument checking
166        return getSeries(series).getKey();
167    }
168
169    /**
170     * Adds a series to the collection.  A
171     * {@link org.jfree.data.general.DatasetChangeEvent} is sent to all
172     * registered listeners.
173     *
174     * @param series  the time series.
175     */
176    public void addSeries(TimePeriodValues series) {
177        Args.nullNotPermitted(series, "series");
178        this.data.add(series);
179        series.addChangeListener(this);
180        fireDatasetChanged();
181    }
182
183    /**
184     * Removes the specified series from the collection.
185     *
186     * @param series  the series to remove ({@code null} not permitted).
187     */
188    public void removeSeries(TimePeriodValues series) {
189        Args.nullNotPermitted(series, "series");
190        this.data.remove(series);
191        series.removeChangeListener(this);
192        fireDatasetChanged();
193
194    }
195
196    /**
197     * Removes a series from the collection.
198     *
199     * @param index  the series index (zero-based).
200     */
201    public void removeSeries(int index) {
202        TimePeriodValues series = getSeries(index);
203        if (series != null) {
204            removeSeries(series);
205        }
206    }
207
208    /**
209     * Returns the number of items in the specified series.
210     * <P>
211     * This method is provided for convenience.
212     *
213     * @param series  the index of the series of interest (zero-based).
214     *
215     * @return The number of items in the specified series.
216     */
217    @Override
218    public int getItemCount(int series) {
219        return getSeries(series).getItemCount();
220    }
221
222    /**
223     * Returns the x-value for the specified series and item.
224     *
225     * @param series  the series (zero-based index).
226     * @param item  the item (zero-based index).
227     *
228     * @return The x-value for the specified series and item.
229     */
230    @Override
231    public Number getX(int series, int item) {
232        TimePeriodValues ts = (TimePeriodValues) this.data.get(series);
233        TimePeriodValue dp = ts.getDataItem(item);
234        TimePeriod period = dp.getPeriod();
235        return getX(period);
236    }
237
238    /**
239     * Returns the x-value for a time period.
240     *
241     * @param period  the time period.
242     *
243     * @return The x-value.
244     */
245    private long getX(TimePeriod period) {
246
247        if (this.xPosition == TimePeriodAnchor.START) {
248            return period.getStart().getTime();
249        }
250        else if (this.xPosition == TimePeriodAnchor.MIDDLE) {
251            return period.getStart().getTime()
252                / 2 + period.getEnd().getTime() / 2;
253        }
254        else if (this.xPosition == TimePeriodAnchor.END) {
255            return period.getEnd().getTime();
256        }
257        else {
258            throw new IllegalStateException("TimePeriodAnchor unknown.");
259        }
260
261    }
262
263    /**
264     * Returns the starting X value for the specified series and item.
265     *
266     * @param series  the series (zero-based index).
267     * @param item  the item (zero-based index).
268     *
269     * @return The starting X value for the specified series and item.
270     */
271    @Override
272    public Number getStartX(int series, int item) {
273        TimePeriodValues ts = (TimePeriodValues) this.data.get(series);
274        TimePeriodValue dp = ts.getDataItem(item);
275        return dp.getPeriod().getStart().getTime();
276    }
277
278    /**
279     * Returns the ending X value for the specified series and item.
280     *
281     * @param series  the series (zero-based index).
282     * @param item  the item (zero-based index).
283     *
284     * @return The ending X value for the specified series and item.
285     */
286    @Override
287    public Number getEndX(int series, int item) {
288        TimePeriodValues ts = (TimePeriodValues) this.data.get(series);
289        TimePeriodValue dp = ts.getDataItem(item);
290        return dp.getPeriod().getEnd().getTime();
291    }
292
293    /**
294     * Returns the y-value for the specified series and item.
295     *
296     * @param series  the series (zero-based index).
297     * @param item  the item (zero-based index).
298     *
299     * @return The y-value for the specified series and item.
300     */
301    @Override
302    public Number getY(int series, int item) {
303        TimePeriodValues ts = (TimePeriodValues) this.data.get(series);
304        TimePeriodValue dp = ts.getDataItem(item);
305        return dp.getValue();
306    }
307
308    /**
309     * Returns the starting Y value for the specified series and item.
310     *
311     * @param series  the series (zero-based index).
312     * @param item  the item (zero-based index).
313     *
314     * @return The starting Y value for the specified series and item.
315     */
316    @Override
317    public Number getStartY(int series, int item) {
318        return getY(series, item);
319    }
320
321    /**
322     * Returns the ending Y value for the specified series and item.
323     *
324     * @param series  the series (zero-based index).
325     * @param item  the item (zero-based index).
326     *
327     * @return The ending Y value for the specified series and item.
328     */
329    @Override
330    public Number getEndY(int series, int item) {
331        return getY(series, item);
332    }
333
334    /**
335     * Returns the minimum x-value in the dataset.
336     *
337     * @param includeInterval  a flag that determines whether or not the
338     *                         x-interval is taken into account.
339     *
340     * @return The minimum value.
341     */
342    @Override
343    public double getDomainLowerBound(boolean includeInterval) {
344        double result = Double.NaN;
345        Range r = getDomainBounds(includeInterval);
346        if (r != null) {
347            result = r.getLowerBound();
348        }
349        return result;
350    }
351
352    /**
353     * Returns the maximum x-value in the dataset.
354     *
355     * @param includeInterval  a flag that determines whether or not the
356     *                         x-interval is taken into account.
357     *
358     * @return The maximum value.
359     */
360    @Override
361    public double getDomainUpperBound(boolean includeInterval) {
362        double result = Double.NaN;
363        Range r = getDomainBounds(includeInterval);
364        if (r != null) {
365            result = r.getUpperBound();
366        }
367        return result;
368    }
369
370    /**
371     * Returns the range of the values in this dataset's domain.
372     *
373     * @param includeInterval  a flag that determines whether or not the
374     *                         x-interval is taken into account.
375     *
376     * @return The range.
377     */
378    @Override
379    public Range getDomainBounds(boolean includeInterval) {
380        boolean interval = includeInterval;
381        Range result = null;
382        Range temp = null;
383        Iterator iterator = this.data.iterator();
384        while (iterator.hasNext()) {
385            TimePeriodValues series = (TimePeriodValues) iterator.next();
386            int count = series.getItemCount();
387            if (count > 0) {
388                TimePeriod start = series.getTimePeriod(
389                        series.getMinStartIndex());
390                TimePeriod end = series.getTimePeriod(series.getMaxEndIndex());
391                if (!interval) {
392                    if (this.xPosition == TimePeriodAnchor.START) {
393                        TimePeriod maxStart = series.getTimePeriod(
394                                series.getMaxStartIndex());
395                        temp = new Range(start.getStart().getTime(),
396                                maxStart.getStart().getTime());
397                    }
398                    else if (this.xPosition == TimePeriodAnchor.MIDDLE) {
399                        TimePeriod minMiddle = series.getTimePeriod(
400                                series.getMinMiddleIndex());
401                        long s1 = minMiddle.getStart().getTime();
402                        long e1 = minMiddle.getEnd().getTime();
403                        TimePeriod maxMiddle = series.getTimePeriod(
404                                series.getMaxMiddleIndex());
405                        long s2 = maxMiddle.getStart().getTime();
406                        long e2 = maxMiddle.getEnd().getTime();
407                        temp = new Range(s1 + (e1 - s1) / 2,
408                                s2 + (e2 - s2) / 2);
409                    }
410                    else if (this.xPosition == TimePeriodAnchor.END) {
411                        TimePeriod minEnd = series.getTimePeriod(
412                                series.getMinEndIndex());
413                        temp = new Range(minEnd.getEnd().getTime(),
414                                end.getEnd().getTime());
415                    }
416                }
417                else {
418                    temp = new Range(start.getStart().getTime(),
419                            end.getEnd().getTime());
420                }
421                result = Range.combine(result, temp);
422            }
423        }
424        return result;
425    }
426
427    /**
428     * Tests this instance for equality with an arbitrary object.
429     *
430     * @param obj  the object ({@code null} permitted).
431     *
432     * @return A boolean.
433     */
434    @Override
435    public boolean equals(Object obj) {
436        if (obj == this) {
437            return true;
438        }
439        if (!(obj instanceof TimePeriodValuesCollection)) {
440            return false;
441        }
442        TimePeriodValuesCollection that = (TimePeriodValuesCollection) obj;
443        if (this.xPosition != that.xPosition) {
444            return false;
445        }
446        if (!ObjectUtils.equal(this.data, that.data)) {
447            return false;
448        }
449        return true;
450    }
451
452}