XYSeries


1   /* ======================================
2    * JFreeChart : a free Java chart library
3    * ======================================
4    *
5    * Project Info:  http://www.jfree.org/jfreechart/index.html
6    * Project Lead:  David Gilbert (david.gilbert@object-refinery.com);
7    *
8    * (C) Copyright 2000-2003, by Object Refinery Limited and Contributors.
9    *
10   * This library is free software; you can redistribute it and/or modify it under the terms
11   * of the GNU Lesser General Public License as published by the Free Software Foundation;
12   * either version 2.1 of the License, or (at your option) any later version.
13   *
14   * This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY;
15   * without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
16   * See the GNU Lesser General Public License for more details.
17   *
18   * You should have received a copy of the GNU Lesser General Public License along with this
19   * library; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330,
20   * Boston, MA 02111-1307, USA.
21   *
22   * -------------
23   * XYSeries.java
24   * -------------
25   * (C) Copyright 2001-2003, Object Refinery Limited and Contributors.
26   *
27   * Original Author:  David Gilbert (for Object Refinery Limited);
28   * Contributor(s):   Aaron Metzger;
29   *                   Jonathan Gabbai;
30   *                   Richard Atkinson;
31   *
32   * $Id: XYSeries.java,v 1.10 2003/11/28 11:37:28 mungady Exp $
33   *
34   * Changes
35   * -------
36   * 15-Nov-2001 : Version 1 (DG);
37   * 03-Apr-2002 : Added an add(double, double) method (DG);
38   * 29-Apr-2002 : Added a clear() method (ARM);
39   * 06-Jun-2002 : Updated Javadoc comments (DG);
40   * 29-Aug-2002 : Modified to give user control over whether or not duplicate x-values are
41   *               allowed (DG);
42   * 07-Oct-2002 : Fixed errors reported by Checkstyle (DG);
43   * 11-Nov-2002 : Added maximum item count, code contributed by Jonathan Gabbai (DG);
44   * 26-Mar-2003 : Implemented Serializable (DG);
45   * 04-Aug-2003 : Added getItems() method (DG);
46   * 15-Aug-2003 : Changed 'data' from private to protected, added new add(...) methods with a
47   *               'notify' argument (DG);
48   * 22-Sep-2003 : Added getAllowDuplicateXValues() method (RA);
49   *
50   */
51  
52  package org.jfree.data;
53  
54  import java.io.Serializable  ;
55  import java.util.Collections  ;
56  import java.util.List  ;
57  
58  import org.jfree.util.ObjectUtils;
59  
60  /**
61   * Represents a sequence of zero or more data items in the form (x, y).
62   *
63   * @author David Gilbert
64   */
65  public class XYSeries extends Series implements Serializable   {
66  
67      /** Storage for the data items in the series. */
68      protected List   data;
69  
70      // In version 0.9.12, in response to several developer requests, I changed the 'data' attribute 
71      // from 'private' to 'protected', so that others can make subclasses that work directly with 
72      // the underlying data structure.
73  
74      /** The maximum number of items for the series. */
75      private int maximumItemCount = Integer.MAX_VALUE;
76  
77      /** A flag that controls whether or not duplicate x-values are allowed. */
78      private boolean allowDuplicateXValues;
79  
80      /**
81       * Constructs a new xy-series that contains no data.
82       * <p>
83       * By default, duplicate x-values will be allowed for the series.
84       *
85       * @param name  the series name.
86       */
87      public XYSeries(String   name) {
88          this(name, true);
89      }
90  
91      /**
92       * Constructs a new xy-series that contains no data.  You can specify whether or not
93       * duplicate x-values are allowed for the series.
94       *
95       * @param name  the series name.
96       * @param allowDuplicateXValues  a flag that controls whether duplicate x-values are allowed.
97       */
98      public XYSeries(String   name, boolean allowDuplicateXValues) {
99          super(name);
100         this.allowDuplicateXValues = allowDuplicateXValues;
101         this.data = new java.util.ArrayList  ();
102     }
103 
104     /**
105      * Returns whether duplicate X-Values are allowed.
106      *
107      * @return a boolean.
108      */
109     public boolean getAllowDuplicateXValues() {
110         return this.allowDuplicateXValues;
111     }
112 
113     /**
114      * Returns the number of items in the series.
115      *
116      * @return the item count.
117      */
118     public int getItemCount() {
119         return this.data.size();
120     }
121 
122     /**
123      * Returns the list of data items for the series (the list contains {@link XYDataItem} 
124      * objects and is unmodifiable).
125      * 
126      * @return The list of data items.
127      */
128     public List   getItems() {
129         return Collections.unmodifiableList(this.data);    
130     }
131     
132     /**
133      * Returns the maximum number of items that will be retained in the series.
134      * <P>
135      * The default value is <code>Integer.MAX_VALUE</code>).
136      *
137      * @return the maximum item count.
138      */
139     public int getMaximumItemCount() {
140         return this.maximumItemCount;
141     }
142 
143     /**
144      * Sets the maximum number of items that will be retained in the series.
145      * <P>
146      * If you add a new item to the series such that the number of items will exceed the
147      * maximum item count, then the FIRST element in the series is automatically removed,
148      * ensuring that the maximum item count is not exceeded.
149      *
150      * @param maximum  the maximum.
151      */
152     public void setMaximumItemCount(int maximum) {
153         this.maximumItemCount = maximum;
154     }
155 
156     /**
157      * Adds a data item to the series. A {@link SeriesChangeEvent} is sent to all registered 
158      * listeners.
159      *
160      * @param item  the (x, y) item.
161      *
162      * @throws SeriesException if there is a problem adding the data.
163      */
164     public void add(XYDataItem item) throws SeriesException {
165         add(item, true);
166     }
167     
168     /**
169      * Adds a data item to the series.  If requested (via <code>notify</code>), a
170      * {@link SeriesChangeEvent} is sent to all registered listeners.
171      *
172      * @param item  the (x, y) item.
173      * @param notify  a flag that controls whether or not a {@link SeriesChangeEvent} is sent to 
174      *                all registered listeners.
175      *
176      * @throws SeriesException if there is a problem adding the data.
177      */
178     public void add(XYDataItem item, boolean notify) throws SeriesException {
179 
180         // check arguments...
181         if (item == null) {
182             throw new IllegalArgumentException  ("XYSeries.add(...): null item not allowed.");
183         }
184 
185         // make the change (if it's not a duplicate x-value)...
186         boolean changed = false;
187         int index = Collections.binarySearch(data, item);
188         if (index < 0) {
189             data.add(-index - 1, item);
190          
191             // check if this addition will exceed the maximum item count...
192             if (getItemCount() > this.maximumItemCount) {
193                 this.data.remove(0);
194             }
195             changed = true;
196         }
197         else {
198             if (allowDuplicateXValues == true) {
199                 data.add(index, item);
200                 if (getItemCount() > this.maximumItemCount) {
201                     this.data.remove(0);
202                 }
203                 changed = true;
204             }
205             else {
206                 throw new SeriesException("XYSeries.add(...): x-value already exists.");
207             }
208         }
209         
210         if (notify && changed) {
211             fireSeriesChanged();
212         }
213 
214     }
215 
216     /**
217      * Adds a data item to the series.
218      *
219      * @param x  the x value.
220      * @param y  the y value.
221      *
222      * @throws SeriesException if there is a problem adding the data.
223      */
224     public void add(double x, double y) throws SeriesException {
225         add(new Double  (x), new Double  (y), true);
226     }
227 
228     /**
229      * Adds a data item to the series.
230      *
231      * @param x  the x value.
232      * @param y  the y value.
233      * @param notify  a flag that controls whether or not a {@link SeriesChangeEvent} is sent to 
234      *                all registered listeners.
235      *
236      * @throws SeriesException if there is a problem adding the data.
237      */
238     public void add(double x, double y, boolean notify) throws SeriesException {
239         add(new Double  (x), new Double  (y), notify);
240     }
241 
242     /**
243      * Adds a data item to the series.
244      * <P>
245      * The unusual pairing of parameter types is to make it easier to add null y-values.
246      *
247      * @param x  the x value.
248      * @param y  the y value.
249      *
250      * @throws SeriesException if there is a problem adding the data.
251      */
252     public void add(double x, Number   y) throws SeriesException {
253         add(new Double  (x), y);
254     }
255 
256     /**
257      * Adds a data item to the series.
258      * <P>
259      * The unusual pairing of parameter types is to make it easier to add null y-values.
260      *
261      * @param x  the x value.
262      * @param y  the y value.
263      * @param notify  a flag that controls whether or not a {@link SeriesChangeEvent} is sent to 
264      *                all registered listeners.
265      *
266      * @throws SeriesException if there is a problem adding the data.
267      */
268     public void add(double x, Number   y, boolean notify) throws SeriesException {
269         add(new Double  (x), y, notify);
270     }
271 
272     /**
273      * Adds new data to the series.
274      * <P>
275      * Throws an exception if the x-value is a duplicate AND the allowDuplicateXValues flag is
276      * false.
277      *
278      * @param x  the x-value.
279      * @param y  the y-value.
280      *
281      * @throws SeriesException if there is a problem adding the data.
282      */
283     public void add(Number   x, Number   y) throws SeriesException {
284         add(x, y, true);
285     }
286     
287     /**
288      * Adds new data to the series.
289      * <P>
290      * Throws an exception if the x-value is a duplicate AND the allowDuplicateXValues flag is
291      * false.
292      *
293      * @param x  the x-value.
294      * @param y  the y-value.
295      * @param notify  a flag the controls whether or not a {@link SeriesChangeEvent} is sent to 
296      *                all registered listeners.
297      *
298      * @throws SeriesException if there is a problem adding the data.
299      */
300     public void add(Number   x, Number   y, boolean notify) throws SeriesException {
301         XYDataItem item = new XYDataItem(x, y);
302         add(item, notify);
303     }
304 
305     /**
306      * Deletes a range of items from the series.
307      *
308      * @param start  the start index (zero-based).
309      * @param end  the end index (zero-based).
310      */
311     public void delete(int start, int end) {
312         for (int i = start; i <= end; i++) {
313             data.remove(start);
314         }
315         fireSeriesChanged();
316     }
317 
318     /**
319      * Removes all data items from the series.
320      */
321     public void clear() {
322 
323         if (this.data.size() > 0) {
324             this.data.clear();
325             fireSeriesChanged();
326         }
327 
328     }
329 
330     /**
331      * Return the data pair with the specified index.
332      *
333      * @param index  The index.
334      *
335      * @return The data pair with the specified index.
336      * @deprecated Use getDataItem(index).
337      */
338     public XYDataPair getDataPair(int index) {
339         return (XYDataPair) data.get(index);
340     }
341 
342     /**
343      * Return the data item with the specified index.
344      *
345      * @param index  The index.
346      *
347      * @return The data item with the specified index.
348      */
349     public XYDataItem getDataItem(int index) {
350         return (XYDataItem) data.get(index);
351     }
352 
353     /**
354      * Returns the x-value at the specified index.
355      *
356      * @param index  The index.
357      *
358      * @return The x-value.
359      */
360     public Number   getXValue(int index) {
361         return getDataItem(index).getX();
362     }
363 
364     /**
365      * Returns the y-value at the specified index.
366      *
367      * @param index  The index.
368      *
369      * @return The y-value.
370      */
371     public Number   getYValue(int index) {
372         return getDataItem(index).getY();
373     }
374 
375     /**
376      * Updates the value of an item in the series.
377      *
378      * @param index  The item (zero based index).
379      * @param y  The new value.
380      */
381     public void update(int index, Number   y) {
382         XYDataItem item = getDataItem(index);
383         item.setY(y);
384         fireSeriesChanged();
385     }
386 
387     /**
388      * Returns a clone of the series.
389      *
390      * @return a clone of the time series.
391      */
392     public Object   clone() {
393 
394         Object   clone = createCopy(0, getItemCount() - 1);
395         return clone;
396 
397     }
398 
399     /**
400      * Creates a new series by copying a subset of the data in this time series.
401      *
402      * @param start  The index of the first item to copy.
403      * @param end  The index of the last item to copy.
404      *
405      * @return A series containing a copy of this series from start until end.
406      */
407     public XYSeries createCopy(int start, int end) {
408 
409         XYSeries copy = (XYSeries) super.clone();
410         //copy.listeners = new java.util.ArrayList();
411         //copy.propertyChangeSupport = new PropertyChangeSupport(copy);
412 
413         copy.data = new java.util.ArrayList  ();
414         if (data.size() > 0) {
415             for (int index = start; index <= end; index++) {
416                 XYDataItem item = (XYDataItem) this.data.get(index);
417                 XYDataItem clone = (XYDataItem) item.clone();
418                 try {
419                     copy.add(clone);
420                 }
421                 catch (SeriesException e) {
422                     System.err.println("XYSeries.createCopy(): unable to add cloned data pair.");
423                 }
424             }
425         }
426 
427         return copy;
428 
429     }
430 
431     /**
432      * Tests this series for equality with an arbitrary object.
433      *
434      * @param obj  the object.
435      *
436      * @return A boolean.
437      */
438     public boolean equals(Object   obj) {
439 
440         if (obj == null) {
441             return false;
442         }
443 
444         if (obj == this) {
445             return true;
446         }
447 
448         if (obj instanceof XYSeries) {
449             XYSeries s = (XYSeries) obj;
450             boolean b0 = ObjectUtils.equal(this.data, s.data);
451             boolean b1 = (this.maximumItemCount == s.maximumItemCount);
452             boolean b2 = (this.allowDuplicateXValues == s.allowDuplicateXValues);
453             return b0 && b1 && b2;
454         }
455 
456         return false;
457 
458     }
459 
460 }
461 
462
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags