    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.xyz;
    034
    035import java.util.ArrayList;
    036import java.util.List;
    037import java.io.Serializable;
    038
    039import com.orsoncharts.util.ArgChecks;
    040import com.orsoncharts.util.ObjectUtils;
    041
    042/**
    043 * A data series containing a sequence of {@code (x, y, z)} data items.
    044 * The series has a key to identify it, and can be added to an
    045 * {@link XYZSeriesCollection} to create a dataset.
    046 * <br><br>
    047 * NOTE: This class is serializable, but the serialization format is subject
    048 * to change in future releases and should not be relied upon for persisting
    049 * instances of this class.
    050 */
    051@SuppressWarnings("serial")
    052public class XYZSeries implements Serializable {
    053
    054    /** The series key (never {@code null}). */
    055    private final Comparable<?> key;
    056
    057    /** The data items in the series. */
    058    private final List<XYZDataItem> items;
    059
    060    /**
    061     * Creates a new series with the specified key.
    062     *
    063     * @param key  the key ({@code null} not permitted).
    064     */
    065    public XYZSeries(Comparable<?> key) {
    066        ArgChecks.nullNotPermitted(key, "key");
    067        this.key = key;
    068        this.items = new ArrayList<XYZDataItem>();
    069    }
    070
    071    /**
    072     * Returns the series key.
    073     *
    074     * @return The series key (never {@code null}).
    075     */
    076    public Comparable<?> getKey() {
    077        return this.key;
    078    }
    079
    080    /**
    081     * Returns the number of items in the series.
    082     *
    083     * @return The number of items in the series.
    084     */
    085    public int getItemCount() {
    086        return this.items.size();
    087    }
    088
    089    /**
    090     * Returns the x-value for the specified item in the series.
    091     *
    092     * @param itemIndex  the item index.
    093     *
    094     * @return The x-value.
    095     */
    096    public double getXValue(int itemIndex) {
    097        return this.items.get(itemIndex).getX();
    098    }
    099
    100    /**
    101     * Returns the y-value for the specified item in the series.
    102     *
    103     * @param itemIndex  the item index.
    104     *
    105     * @return The y-value.
    106     */
    107    public double getYValue(int itemIndex) {
    108        return this.items.get(itemIndex).getY();
    109    }
    110
    111    /**
    112     * Returns the z-value for the specified item in the series.
    113     *
    114     * @param itemIndex  the item index.
    115     *
    116     * @return The z-value.
    117     */
    118    public double getZValue(int itemIndex) {
    119        return this.items.get(itemIndex).getZ();
    120    }
    121
    122    /**
    123     * Adds a new data item to the series.
    124     *
    125     * @param x  the x-value.
    126     * @param y  the y-value.
    127     * @param z  the z-value.
    128     */
    129    public void add(double x, double y, double z) {
    130        add(new XYZDataItem(x, y, z));
    131    }
    132
    133    /**
    134     * Adds a new data item to the series.
    135     *
    136     * @param item  the data item ({@code null} not permitted).
    137     */
    138    public void add(XYZDataItem item) {
    139        ArgChecks.nullNotPermitted(item, "item");
    140        this.items.add(item);
    141    }
    142
    143    /**
    144     * Tests this series for equality with an arbitrary object.
    145     *
    146     * @param obj  the object to test ({@code null} permitted).
    147     *
    148     * @return A boolean.
    149     */
    150    @Override
    151    public boolean equals(Object obj) {
    152        if (obj == this) {
    153            return true;
    154        }
    155        if (!(obj instanceof XYZSeries)) {
    156            return false;
    157        }
    158        XYZSeries that = (XYZSeries) obj;
    159        if (!this.key.equals(that.key)) {
    160            return false;
    161        }
    162        if (!this.items.equals(that.items)) {
    163            return false;
    164        }
    165        return true;
    166    }
    167
    168    @Override
    169    public int hashCode() {
    170        int hash = 7;
    171        hash = 41 * hash + ObjectUtils.hashCode(this.key);
    172        return hash;
    173    }
    174
    175}