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 * TimeSeriesURLGenerator.java
029 * ---------------------------
030 * (C) Copyright 2002-2013, 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 * 03-Jul-2013 : Use ParamChecks (DG);
049 *
050 */
051
052package org.jfree.chart.urls;
053
054import java.io.Serializable;
055import java.text.DateFormat;
056import java.util.Date;
057import org.jfree.chart.util.ParamChecks;
058
059import org.jfree.data.xy.XYDataset;
060
061/**
062 * A URL generator for time series charts.
063 */
064public class TimeSeriesURLGenerator implements XYURLGenerator, Serializable {
065
066    /** For serialization. */
067    private static final long serialVersionUID = -9122773175671182445L;
068
069    /** A formatter for the date. */
070    private DateFormat dateFormat = DateFormat.getInstance();
071
072    /** Prefix to the URL */
073    private String prefix = "index.html";
074
075    /** Name to use to identify the series */
076    private String seriesParameterName = "series";
077
078    /** Name to use to identify the item */
079    private String itemParameterName = "item";
080
081    /**
082     * Default constructor.
083     */
084    public TimeSeriesURLGenerator() {
085        super();
086    }
087
088    /**
089     * Construct TimeSeriesURLGenerator overriding defaults.
090     *
091     * @param dateFormat  a formatter for the date (<code>null</code> not
092     *         permitted).
093     * @param prefix  the prefix of the URL (<code>null</code> not permitted).
094     * @param seriesParameterName  the name of the series parameter in the URL
095     *         (<code>null</code> not permitted).
096     * @param itemParameterName  the name of the item parameter in the URL
097     *         (<code>null</code> not permitted).
098     */
099    public TimeSeriesURLGenerator(DateFormat dateFormat, String prefix,
100            String seriesParameterName, String itemParameterName) {
101
102        ParamChecks.nullNotPermitted(dateFormat, "dateFormat");
103        ParamChecks.nullNotPermitted(prefix, "prefix");
104        ParamChecks.nullNotPermitted(seriesParameterName, "seriesParameterName");
105        ParamChecks.nullNotPermitted(itemParameterName, "itemParameterName");
106        this.dateFormat = (DateFormat) dateFormat.clone();
107        this.prefix = prefix;
108        this.seriesParameterName = seriesParameterName;
109        this.itemParameterName = itemParameterName;
110    }
111
112    /**
113     * Returns a clone of the date format assigned to this URL generator.
114     *
115     * @return The date format (never <code>null</code>).
116     *
117     * @since 1.0.6
118     */
119    public DateFormat getDateFormat() {
120        return (DateFormat) this.dateFormat.clone();
121    }
122
123    /**
124     * Returns the prefix string.
125     *
126     * @return The prefix string (never <code>null</code>).
127     *
128     * @since 1.0.6
129     */
130    public String getPrefix() {
131        return this.prefix;
132    }
133
134    /**
135     * Returns the series parameter name.
136     *
137     * @return The series parameter name (never <code>null</code>).
138     *
139     * @since 1.0.6
140     */
141    public String getSeriesParameterName() {
142        return this.seriesParameterName;
143    }
144
145    /**
146     * Returns the item parameter name.
147     *
148     * @return The item parameter name (never <code>null</code>).
149     *
150     * @since 1.0.6
151     */
152    public String getItemParameterName() {
153        return this.itemParameterName;
154    }
155
156    /**
157     * Generates a URL for a particular item within a series.
158     *
159     * @param dataset  the dataset (<code>null</code> not permitted).
160     * @param series  the series number (zero-based index).
161     * @param item  the item number (zero-based index).
162     *
163     * @return The generated URL.
164     */
165    @Override
166    public String generateURL(XYDataset dataset, int series, int item) {
167        String result = this.prefix;
168        boolean firstParameter = result.indexOf("?") == -1;
169        Comparable seriesKey = dataset.getSeriesKey(series);
170        if (seriesKey != null) {
171            result += firstParameter ? "?" : "&amp;";
172            result += this.seriesParameterName + "=" + URLUtilities.encode(
173                    seriesKey.toString(), "UTF-8");
174            firstParameter = false;
175        }
176
177        long x = (long) dataset.getXValue(series, item);
178        String xValue = this.dateFormat.format(new Date(x));
179        result += firstParameter ? "?" : "&amp;";
180        result += this.itemParameterName + "=" + URLUtilities.encode(xValue,
181                "UTF-8");
182
183        return result;
184    }
185
186    /**
187     * Tests this generator for equality with an arbitrary object.
188     *
189     * @param obj  the object (<code>null</code> permitted).
190     *
191     * @return A boolean.
192     */
193    @Override
194    public boolean equals(Object obj) {
195        if (obj == this) {
196            return true;
197        }
198        if (!(obj instanceof TimeSeriesURLGenerator)) {
199            return false;
200        }
201        TimeSeriesURLGenerator that = (TimeSeriesURLGenerator) obj;
202        if (!this.dateFormat.equals(that.dateFormat)) {
203            return false;
204        }
205        if (!this.itemParameterName.equals(that.itemParameterName)) {
206            return false;
207        }
208        if (!this.prefix.equals(that.prefix)) {
209            return false;
210        }
211        if (!this.seriesParameterName.equals(that.seriesParameterName)) {
212            return false;
213        }
214        return true;
215    }
216
217}