001/* ===========================================================
002 * JFreeChart : a free chart library for the Java(tm) platform
003 * ===========================================================
004 *
005 * (C) Copyright 2000-2017, 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 * CategoryItemEntity.java
029 * -----------------------
030 * (C) Copyright 2002-2016, by Object Refinery Limited and Contributors.
031 *
032 * Original Author:  David Gilbert (for Object Refinery Limited);
033 * Contributor(s):   Richard Atkinson;
034 *                   Christian W. Zuckschwerdt;
035 *
036 * Changes:
037 * --------
038 * 23-May-2002 : Version 1 (DG);
039 * 12-Jun-2002 : Added Javadoc comments (DG);
040 * 26-Jun-2002 : Added getImageMapAreaTag() method (DG);
041 * 05-Aug-2002 : Added new constructor to populate URLText
042 *               Moved getImageMapAreaTag() to ChartEntity (superclass) (RA);
043 * 03-Oct-2002 : Fixed errors reported by Checkstyle (DG);
044 * 30-Jul-2003 : Added CategoryDataset reference (CZ);
045 * 20-May-2004 : Added equals() and clone() methods, and implemented
046 *               Serializable (DG);
047 * 11-Jan-2005 : Removed deprecated code in preparation for 1.0.0 release (DG);
048 * ------------- JFREECHART 1.0.x ---------------------------------------------
049 * 18-May-2007 : Updated to use row and column keys to identify item (DG);
050 * 02-Jul-2013 : Use ParamChecks (DG);
051 *
052 */
053
054package org.jfree.chart.entity;
055
056import java.awt.Shape;
057import java.io.Serializable;
058import org.jfree.chart.util.ObjectUtils;
059import org.jfree.chart.util.Args;
060
061import org.jfree.data.category.CategoryDataset;
062
063/**
064 * A chart entity that represents one item within a category plot.
065 */
066public class CategoryItemEntity extends ChartEntity
067        implements Cloneable, Serializable {
068
069    /** For serialization. */
070    private static final long serialVersionUID = -8657249457902337349L;
071
072    /** The dataset. */
073    private CategoryDataset dataset;
074
075    /**
076     * The row key.
077     *
078     * @since 1.0.6
079     */
080    private Comparable rowKey;
081
082    /**
083     * The column key.
084     *
085     * @since 1.0.6
086     */
087    private Comparable columnKey;
088
089    /**
090     * Creates a new entity instance for an item in the specified dataset.
091     *
092     * @param area  the 'hotspot' area ({@code null} not permitted).
093     * @param toolTipText  the tool tip text.
094     * @param urlText  the URL text.
095     * @param dataset  the dataset ({@code null} not permitted).
096     * @param rowKey  the row key ({@code null} not permitted).
097     * @param columnKey  the column key ({@code null} not permitted).
098     *
099     * @since 1.0.6
100     */
101    public CategoryItemEntity(Shape area, String toolTipText, String urlText,
102            CategoryDataset dataset, Comparable rowKey, Comparable columnKey) {
103        super(area, toolTipText, urlText);
104        Args.nullNotPermitted(dataset, "dataset");
105        this.dataset = dataset;
106        this.rowKey = rowKey;
107        this.columnKey = columnKey;
108    }
109
110    /**
111     * Returns the dataset this entity refers to.  This can be used to
112     * differentiate between items in a chart that displays more than one
113     * dataset.
114     *
115     * @return The dataset (never {@code null}).
116     *
117     * @see #setDataset(CategoryDataset)
118     */
119    public CategoryDataset getDataset() {
120        return this.dataset;
121    }
122
123    /**
124     * Sets the dataset this entity refers to.
125     *
126     * @param dataset  the dataset ({@code null} not permitted).
127     *
128     * @see #getDataset()
129     */
130    public void setDataset(CategoryDataset dataset) {
131        Args.nullNotPermitted(dataset, "dataset");
132        this.dataset = dataset;
133    }
134
135    /**
136     * Returns the row key.
137     *
138     * @return The row key (never {@code null}).
139     *
140     * @since 1.0.6
141     *
142     * @see #setRowKey(Comparable)
143     */
144    public Comparable getRowKey() {
145        return this.rowKey;
146    }
147
148    /**
149     * Sets the row key.
150     *
151     * @param rowKey  the row key ({@code null} not permitted).
152     *
153     * @since 1.0.6
154     *
155     * @see #getRowKey()
156     */
157    public void setRowKey(Comparable rowKey) {
158        this.rowKey = rowKey;
159    }
160
161    /**
162     * Returns the column key.
163     *
164     * @return The column key (never {@code null}).
165     *
166     * @since 1.0.6
167     *
168     * @see #setColumnKey(Comparable)
169     */
170    public Comparable getColumnKey() {
171        return this.columnKey;
172    }
173
174    /**
175     * Sets the column key.
176     *
177     * @param columnKey  the column key ({@code null} not permitted).
178     *
179     * @since 1.0.6
180     *
181     * @see #getColumnKey()
182     */
183    public void setColumnKey(Comparable columnKey) {
184        this.columnKey = columnKey;
185    }
186
187    /**
188     * Returns a string representing this object (useful for debugging
189     * purposes).
190     *
191     * @return A string (never {@code null}).
192     */
193    @Override
194    public String toString() {
195        return "CategoryItemEntity: rowKey=" + this.rowKey
196               + ", columnKey=" + this.columnKey + ", dataset=" + this.dataset;
197    }
198
199    /**
200     * Tests the entity for equality with an arbitrary object.
201     *
202     * @param obj  the object ({@code null} permitted).
203     *
204     * @return A boolean.
205     */
206    @Override
207    public boolean equals(Object obj) {
208        if (obj == this) {
209            return true;
210        }
211        if (!(obj instanceof CategoryItemEntity)) {
212            return false;
213        }
214        CategoryItemEntity that = (CategoryItemEntity) obj;
215        if (!this.rowKey.equals(that.rowKey)) {
216            return false;
217        }
218        if (!this.columnKey.equals(that.columnKey)) {
219            return false;
220        }
221        if (!ObjectUtils.equal(this.dataset, that.dataset)) {
222            return false;
223        }
224
225        return super.equals(obj);
226    }
227
228}