001/* =========================================================== 002 * JFreeChart : a free chart library for the Java(tm) platform 003 * =========================================================== 004 * 005 * (C) Copyright 2000-2017, 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 * RegularTimePeriod.java 029 * ---------------------- 030 * (C) Copyright 2001-2016, by Object Refinery Limited. 031 * 032 * Original Author: David Gilbert (for Object Refinery Limited); 033 * Contributor(s): -; 034 * 035 * Changes 036 * ------- 037 * 11-Oct-2001 : Version 1 (DG); 038 * 26-Feb-2002 : Changed getStart(), getMiddle() and getEnd() methods to 039 * evaluate with reference to a particular time zone (DG); 040 * 29-May-2002 : Implemented MonthConstants interface, so that these constants 041 * are conveniently available (DG); 042 * 10-Sep-2002 : Added getSerialIndex() method (DG); 043 * 10-Jan-2003 : Renamed TimePeriod --> RegularTimePeriod (DG); 044 * 13-Mar-2003 : Moved to com.jrefinery.data.time package (DG); 045 * 29-Apr-2004 : Changed getMiddleMillisecond() methods to fix bug 943985 (DG); 046 * 25-Nov-2004 : Added utility methods (DG); 047 * ------------- JFREECHART 1.0.x --------------------------------------------- 048 * 06-Oct-2006 : Deprecated the WORKING_CALENDAR field and several methods, 049 * added new peg() method (DG); 050 * 16-Sep-2008 : Deprecated DEFAULT_TIME_ZONE (DG); 051 * 23-Feb-2014 : Added getMillisecond() method (DG); 052 * 053 */ 054 055package org.jfree.data.time; 056 057import java.lang.reflect.Constructor; 058import java.util.Calendar; 059import java.util.Date; 060import java.util.Locale; 061import java.util.TimeZone; 062import org.jfree.chart.date.MonthConstants; 063 064/** 065 * An abstract class representing a unit of time. Convenient methods are 066 * provided for calculating the next and previous time periods. Conversion 067 * methods are defined that return the first and last milliseconds of the time 068 * period. The results from these methods are timezone dependent. 069 * <P> 070 * This class is immutable, and all subclasses should be immutable also. 071 */ 072public abstract class RegularTimePeriod implements TimePeriod, Comparable, 073 MonthConstants { 074 075 /** 076 * Creates a time period that includes the specified millisecond, assuming 077 * the given time zone. 078 * 079 * @param c the time period class. 080 * @param millisecond the time. 081 * @param zone the time zone. 082 * @param locale the locale. 083 * 084 * @return The time period. 085 */ 086 public static RegularTimePeriod createInstance(Class c, Date millisecond, 087 TimeZone zone, Locale locale) { 088 RegularTimePeriod result = null; 089 try { 090 Constructor constructor = c.getDeclaredConstructor( 091 new Class[] {Date.class, TimeZone.class, Locale.class}); 092 result = (RegularTimePeriod) constructor.newInstance( 093 new Object[] {millisecond, zone, locale}); 094 } 095 catch (Exception e) { 096 // do nothing, so null is returned 097 } 098 return result; 099 } 100 101 /** 102 * Returns a subclass of {@link RegularTimePeriod} that is smaller than 103 * the specified class. 104 * 105 * @param c a subclass of {@link RegularTimePeriod}. 106 * 107 * @return A class. 108 */ 109 public static Class downsize(Class c) { 110 if (c.equals(Year.class)) { 111 return Quarter.class; 112 } 113 else if (c.equals(Quarter.class)) { 114 return Month.class; 115 } 116 else if (c.equals(Month.class)) { 117 return Day.class; 118 } 119 else if (c.equals(Day.class)) { 120 return Hour.class; 121 } 122 else if (c.equals(Hour.class)) { 123 return Minute.class; 124 } 125 else if (c.equals(Minute.class)) { 126 return Second.class; 127 } 128 else if (c.equals(Second.class)) { 129 return Millisecond.class; 130 } 131 else { 132 return Millisecond.class; 133 } 134 } 135 136 /** 137 * Returns the time period preceding this one, or {@code null} if some 138 * lower limit has been reached. 139 * 140 * @return The previous time period (possibly {@code null}). 141 */ 142 public abstract RegularTimePeriod previous(); 143 144 /** 145 * Returns the time period following this one, or {@code null} if some 146 * limit has been reached. 147 * 148 * @return The next time period (possibly {@code null}). 149 */ 150 public abstract RegularTimePeriod next(); 151 152 /** 153 * Returns a serial index number for the time unit. 154 * 155 * @return The serial index number. 156 */ 157 public abstract long getSerialIndex(); 158 159 ////////////////////////////////////////////////////////////////////////// 160 161 /** 162 * Recalculates the start date/time and end date/time for this time period 163 * relative to the supplied calendar (which incorporates a time zone). 164 * 165 * @param calendar the calendar ({@code null} not permitted). 166 * 167 * @since 1.0.3 168 */ 169 public abstract void peg(Calendar calendar); 170 171 /** 172 * Returns the date/time that marks the start of the time period. This 173 * method returns a new {@code Date} instance every time it is called. 174 * 175 * @return The start date/time. 176 * 177 * @see #getFirstMillisecond() 178 */ 179 @Override 180 public Date getStart() { 181 return new Date(getFirstMillisecond()); 182 } 183 184 /** 185 * Returns the date/time that marks the end of the time period. This 186 * method returns a new {@code Date} instance every time it is called. 187 * 188 * @return The end date/time. 189 * 190 * @see #getLastMillisecond() 191 */ 192 @Override 193 public Date getEnd() { 194 return new Date(getLastMillisecond()); 195 } 196 197 /** 198 * Returns the first millisecond of the time period. This will be 199 * determined relative to the time zone specified in the constructor, or 200 * in the calendar instance passed in the most recent call to the 201 * {@link #peg(Calendar)} method. 202 * 203 * @return The first millisecond of the time period. 204 * 205 * @see #getLastMillisecond() 206 */ 207 public abstract long getFirstMillisecond(); 208 209 /** 210 * Returns the first millisecond of the time period, evaluated using the 211 * supplied calendar (which incorporates a timezone). 212 * 213 * @param calendar the calendar ({@code null} not permitted). 214 * 215 * @return The first millisecond of the time period. 216 * 217 * @throws NullPointerException if {@code calendar} is {@code null}. 218 * 219 * @see #getLastMillisecond(Calendar) 220 */ 221 public abstract long getFirstMillisecond(Calendar calendar); 222 223 /** 224 * Returns the last millisecond of the time period. This will be 225 * determined relative to the time zone specified in the constructor, or 226 * in the calendar instance passed in the most recent call to the 227 * {@link #peg(Calendar)} method. 228 * 229 * @return The last millisecond of the time period. 230 * 231 * @see #getFirstMillisecond() 232 */ 233 public abstract long getLastMillisecond(); 234 235 /** 236 * Returns the last millisecond of the time period, evaluated using the 237 * supplied calendar (which incorporates a timezone). 238 * 239 * @param calendar the calendar ({@code null} not permitted). 240 * 241 * @return The last millisecond of the time period. 242 * 243 * @see #getFirstMillisecond(Calendar) 244 */ 245 public abstract long getLastMillisecond(Calendar calendar); 246 247 /** 248 * Returns the millisecond closest to the middle of the time period. 249 * 250 * @return The middle millisecond. 251 */ 252 public long getMiddleMillisecond() { 253 long m1 = getFirstMillisecond(); 254 long m2 = getLastMillisecond(); 255 return m1 + (m2 - m1) / 2; 256 } 257 258 /** 259 * Returns the millisecond closest to the middle of the time period, 260 * evaluated using the supplied calendar (which incorporates a timezone). 261 * 262 * @param calendar the calendar. 263 * 264 * @return The middle millisecond. 265 */ 266 public long getMiddleMillisecond(Calendar calendar) { 267 long m1 = getFirstMillisecond(calendar); 268 long m2 = getLastMillisecond(calendar); 269 return m1 + (m2 - m1) / 2; 270 } 271 272 /** 273 * Returns the millisecond (relative to the epoch) corresponding to the 274 * specified {@code anchor} using the supplied {@code calendar} 275 * (which incorporates a time zone). 276 * 277 * @param anchor the anchor ({@code null} not permitted). 278 * @param calendar the calendar ({@code null} not permitted). 279 * 280 * @return Milliseconds since the epoch. 281 * 282 * @since 1.0.18 283 */ 284 public long getMillisecond(TimePeriodAnchor anchor, Calendar calendar) { 285 if (anchor.equals(TimePeriodAnchor.START)) { 286 return getFirstMillisecond(calendar); 287 } else if (anchor.equals(TimePeriodAnchor.MIDDLE)) { 288 return getMiddleMillisecond(calendar); 289 } else if (anchor.equals(TimePeriodAnchor.END)) { 290 return getLastMillisecond(calendar); 291 } else { 292 throw new IllegalStateException("Unrecognised anchor: " + anchor); 293 } 294 } 295 296 /** 297 * Returns a string representation of the time period. 298 * 299 * @return The string. 300 */ 301 @Override 302 public String toString() { 303 return String.valueOf(getStart()); 304 } 305 306}