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
051package org.jfree.chart.urls;
052
053import java.io.Serializable;
054import java.text.DateFormat;
055import java.util.Date;
056
057import org.jfree.data.xy.XYDataset;
058
059/**
060 * A URL generator for time series charts.
061 */
062public 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}