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&lt;Number&gt;}, 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}