001/* ===========================================================
002 * JFreeChart : a free chart library for the Java(tm) platform
003 * ===========================================================
004 *
005 * (C) Copyright 2000-2013, 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 * AbstractXYItemLabelGenerator.java
029 * ---------------------------------
030 * (C) Copyright 2004-2013, by Object Refinery Limited.
031 *
032 * Original Author:  David Gilbert (for Object Refinery Limited);
033 * Contributor(s):   -;
034 *
035 * Changes
036 * -------
037 * 27-Feb-2004 : Version 1 (DG);
038 * 12-May-2004 : Moved default tool tip format to
039 *               StandardXYToolTipGenerator (DG);
040 * 15-Jul-2004 : Switched getX() with getXValue() and getY() with
041 *               getYValue() (DG);
042 * 08-Oct-2004 : Modified createItemArray() method to handle null values (DG);
043 * 10-Jan-2005 : Updated createItemArray() to use x, y primitives if
044 *               possible (DG);
045 * ------------- JFREECHART 1.0.x --------------------------------------------
046 * 26-Jan-2006 : Minor API doc update (DG);
047 * 25-Jan-2007 : Added new constructor and fixed bug in clone() method (DG);
048 * 16-Oct-2007 : Removed redundant code (DG);
049 * 23-Nov-2007 : Implemented hashCode() (DG);
050 * 26-May-2008 : Added accessor methods for nullYString and updated equals()
051 *               method (DG);
052 * 03-Jul-2013 : Use ParamChecks (DG);
053 *
054 */
055
056package org.jfree.chart.labels;
057
058import java.io.Serializable;
059import java.text.DateFormat;
060import java.text.MessageFormat;
061import java.text.NumberFormat;
062import java.util.Date;
063
064import org.jfree.chart.HashUtilities;
065import org.jfree.chart.util.ParamChecks;
066import org.jfree.data.xy.XYDataset;
067import org.jfree.util.ObjectUtilities;
068
069/**
070 * A base class for creating item label generators.
071 */
072public class AbstractXYItemLabelGenerator implements Cloneable, Serializable {
073
074    /** For serialization. */
075    private static final long serialVersionUID = 5869744396278660636L;
076
077    /** The item label format string. */
078    private String formatString;
079
080    /** A number formatter for the x value. */
081    private NumberFormat xFormat;
082
083    /** A date formatter for the x value. */
084    private DateFormat xDateFormat;
085
086    /** A formatter for the y value. */
087    private NumberFormat yFormat;
088
089    /** A date formatter for the y value. */
090    private DateFormat yDateFormat;
091
092    /** The string used to represent 'null' for the y-value. */
093    private String nullYString = "null";
094
095    /**
096     * Creates an item label generator using default number formatters.
097     */
098    protected AbstractXYItemLabelGenerator() {
099        this("{2}", NumberFormat.getNumberInstance(),
100                NumberFormat.getNumberInstance());
101    }
102
103    /**
104     * Creates an item label generator using the specified number formatters.
105     *
106     * @param formatString  the item label format string (<code>null</code>
107     *                      not permitted).
108     * @param xFormat  the format object for the x values (<code>null</code>
109     *                 not permitted).
110     * @param yFormat  the format object for the y values (<code>null</code>
111     *                 not permitted).
112     */
113    protected AbstractXYItemLabelGenerator(String formatString, 
114            NumberFormat xFormat, NumberFormat yFormat) {
115
116        ParamChecks.nullNotPermitted(formatString, "formatString");
117        ParamChecks.nullNotPermitted(xFormat, "xFormat");
118        ParamChecks.nullNotPermitted(yFormat, "yFormat");
119        this.formatString = formatString;
120        this.xFormat = xFormat;
121        this.yFormat = yFormat;
122    }
123
124    /**
125     * Creates an item label generator using the specified number formatters.
126     *
127     * @param formatString  the item label format string (<code>null</code>
128     *                      not permitted).
129     * @param xFormat  the format object for the x values (<code>null</code>
130     *                 permitted).
131     * @param yFormat  the format object for the y values (<code>null</code>
132     *                 not permitted).
133     */
134    protected AbstractXYItemLabelGenerator(String formatString, 
135            DateFormat xFormat, NumberFormat yFormat) {
136
137        this(formatString, NumberFormat.getInstance(), yFormat);
138        this.xDateFormat = xFormat;
139    }
140
141    /**
142     * Creates an item label generator using the specified formatters (a
143     * number formatter for the x-values and a date formatter for the
144     * y-values).
145     *
146     * @param formatString  the item label format string (<code>null</code>
147     *                      not permitted).
148     * @param xFormat  the format object for the x values (<code>null</code>
149     *                 permitted).
150     * @param yFormat  the format object for the y values (<code>null</code>
151     *                 not permitted).
152     *
153     * @since 1.0.4
154     */
155    protected AbstractXYItemLabelGenerator(String formatString,
156            NumberFormat xFormat, DateFormat yFormat) {
157
158        this(formatString, xFormat, NumberFormat.getInstance());
159        this.yDateFormat = yFormat;
160    }
161
162    /**
163     * Creates an item label generator using the specified number formatters.
164     *
165     * @param formatString  the item label format string (<code>null</code>
166     *                      not permitted).
167     * @param xFormat  the format object for the x values (<code>null</code>
168     *                 permitted).
169     * @param yFormat  the format object for the y values (<code>null</code>
170     *                 not permitted).
171     */
172    protected AbstractXYItemLabelGenerator(String formatString, 
173            DateFormat xFormat, DateFormat yFormat) {
174
175        this(formatString, NumberFormat.getInstance(),
176                NumberFormat.getInstance());
177        this.xDateFormat = xFormat;
178        this.yDateFormat = yFormat;
179    }
180
181    /**
182     * Returns the format string (this controls the overall structure of the
183     * label).
184     *
185     * @return The format string (never <code>null</code>).
186     */
187    public String getFormatString() {
188        return this.formatString;
189    }
190
191    /**
192     * Returns the number formatter for the x-values.
193     *
194     * @return The number formatter (possibly <code>null</code>).
195     */
196    public NumberFormat getXFormat() {
197        return this.xFormat;
198    }
199
200    /**
201     * Returns the date formatter for the x-values.
202     *
203     * @return The date formatter (possibly <code>null</code>).
204     */
205    public DateFormat getXDateFormat() {
206        return this.xDateFormat;
207    }
208
209    /**
210     * Returns the number formatter for the y-values.
211     *
212     * @return The number formatter (possibly <code>null</code>).
213     */
214    public NumberFormat getYFormat() {
215        return this.yFormat;
216    }
217
218    /**
219     * Returns the date formatter for the y-values.
220     *
221     * @return The date formatter (possibly <code>null</code>).
222     */
223    public DateFormat getYDateFormat() {
224        return this.yDateFormat;
225    }
226
227    /**
228     * Generates a label string for an item in the dataset.
229     *
230     * @param dataset  the dataset (<code>null</code> not permitted).
231     * @param series  the series (zero-based index).
232     * @param item  the item (zero-based index).
233     *
234     * @return The label (possibly <code>null</code>).
235     */
236    public String generateLabelString(XYDataset dataset, int series, int item) {
237        String result;
238        Object[] items = createItemArray(dataset, series, item);
239        result = MessageFormat.format(this.formatString, items);
240        return result;
241    }
242
243    /**
244     * Returns the string representing a null value.
245     *
246     * @return The string representing a null value.
247     *
248     * @since 1.0.10
249     */
250    public String getNullYString() {
251        return this.nullYString;
252    }
253
254    /**
255     * Creates the array of items that can be passed to the
256     * {@link MessageFormat} class for creating labels.
257     *
258     * @param dataset  the dataset (<code>null</code> not permitted).
259     * @param series  the series (zero-based index).
260     * @param item  the item (zero-based index).
261     *
262     * @return An array of three items from the dataset formatted as
263     *         <code>String</code> objects (never <code>null</code>).
264     */
265    protected Object[] createItemArray(XYDataset dataset, int series,
266                                       int item) {
267        Object[] result = new Object[3];
268        result[0] = dataset.getSeriesKey(series).toString();
269
270        double x = dataset.getXValue(series, item);
271        if (this.xDateFormat != null) {
272            result[1] = this.xDateFormat.format(new Date((long) x));
273        }
274        else {
275            result[1] = this.xFormat.format(x);
276        }
277
278        double y = dataset.getYValue(series, item);
279        if (Double.isNaN(y) && dataset.getY(series, item) == null) {
280            result[2] = this.nullYString;
281        }
282        else {
283            if (this.yDateFormat != null) {
284                result[2] = this.yDateFormat.format(new Date((long) y));
285            }
286            else {
287                result[2] = this.yFormat.format(y);
288            }
289        }
290        return result;
291    }
292
293    /**
294     * Tests this object for equality with an arbitrary object.
295     *
296     * @param obj  the other object (<code>null</code> permitted).
297     *
298     * @return A boolean.
299     */
300    @Override
301    public boolean equals(Object obj) {
302        if (obj == this) {
303            return true;
304        }
305        if (!(obj instanceof AbstractXYItemLabelGenerator)) {
306            return false;
307        }
308        AbstractXYItemLabelGenerator that = (AbstractXYItemLabelGenerator) obj;
309        if (!this.formatString.equals(that.formatString)) {
310            return false;
311        }
312        if (!ObjectUtilities.equal(this.xFormat, that.xFormat)) {
313            return false;
314        }
315        if (!ObjectUtilities.equal(this.xDateFormat, that.xDateFormat)) {
316            return false;
317        }
318        if (!ObjectUtilities.equal(this.yFormat, that.yFormat)) {
319            return false;
320        }
321        if (!ObjectUtilities.equal(this.yDateFormat, that.yDateFormat)) {
322            return false;
323        }
324        if (!this.nullYString.equals(that.nullYString)) {
325            return false;
326        }
327        return true;
328    }
329
330    /**
331     * Returns a hash code for this instance.
332     *
333     * @return A hash code.
334     */
335    @Override
336    public int hashCode() {
337        int result = 127;
338        result = HashUtilities.hashCode(result, this.formatString);
339        result = HashUtilities.hashCode(result, this.xFormat);
340        result = HashUtilities.hashCode(result, this.xDateFormat);
341        result = HashUtilities.hashCode(result, this.yFormat);
342        result = HashUtilities.hashCode(result, this.yDateFormat);
343        return result;
344    }
345
346    /**
347     * Returns an independent copy of the generator.
348     *
349     * @return A clone.
350     *
351     * @throws CloneNotSupportedException if cloning is not supported.
352     */
353    @Override
354    public Object clone() throws CloneNotSupportedException {
355        AbstractXYItemLabelGenerator clone
356                = (AbstractXYItemLabelGenerator) super.clone();
357        if (this.xFormat != null) {
358            clone.xFormat = (NumberFormat) this.xFormat.clone();
359        }
360        if (this.yFormat != null) {
361            clone.yFormat = (NumberFormat) this.yFormat.clone();
362        }
363        if (this.xDateFormat != null) {
364            clone.xDateFormat = (DateFormat) this.xDateFormat.clone();
365        }
366        if (this.yDateFormat != null) {
367            clone.yDateFormat = (DateFormat) this.yDateFormat.clone();
368        }
369        return clone;
370    }
371
372}