    001    /* ===========================================================
    002     * JFreeChart : a free chart library for the Java(tm) platform
    003     * ===========================================================
    004     *
    005     * (C) Copyright 2000-2008, 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     * [Java is a trademark or registered trademark of Sun Microsystems, Inc.
    025     * in the United States and other countries.]
    026     *
    027     * ---------------------------
    028     * TimeSeriesURLGenerator.java
    029     * ---------------------------
    030     * (C) Copyright 2002-2008, by Richard Atkinson and Contributors.
    031     *
    032     * Original Author:  Richard Atkinson;
    033     * Contributors:     David Gilbert (for Object Refinery Limited);
    034     *
    035     * Changes:
    036     * --------
    037     * 29-Aug-2002 : Initial version (RA);
    038     * 09-Oct-2002 : Fixed errors reported by Checkstyle (DG);
    039     * 23-Mar-2003 : Implemented Serializable (DG);
    040     * 15-Jul-2004 : Switched getX() with getXValue() and getY() with
    041     *               getYValue() (DG);
    042     * 13-Jan-2005 : Modified for XHTML 1.0 compliance (DG);
    043     * ------------- JFREECHART 1.0.x ---------------------------------------------
    044     * 06-Jul-2006 : Swap call to dataset's getX() --> getXValue() (DG);
    045     * 17-Apr-2007 : Added null argument checks to constructor, new accessor
    046     *               methods, added equals() override and used new URLUtilities
    047     *               class to encode series key and date (DG);
    048     *
    049     */
    050
    051    package org.jfree.chart.urls;
    052
    053    import java.io.Serializable;
    054    import java.text.DateFormat;
    055    import java.util.Date;
    056
    057    import org.jfree.data.xy.XYDataset;
    058
    059    /**
    060     * A URL generator for time series charts.
    061     */
    062    public class TimeSeriesURLGenerator implements XYURLGenerator, Serializable {
    063
    064        /** For serialization. */
    065        private static final long serialVersionUID = -9122773175671182445L;
    066
    067        /** A formatter for the date. */
    068        private DateFormat dateFormat = DateFormat.getInstance();
    069
    070        /** Prefix to the URL */
    071        private String prefix = "index.html";
    072
    073        /** Name to use to identify the series */
    074        private String seriesParameterName = "series";
    075
    076        /** Name to use to identify the item */
    077        private String itemParameterName = "item";
    078
    079        /**
    080         * Default constructor.
    081         */
    082        public TimeSeriesURLGenerator() {
    083            super();
    084        }
    085
    086        /**
    087         * Construct TimeSeriesURLGenerator overriding defaults.
    088         *
    089         * @param dateFormat  a formatter for the date (<code>null</code> not
    090         *         permitted).
    091         * @param prefix  the prefix of the URL (<code>null</code> not permitted).
    092         * @param seriesParameterName  the name of the series parameter in the URL
    093         *         (<code>null</code> not permitted).
    094         * @param itemParameterName  the name of the item parameter in the URL
    095         *         (<code>null</code> not permitted).
    096         */
    097        public TimeSeriesURLGenerator(DateFormat dateFormat, String prefix,
    098                String seriesParameterName, String itemParameterName) {
    099
    100            if (dateFormat == null) {
    101                throw new IllegalArgumentException("Null 'dateFormat' argument.");
    102            }
    103            if (prefix == null) {
    104                throw new IllegalArgumentException("Null 'prefix' argument.");
    105            }
    106            if (seriesParameterName == null) {
    107                throw new IllegalArgumentException(
    108                        "Null 'seriesParameterName' argument.");
    109            }
    110            if (itemParameterName == null) {
    111                throw new IllegalArgumentException(
    112                        "Null 'itemParameterName' argument.");
    113            }
    114
    115            this.dateFormat = (DateFormat) dateFormat.clone();
    116            this.prefix = prefix;
    117            this.seriesParameterName = seriesParameterName;
    118            this.itemParameterName = itemParameterName;
    119
    120        }
    121
    122        /**
    123         * Returns a clone of the date format assigned to this URL generator.
    124         *
    125         * @return The date format (never <code>null</code>).
    126         *
    127         * @since 1.0.6
    128         */
    129        public DateFormat getDateFormat() {
    130            return (DateFormat) this.dateFormat.clone();
    131        }
    132
    133        /**
    134         * Returns the prefix string.
    135         *
    136         * @return The prefix string (never <code>null</code>).
    137         *
    138         * @since 1.0.6
    139         */
    140        public String getPrefix() {
    141            return this.prefix;
    142        }
    143
    144        /**
    145         * Returns the series parameter name.
    146         *
    147         * @return The series parameter name (never <code>null</code>).
    148         *
    149         * @since 1.0.6
    150         */
    151        public String getSeriesParameterName() {
    152            return this.seriesParameterName;
    153        }
    154
    155        /**
    156         * Returns the item parameter name.
    157         *
    158         * @return The item parameter name (never <code>null</code>).
    159         *
    160         * @since 1.0.6
    161         */
    162        public String getItemParameterName() {
    163            return this.itemParameterName;
    164        }
    165
    166        /**
    167         * Generates a URL for a particular item within a series.
    168         *
    169         * @param dataset  the dataset (<code>null</code> not permitted).
    170         * @param series  the series number (zero-based index).
    171         * @param item  the item number (zero-based index).
    172         *
    173         * @return The generated URL.
    174         */
    175        public String generateURL(XYDataset dataset, int series, int item) {
    176            String result = this.prefix;
    177            boolean firstParameter = result.indexOf("?") == -1;
    178            Comparable seriesKey = dataset.getSeriesKey(series);
    179            if (seriesKey != null) {
    180                result += firstParameter ? "?" : "&amp;";
    181                result += this.seriesParameterName + "=" + URLUtilities.encode(
    182                        seriesKey.toString(), "UTF-8");
    183                firstParameter = false;
    184            }
    185
    186            long x = (long) dataset.getXValue(series, item);
    187            String xValue = this.dateFormat.format(new Date(x));
    188            result += firstParameter ? "?" : "&amp;";
    189            result += this.itemParameterName + "=" + URLUtilities.encode(xValue,
    190                    "UTF-8");
    191
    192            return result;
    193        }
    194
    195        /**
    196         * Tests this generator for equality with an arbitrary object.
    197         *
    198         * @param obj  the object (<code>null</code> permitted).
    199         *
    200         * @return A boolean.
    201         */
    202        public boolean equals(Object obj) {
    203            if (obj == this) {
    204                return true;
    205            }
    206            if (!(obj instanceof TimeSeriesURLGenerator)) {
    207                return false;
    208            }
    209            TimeSeriesURLGenerator that = (TimeSeriesURLGenerator) obj;
    210            if (!this.dateFormat.equals(that.dateFormat)) {
    211                return false;
    212            }
    213            if (!this.itemParameterName.equals(that.itemParameterName)) {
    214                return false;
    215            }
    216            if (!this.prefix.equals(that.prefix)) {
    217                return false;
    218            }
    219            if (!this.seriesParameterName.equals(that.seriesParameterName)) {
    220                return false;
    221            }
    222            return true;
    223        }
    224
    225    }