001/* =========================================================== 002 * Orson Charts : a 3D chart library for the Java(tm) platform 003 * =========================================================== 004 * 005 * (C)opyright 2013-2016, by Object Refinery Limited. All rights reserved. 006 * 007 * http://www.object-refinery.com/orsoncharts/index.html 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 com.orsoncharts.data; 034 035import java.io.Serializable; 036import java.util.List; 037 038import com.orsoncharts.util.ArgChecks; 039import com.orsoncharts.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(com.orsoncharts.data.Values)} 054 * {@link JSONUtils#writeKeyedValues(com.orsoncharts.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@SuppressWarnings("serial") 062public final class StandardPieDataset3D extends AbstractDataset3D 063 implements PieDataset3D, Serializable { 064 065 /** Storage for the data. */ 066 private DefaultKeyedValues<Number> data; 067 068 /** 069 * Creates a new (empty) dataset. 070 */ 071 public StandardPieDataset3D() { 072 this.data = new DefaultKeyedValues<Number>(); 073 } 074 075 /** 076 * Returns the number of items in the dataset. 077 * 078 * @return The number of items in the dataset. 079 */ 080 @Override 081 public int getItemCount() { 082 return this.data.getItemCount(); 083 } 084 085 /** 086 * Returns the key for the specified item in the list. 087 * 088 * @param item the item index. 089 * 090 * @return The key. 091 */ 092 @Override 093 public Comparable<?> getKey(int item) { 094 return this.data.getKey(item); 095 } 096 097 /** 098 * Returns the index for the specified key, or {@code -1} if the key 099 * is not present in the list. 100 * 101 * @param key the key ({@code null} not permitted). 102 * 103 * @return The item index, or {@code -1}. 104 */ 105 @Override 106 public int getIndex(Comparable<?> key) { 107 return this.data.getIndex(key); 108 } 109 110 /** 111 * Returns the value for the specified item. 112 * 113 * @param item the item index. 114 * 115 * @return The value for the specified item (possibly {@code null}). 116 */ 117 @Override 118 public Number getValue(int item) { 119 return this.data.getValue(item); 120 } 121 122 /** 123 * Returns the value associated with the specified key, or 124 * {@code null}. 125 * 126 * @param key the key ({@code null} not permitted). 127 * 128 * @return The value (possibly {@code null}). 129 */ 130 @Override 131 public Number getValue(Comparable<?> key) { 132 return this.data.getValue(key); 133 } 134 135 /** 136 * Adds a value to the dataset (if there is already a value with the given 137 * key, the value is overwritten) and sends a {@link Dataset3DChangeEvent} 138 * to all registered listeners. 139 * 140 * @param key the key ({@code null} not permitted). 141 * @param value the value. 142 */ 143 public void add(Comparable<?> key, double value) { 144 add(key, Double.valueOf(value)); 145 } 146 147 /** 148 * Adds a value to the dataset (if there is already a value with the given 149 * key, the value is overwritten) and sends a {@link Dataset3DChangeEvent} 150 * to all registered listeners. 151 * 152 * @param key the key ({@code null} not permitted). 153 * @param value the value ({@code null} permitted). 154 */ 155 public void add(Comparable<?> key, Number value) { 156 ArgChecks.nullNotPermitted(key, "key"); 157 this.data.put(key, value); 158 fireDatasetChanged(); 159 } 160 161 /** 162 * Returns a list of all the keys in the dataset. Note that the list will 163 * be a copy, so modifying it will not impact this dataset. 164 * 165 * @return A list of keys (possibly empty, but never {@code null}). 166 */ 167 @Override 168 public List<Comparable<?>> getKeys() { 169 return this.data.getKeys(); 170 } 171 172 /** 173 * Returns the value for the specified item as a double primitive. Where 174 * the {@link #getValue(int)} method returns {@code null}, this method 175 * returns {@code Double.NaN}. 176 * 177 * @param item the item index. 178 * 179 * @return The value for the specified item. 180 */ 181 @Override 182 public double getDoubleValue(int item) { 183 return this.data.getDoubleValue(item); 184 } 185 186 /** 187 * Tests this dataset for equality with an arbitrary object. 188 * 189 * @param obj the object ({@code null} not permitted). 190 * 191 * @return A boolean. 192 */ 193 @Override 194 public boolean equals(Object obj) { 195 if (obj == this) { 196 return true; 197 } 198 if (!(obj instanceof StandardPieDataset3D)) { 199 return false; 200 } 201 StandardPieDataset3D that = (StandardPieDataset3D) obj; 202 if (!this.data.equals(that.data)) { 203 return false; 204 } 205 return true; 206 } 207 208 /** 209 * Returns a string representation of this instance, primarily for 210 * debugging purposes. 211 * <br><br> 212 * Implementation note: the current implementation (which is subject to 213 * change) writes the dataset in JSON format using 214 * {@link JSONUtils#writeKeyedValues(com.orsoncharts.data.KeyedValues)}. 215 * 216 * @return A string. 217 */ 218 @Override 219 public String toString() { 220 return JSONUtils.writeKeyedValues(this); 221 } 222}