Source for org.jfree.chart.urls.TimeSeriesURLGenerator

   1: /* ===========================================================
   2:  * JFreeChart : a free chart library for the Java(tm) platform
   3:  * ===========================================================
   4:  *
   5:  * (C) Copyright 2000-2007, by Object Refinery Limited and Contributors.
   6:  *
   7:  * Project Info:  http://www.jfree.org/jfreechart/index.html
   8:  *
   9:  * This library is free software; you can redistribute it and/or modify it 
  10:  * under the terms of the GNU Lesser General Public License as published by 
  11:  * the Free Software Foundation; either version 2.1 of the License, or 
  12:  * (at your option) any later version.
  13:  *
  14:  * This library is distributed in the hope that it will be useful, but 
  15:  * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY 
  16:  * or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public 
  17:  * License for more details.
  18:  *
  19:  * You should have received a copy of the GNU Lesser General Public
  20:  * License along with this library; if not, write to the Free Software
  21:  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, 
  22:  * USA.  
  23:  *
  24:  * [Java is a trademark or registered trademark of Sun Microsystems, Inc. 
  25:  * in the United States and other countries.]
  26:  *
  27:  * ---------------------------
  28:  * TimeSeriesURLGenerator.java
  29:  * ---------------------------
  30:  * (C) Copyright 2002-2007, by Richard Atkinson and Contributors.
  31:  *
  32:  * Original Author:  Richard Atkinson;
  33:  * Contributors:     David Gilbert (for Object Refinery Limited);
  34:  *
  35:  * Changes:
  36:  * --------
  37:  * 29-Aug-2002 : Initial version (RA);
  38:  * 09-Oct-2002 : Fixed errors reported by Checkstyle (DG);
  39:  * 23-Mar-2003 : Implemented Serializable (DG);
  40:  * 15-Jul-2004 : Switched getX() with getXValue() and getY() with 
  41:  *               getYValue() (DG);
  42:  * 13-Jan-2005 : Modified for XHTML 1.0 compliance (DG);
  43:  * ------------- JFREECHART 1.0.x ---------------------------------------------
  44:  * 06-Jul-2006 : Swap call to dataset's getX() --> getXValue() (DG);
  45:  * 17-Apr-2007 : Added null argument checks to constructor, new accessor 
  46:  *               methods, added equals() override and used new URLUtilities
  47:  *               class to encode series key and date (DG);
  48:  * 
  49:  */
  50: 
  51: package org.jfree.chart.urls;
  52: 
  53: import java.io.Serializable;
  54: import java.text.DateFormat;
  55: import java.util.Date;
  56: 
  57: import org.jfree.data.xy.XYDataset;
  58: 
  59: /**
  60:  * A URL generator for time series charts.
  61:  */
  62: public class TimeSeriesURLGenerator implements XYURLGenerator, Serializable {
  63: 
  64:     /** For serialization. */
  65:     private static final long serialVersionUID = -9122773175671182445L;    
  66:     
  67:     /** A formatter for the date. */
  68:     private DateFormat dateFormat = DateFormat.getInstance();
  69:     
  70:     /** Prefix to the URL */
  71:     private String prefix = "index.html";
  72: 
  73:     /** Name to use to identify the series */
  74:     private String seriesParameterName = "series";
  75: 
  76:     /** Name to use to identify the item */
  77:     private String itemParameterName = "item";
  78: 
  79:     /**
  80:      * Default constructor.
  81:      */
  82:     public TimeSeriesURLGenerator() {
  83:         super();
  84:     }
  85: 
  86:     /**
  87:      * Construct TimeSeriesURLGenerator overriding defaults.
  88:      *
  89:      * @param dateFormat  a formatter for the date (<code>null</code> not 
  90:      *         permitted).
  91:      * @param prefix  the prefix of the URL (<code>null</code> not permitted).
  92:      * @param seriesParameterName  the name of the series parameter in the URL
  93:      *         (<code>null</code> not permitted).
  94:      * @param itemParameterName  the name of the item parameter in the URL 
  95:      *         (<code>null</code> not permitted).
  96:      */
  97:     public TimeSeriesURLGenerator(DateFormat dateFormat, String prefix,
  98:             String seriesParameterName, String itemParameterName) {
  99: 
 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: }