001/* =========================================================== 002 * JFreeChart : a free chart library for the Java(tm) platform 003 * =========================================================== 004 * 005 * (C) Copyright 2000-2021, 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 * Series.java 029 * ----------- 030 * (C) Copyright 2001-2021, by Object Refinery Limited. 031 * 032 * Original Author: David Gilbert (for Object Refinery Limited); 033 * Contributor(s): -; 034 * 035 */ 036 037package org.jfree.data.general; 038 039import java.beans.PropertyChangeListener; 040import java.beans.PropertyChangeSupport; 041import java.beans.PropertyVetoException; 042import java.beans.VetoableChangeListener; 043import java.beans.VetoableChangeSupport; 044import java.io.Serializable; 045import java.util.Objects; 046 047import javax.swing.event.EventListenerList; 048 049import org.jfree.chart.util.Args; 050 051/** 052 * Base class representing a data series. Subclasses are left to implement the 053 * actual data structures. 054 * <P> 055 * The series has two properties ("Key" and "Description") for which you can 056 * register a {@code PropertyChangeListener}. 057 * <P> 058 * You can also register a {@link SeriesChangeListener} to receive notification 059 * of changes to the series data. 060 */ 061public abstract class Series implements Cloneable, Serializable { 062 063 /** For serialization. */ 064 private static final long serialVersionUID = -6906561437538683581L; 065 066 /** The key for the series. */ 067 private Comparable key; 068 069 /** A description of the series. */ 070 private String description; 071 072 /** Storage for registered change listeners. */ 073 private EventListenerList listeners; 074 075 /** Object to support property change notification. */ 076 private PropertyChangeSupport propertyChangeSupport; 077 078 /** Object to support property change notification. */ 079 private VetoableChangeSupport vetoableChangeSupport; 080 081 /** A flag that controls whether or not changes are notified. */ 082 private boolean notify; 083 084 /** 085 * Creates a new series with the specified key. 086 * 087 * @param key the series key ({@code null} not permitted). 088 */ 089 protected Series(Comparable key) { 090 this(key, null); 091 } 092 093 /** 094 * Creates a new series with the specified key and description. 095 * 096 * @param key the series key ({@code null} NOT permitted). 097 * @param description the series description ({@code null} permitted). 098 */ 099 protected Series(Comparable key, String description) { 100 Args.nullNotPermitted(key, "key"); 101 this.key = key; 102 this.description = description; 103 this.listeners = new EventListenerList(); 104 this.propertyChangeSupport = new PropertyChangeSupport(this); 105 this.vetoableChangeSupport = new VetoableChangeSupport(this); 106 this.notify = true; 107 } 108 109 /** 110 * Returns the key for the series. 111 * 112 * @return The series key (never {@code null}). 113 * 114 * @see #setKey(Comparable) 115 */ 116 public Comparable getKey() { 117 return this.key; 118 } 119 120 /** 121 * Sets the key for the series and sends a {@code VetoableChangeEvent} 122 * (with the property name "Key") to all registered listeners. For 123 * backwards compatibility, this method also fires a regular 124 * {@code PropertyChangeEvent}. If the key change is vetoed this 125 * method will throw an IllegalArgumentException. 126 * 127 * @param key the key ({@code null} not permitted). 128 * 129 * @see #getKey() 130 */ 131 public void setKey(Comparable key) { 132 Args.nullNotPermitted(key, "key"); 133 Comparable old = this.key; 134 try { 135 // if this series belongs to a dataset, the dataset might veto the 136 // change if it results in two series within the dataset having the 137 // same key 138 this.vetoableChangeSupport.fireVetoableChange("Key", old, key); 139 this.key = key; 140 // prior to 1.0.14, we just fired a PropertyChange - so we need to 141 // keep doing this 142 this.propertyChangeSupport.firePropertyChange("Key", old, key); 143 } catch (PropertyVetoException e) { 144 throw new IllegalArgumentException(e.getMessage()); 145 } 146 } 147 148 /** 149 * Returns a description of the series. 150 * 151 * @return The series description (possibly {@code null}). 152 * 153 * @see #setDescription(String) 154 */ 155 public String getDescription() { 156 return this.description; 157 } 158 159 /** 160 * Sets the description of the series and sends a 161 * {@code PropertyChangeEvent} to all registered listeners. 162 * 163 * @param description the description ({@code null} permitted). 164 * 165 * @see #getDescription() 166 */ 167 public void setDescription(String description) { 168 String old = this.description; 169 this.description = description; 170 this.propertyChangeSupport.firePropertyChange("Description", old, 171 description); 172 } 173 174 /** 175 * Returns the flag that controls whether or not change events are sent to 176 * registered listeners. 177 * 178 * @return A boolean. 179 * 180 * @see #setNotify(boolean) 181 */ 182 public boolean getNotify() { 183 return this.notify; 184 } 185 186 /** 187 * Sets the flag that controls whether or not change events are sent to 188 * registered listeners. 189 * 190 * @param notify the new value of the flag. 191 * 192 * @see #getNotify() 193 */ 194 public void setNotify(boolean notify) { 195 if (this.notify != notify) { 196 this.notify = notify; 197 fireSeriesChanged(); 198 } 199 } 200 201 /** 202 * Returns {@code true} if the series contains no data items, and 203 * {@code false} otherwise. 204 * 205 * @return A boolean. 206 */ 207 public boolean isEmpty() { 208 return (getItemCount() == 0); 209 } 210 211 /** 212 * Returns the number of data items in the series. 213 * 214 * @return The number of data items in the series. 215 */ 216 public abstract int getItemCount(); 217 218 /** 219 * Returns a clone of the series. 220 * <P> 221 * Notes: 222 * <ul> 223 * <li>No need to clone the name or description, since String object is 224 * immutable.</li> 225 * <li>We set the listener list to empty, since the listeners did not 226 * register with the clone.</li> 227 * <li>Same applies to the PropertyChangeSupport instance.</li> 228 * </ul> 229 * 230 * @return A clone of the series. 231 * 232 * @throws CloneNotSupportedException not thrown by this class, but 233 * subclasses may differ. 234 */ 235 @Override 236 public Object clone() throws CloneNotSupportedException { 237 Series clone = (Series) super.clone(); 238 clone.listeners = new EventListenerList(); 239 clone.propertyChangeSupport = new PropertyChangeSupport(clone); 240 clone.vetoableChangeSupport = new VetoableChangeSupport(clone); 241 return clone; 242 } 243 244 /** 245 * Tests the series for equality with another object. 246 * 247 * @param obj the object ({@code null} permitted). 248 * 249 * @return {@code true} or {@code false}. 250 */ 251 @Override 252 public boolean equals(Object obj) { 253 if (obj == this) { 254 return true; 255 } 256 if (!(obj instanceof Series)) { 257 return false; 258 } 259 Series that = (Series) obj; 260 if (!getKey().equals(that.getKey())) { 261 return false; 262 } 263 if (!Objects.equals(getDescription(), that.getDescription())) { 264 return false; 265 } 266 return true; 267 } 268 269 /** 270 * Returns a hash code. 271 * 272 * @return A hash code. 273 */ 274 @Override 275 public int hashCode() { 276 int result; 277 result = this.key.hashCode(); 278 result = 29 * result + (this.description != null 279 ? this.description.hashCode() : 0); 280 return result; 281 } 282 283 /** 284 * Registers an object with this series, to receive notification whenever 285 * the series changes. 286 * <P> 287 * Objects being registered must implement the {@link SeriesChangeListener} 288 * interface. 289 * 290 * @param listener the listener to register. 291 */ 292 public void addChangeListener(SeriesChangeListener listener) { 293 this.listeners.add(SeriesChangeListener.class, listener); 294 } 295 296 /** 297 * Deregisters an object, so that it not longer receives notification 298 * whenever the series changes. 299 * 300 * @param listener the listener to deregister. 301 */ 302 public void removeChangeListener(SeriesChangeListener listener) { 303 this.listeners.remove(SeriesChangeListener.class, listener); 304 } 305 306 /** 307 * General method for signalling to registered listeners that the series 308 * has been changed. 309 */ 310 public void fireSeriesChanged() { 311 if (this.notify) { 312 notifyListeners(new SeriesChangeEvent(this)); 313 } 314 } 315 316 /** 317 * Sends a change event to all registered listeners. 318 * 319 * @param event contains information about the event that triggered the 320 * notification. 321 */ 322 protected void notifyListeners(SeriesChangeEvent event) { 323 324 Object[] listenerList = this.listeners.getListenerList(); 325 for (int i = listenerList.length - 2; i >= 0; i -= 2) { 326 if (listenerList[i] == SeriesChangeListener.class) { 327 ((SeriesChangeListener) listenerList[i + 1]).seriesChanged( 328 event); 329 } 330 } 331 332 } 333 334 /** 335 * Adds a property change listener to the series. 336 * 337 * @param listener the listener. 338 */ 339 public void addPropertyChangeListener(PropertyChangeListener listener) { 340 this.propertyChangeSupport.addPropertyChangeListener(listener); 341 } 342 343 /** 344 * Removes a property change listener from the series. 345 * 346 * @param listener the listener. 347 */ 348 public void removePropertyChangeListener(PropertyChangeListener listener) { 349 this.propertyChangeSupport.removePropertyChangeListener(listener); 350 } 351 352 /** 353 * Fires a property change event. 354 * 355 * @param property the property key. 356 * @param oldValue the old value. 357 * @param newValue the new value. 358 */ 359 protected void firePropertyChange(String property, Object oldValue, 360 Object newValue) { 361 this.propertyChangeSupport.firePropertyChange(property, oldValue, 362 newValue); 363 } 364 365 /** 366 * Adds a vetoable property change listener to the series. 367 * 368 * @param listener the listener. 369 */ 370 public void addVetoableChangeListener(VetoableChangeListener listener) { 371 this.vetoableChangeSupport.addVetoableChangeListener(listener); 372 } 373 374 /** 375 * Removes a vetoable property change listener from the series. 376 * 377 * @param listener the listener. 378 */ 379 public void removeVetoableChangeListener(VetoableChangeListener listener) { 380 this.vetoableChangeSupport.removeVetoableChangeListener(listener); 381 } 382 383 /** 384 * Fires a vetoable property change event. 385 * 386 * @param property the property key. 387 * @param oldValue the old value. 388 * @param newValue the new value. 389 * 390 * @throws PropertyVetoException if the change was vetoed. 391 */ 392 protected void fireVetoableChange(String property, Object oldValue, 393 Object newValue) throws PropertyVetoException { 394 this.vetoableChangeSupport.fireVetoableChange(property, oldValue, 395 newValue); 396 } 397 398}