    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.label;
    034
    035import java.io.Serializable;
    036import java.util.Formatter;
    037
    038import com.orsoncharts.data.DataUtils;
    039import com.orsoncharts.data.xyz.XYZDataset;
    040import com.orsoncharts.util.ArgChecks;
    041
    042/**
    043 * A default implementation of the {@link XYZLabelGenerator} interface.
    044 * The implementation uses a {@link java.util.Formatter} instance to generate
    045 * the labels, which are typically used as the series labels in the chart
    046 * legend.  Three values are passed to the formatter for possible inclusion
    047 * in the resulting label: (1) the key for the series, (2) the count for the
    048 * number of items in the series (as an {@code Integer}) and (3) the total
    049 * of the non-{@code NaN} values in the series (as a {@code Double}).
    050 * <br><br>
    051 * NOTE: This class is serializable, but the serialization format is subject
    052 * to change in future releases and should not be relied upon for persisting
    053 * instances of this class.
    054 *
    055 * @since 1.2
    056 */
    057@SuppressWarnings("serial")
    058public class StandardXYZLabelGenerator implements XYZLabelGenerator,
    059        Serializable {
    060
    061    /** A label template that will display the series key only. */
    062    public static final String KEY_ONLY_TEMPLATE = "%s";
    063
    064    /**
    065     * A label template that will display the series key followed by the
    066     * total of the data items for the series (in brackets) with zero decimal
    067     * places.
    068     */
    069    public static final String TOTAL_TEMPLATE = "%s (%3$,.0f)";
    070
    071    /**
    072     * A label template that will display the series key followed by the
    073     * total of the data items for the series (in brackets) with zero decimal
    074     * places.
    075     */
    076    public static final String TOTAL_TEMPLATE_2DP = "%s (%3$,.2f)";
    077
    078    /**
    079     * A label template that will display the series key followed by the
    080     * number of data items for the series (in brackets).
    081     */
    082    public static final String COUNT_TEMPLATE = "%s (%2$,d)";
    083
    084    /** The default label template. */
    085    public static final String DEFAULT_TEMPLATE = KEY_ONLY_TEMPLATE;
    086
    087    /** The label template. */
    088    private String template;
    089
    090    /**
    091     * The default constructor.
    092     */
    093    public StandardXYZLabelGenerator() {
    094        this(DEFAULT_TEMPLATE);
    095    }
    096
    097    /**
    098     * Creates a new instance with the specified label template.
    099     *
    100     * @param template  the label template ({@code null} not permitted).
    101     */
    102    public StandardXYZLabelGenerator(String template) {
    103        ArgChecks.nullNotPermitted(template, "template");
    104        this.template = template;
    105    }
    106
    107    /**
    108     * Generates a series label.
    109     *
    110     * @param dataset  the dataset ({@code null} not permitted).
    111     * @param seriesKey  the series key ({@code null} not permitted).
    112     *
    113     * @return The series label (possibly {@code null}).
    114     */
    115    @Override
    116    public <S extends Comparable<S>> String generateSeriesLabel(
    117            XYZDataset<S> dataset, S seriesKey) {
    118        ArgChecks.nullNotPermitted(dataset, "dataset");
    119        ArgChecks.nullNotPermitted(seriesKey, "seriesKey");
    120        Formatter formatter = new Formatter(new StringBuilder());
    121        int count = dataset.getItemCount(dataset.getSeriesIndex(seriesKey));
    122        double total = DataUtils.total(dataset, seriesKey);
    123        formatter.format(this.template, seriesKey, count, total);
    124        String result = formatter.toString();
    125        formatter.close();
    126        return result;
    127    }
    128
    129    /**
    130     * Tests this label generator for equality with an arbitrary object.
    131     *
    132     * @param obj  the object ({@code null} permitted).
    133     *
    134     * @return A boolean.
    135     */
    136    @Override
    137    public boolean equals(Object obj) {
    138        if (obj == this) {
    139            return true;
    140        }
    141        if (!(obj instanceof StandardXYZLabelGenerator)) {
    142            return false;
    143        }
    144        StandardXYZLabelGenerator that = (StandardXYZLabelGenerator) obj;
    145        if (!this.template.equals(that.template)) {
    146            return false;
    147        }
    148        return true;
    149    }
    150
    151    @Override
    152    public int hashCode() {
    153        return this.template.hashCode();
    154    }
    155
    156}