001/* =========================================================== 002 * Orson Charts : a 3D chart library for the Java(tm) platform 003 * =========================================================== 004 * 005 * (C)opyright 2013-2022, by David Gilbert. All rights reserved. 006 * 007 * https://github.com/jfree/orson-charts 008 * 009 * This program is free software: you can redistribute it and/or modify 010 * it under the terms of the GNU General Public License as published by 011 * the Free Software Foundation, either version 3 of the License, or 012 * (at your option) any later version. 013 * 014 * This program is distributed in the hope that it will be useful, 015 * but WITHOUT ANY WARRANTY; without even the implied warranty of 016 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 017 * GNU General Public License for more details. 018 * 019 * You should have received a copy of the GNU General Public License 020 * along with this program. If not, see <http://www.gnu.org/licenses/>. 021 * 022 * [Oracle and Java are registered trademarks of Oracle and/or its affiliates. 023 * Other names may be trademarks of their respective owners.] 024 * 025 * If you do not wish to be bound by the terms of the GPL, an alternative 026 * commercial license can be purchased. For details, please see visit the 027 * Orson Charts home page: 028 * 029 * http://www.object-refinery.com/orsoncharts/index.html 030 * 031 */ 032 033package org.jfree.chart3d.data; 034 035import java.io.Serializable; 036import java.util.List; 037 038import org.jfree.chart3d.internal.Args; 039import org.jfree.chart3d.plot.PiePlot3D; 040 041/** 042 * A dataset that can be used with a {@link PiePlot3D}. This class represents 043 * an ordered list of (key, value) items. The keys can be any instance of 044 * {@link Comparable} ({@code String} is commonly used) and the values 045 * can be any {@link Number} instance (bearing in mind that the downstream 046 * code will use the {@code toDouble()} method to read values) or 047 * {@code null}. 048 * <br><br> 049 * This class provides an implementation of 050 * {@code KeyedValues<Number>}, so the following useful utility 051 * methods can be used: 052 * <ul> 053 * {@link DataUtils#total(org.jfree.chart3d.data.Values)} 054 * {@link JSONUtils#writeKeyedValues(org.jfree.chart3d.data.KeyedValues)} 055 * </ul> 056 * <br><br> 057 * NOTE: This class is serializable, but the serialization format is subject 058 * to change in future releases and should not be relied upon for persisting 059 * instances of this class. 060 * 061 * @param <K> the key type. 062 */ 063@SuppressWarnings("serial") 064public final class StandardPieDataset3D<K extends Comparable<K>> 065 extends AbstractDataset3D implements PieDataset3D<K>, Serializable { 066 067 /** Storage for the data. */ 068 private DefaultKeyedValues<K, Number> data; 069 070 /** 071 * Creates a new (empty) dataset. 072 */ 073 public StandardPieDataset3D() { 074 this.data = new DefaultKeyedValues<>(); 075 } 076 077 /** 078 * Returns the number of items in the dataset. 079 * 080 * @return The number of items in the dataset. 081 */ 082 @Override 083 public int getItemCount() { 084 return this.data.getItemCount(); 085 } 086 087 /** 088 * Returns the key for the specified item in the list. 089 * 090 * @param item the item index. 091 * 092 * @return The key. 093 */ 094 @Override 095 public K getKey(int item) { 096 return this.data.getKey(item); 097 } 098 099 /** 100 * Returns the index for the specified key, or {@code -1} if the key 101 * is not present in the list. 102 * 103 * @param key the key ({@code null} not permitted). 104 * 105 * @return The item index, or {@code -1}. 106 */ 107 @Override 108 public int getIndex(K key) { 109 return this.data.getIndex(key); 110 } 111 112 /** 113 * Returns the value for the specified item. 114 * 115 * @param item the item index. 116 * 117 * @return The value for the specified item (possibly {@code null}). 118 */ 119 @Override 120 public Number getValue(int item) { 121 return this.data.getValue(item); 122 } 123 124 /** 125 * Returns the value associated with the specified key, or 126 * {@code null}. 127 * 128 * @param key the key ({@code null} not permitted). 129 * 130 * @return The value (possibly {@code null}). 131 */ 132 @Override 133 public Number getValue(K key) { 134 return this.data.getValue(key); 135 } 136 137 /** 138 * Adds a value to the dataset (if there is already a value with the given 139 * key, the value is overwritten) and sends a {@link Dataset3DChangeEvent} 140 * to all registered listeners. 141 * 142 * @param key the key ({@code null} not permitted). 143 * @param value the value. 144 */ 145 public void add(K key, double value) { 146 add(key, Double.valueOf(value)); 147 } 148 149 /** 150 * Adds a value to the dataset (if there is already a value with the given 151 * key, the value is overwritten) and sends a {@link Dataset3DChangeEvent} 152 * to all registered listeners. 153 * 154 * @param key the key ({@code null} not permitted). 155 * @param value the value ({@code null} permitted). 156 */ 157 public void add(K key, Number value) { 158 Args.nullNotPermitted(key, "key"); 159 this.data.put(key, value); 160 fireDatasetChanged(); 161 } 162 163 /** 164 * Returns a list of all the keys in the dataset. Note that the list will 165 * be a copy, so modifying it will not impact this dataset. 166 * 167 * @return A list of keys (possibly empty, but never {@code null}). 168 */ 169 @Override 170 public List<K> getKeys() { 171 return this.data.getKeys(); 172 } 173 174 /** 175 * Returns the value for the specified item as a double primitive. Where 176 * the {@link #getValue(int)} method returns {@code null}, this method 177 * returns {@code Double.NaN}. 178 * 179 * @param item the item index. 180 * 181 * @return The value for the specified item. 182 */ 183 @Override 184 public double getDoubleValue(int item) { 185 return this.data.getDoubleValue(item); 186 } 187 188 /** 189 * Tests this dataset for equality with an arbitrary object. 190 * 191 * @param obj the object ({@code null} not permitted). 192 * 193 * @return A boolean. 194 */ 195 @Override 196 public boolean equals(Object obj) { 197 if (obj == this) { 198 return true; 199 } 200 if (!(obj instanceof StandardPieDataset3D)) { 201 return false; 202 } 203 StandardPieDataset3D that = (StandardPieDataset3D) obj; 204 if (!this.data.equals(that.data)) { 205 return false; 206 } 207 return true; 208 } 209 210 /** 211 * Returns a string representation of this instance, primarily for 212 * debugging purposes. 213 * <br><br> 214 * Implementation note: the current implementation (which is subject to 215 * change) writes the dataset in JSON format using 216 * {@link JSONUtils#writeKeyedValues(org.jfree.chart3d.data.KeyedValues)}. 217 * 218 * @return A string. 219 */ 220 @Override 221 public String toString() { 222 return JSONUtils.writeKeyedValues(this); 223 } 224}