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 * Year.java 029 * --------- 030 * (C) Copyright 2001-2012, 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 * 14-Nov-2001 : Override for toString() method (DG); 039 * 19-Dec-2001 : Added a new constructor as suggested by Paul English (DG); 040 * 29-Jan-2002 : Worked on parseYear() method (DG); 041 * 14-Feb-2002 : Fixed bug in Year(Date) constructor (DG); 042 * 26-Feb-2002 : Changed getStart(), getMiddle() and getEnd() methods to 043 * evaluate with reference to a particular time zone (DG); 044 * 19-Mar-2002 : Changed API for TimePeriod classes (DG); 045 * 10-Sep-2002 : Added getSerialIndex() method (DG); 046 * 04-Oct-2002 : Fixed errors reported by Checkstyle (DG); 047 * 10-Jan-2003 : Changed base class and method names (DG); 048 * 05-Mar-2003 : Fixed bug in getFirstMillisecond() picked up in JUnit 049 * tests (DG); 050 * 13-Mar-2003 : Moved to com.jrefinery.data.time package, and implemented 051 * Serializable (DG); 052 * 21-Oct-2003 : Added hashCode() method (DG); 053 * ------------- JFREECHART 1.0.x --------------------------------------------- 054 * 05-Oct-2006 : Updated API docs (DG); 055 * 06-Oct-2006 : Refactored to cache first and last millisecond values (DG); 056 * 16-Sep-2008 : Extended range of valid years, and deprecated 057 * DEFAULT_TIME_ZONE (DG); 058 * 25-Nov-2008 : Added new constructor with Locale (DG); 059 * 05-Jul-2012 : Removed JRE 1.3.1 code (DG); 060 * 061 */ 062 063package org.jfree.data.time; 064 065import java.io.Serializable; 066import java.util.Calendar; 067import java.util.Date; 068import java.util.Locale; 069import java.util.TimeZone; 070 071/** 072 * Represents a year in the range -9999 to 9999. This class is immutable, 073 * which is a requirement for all {@link RegularTimePeriod} subclasses. 074 */ 075public class Year extends RegularTimePeriod implements Serializable { 076 077 /** 078 * The minimum year value. 079 * 080 * @since 1.0.11 081 */ 082 public static final int MINIMUM_YEAR = -9999; 083 084 /** 085 * The maximum year value. 086 * 087 * @since 1.0.11 088 */ 089 public static final int MAXIMUM_YEAR = 9999; 090 091 /** For serialization. */ 092 private static final long serialVersionUID = -7659990929736074836L; 093 094 /** The year. */ 095 private short year; 096 097 /** The first millisecond. */ 098 private long firstMillisecond; 099 100 /** The last millisecond. */ 101 private long lastMillisecond; 102 103 /** 104 * Creates a new {@code Year}, based on the current system date/time. 105 */ 106 public Year() { 107 this(new Date()); 108 } 109 110 /** 111 * Creates a time period representing a single year. 112 * 113 * @param year the year. 114 */ 115 public Year(int year) { 116 if ((year < Year.MINIMUM_YEAR) || (year > Year.MAXIMUM_YEAR)) { 117 throw new IllegalArgumentException( 118 "Year constructor: year (" + year + ") outside valid range."); 119 } 120 this.year = (short) year; 121 peg(Calendar.getInstance()); 122 } 123 124 /** 125 * Creates a new {@code Year}, based on a particular instant in time, 126 * using the default time zone. 127 * 128 * @param time the time ({@code null} not permitted). 129 * 130 * @see #Year(Date, TimeZone, Locale) 131 */ 132 public Year(Date time) { 133 this(time, TimeZone.getDefault(), Locale.getDefault()); 134 } 135 136 /** 137 * Creates a new {@code Year} instance, for the specified time zone 138 * and locale. 139 * 140 * @param time the current time ({@code null} not permitted). 141 * @param zone the time zone. 142 * @param locale the locale. 143 * 144 * @since 1.0.12 145 */ 146 public Year(Date time, TimeZone zone, Locale locale) { 147 Calendar calendar = Calendar.getInstance(zone, locale); 148 calendar.setTime(time); 149 this.year = (short) calendar.get(Calendar.YEAR); 150 peg(calendar); 151 } 152 153 /** 154 * Returns the year. 155 * 156 * @return The year. 157 */ 158 public int getYear() { 159 return this.year; 160 } 161 162 /** 163 * Returns the first millisecond of the year. This will be determined 164 * relative to the time zone specified in the constructor, or in the 165 * calendar instance passed in the most recent call to the 166 * {@link #peg(Calendar)} method. 167 * 168 * @return The first millisecond of the year. 169 * 170 * @see #getLastMillisecond() 171 */ 172 @Override 173 public long getFirstMillisecond() { 174 return this.firstMillisecond; 175 } 176 177 /** 178 * Returns the last millisecond of the year. This will be 179 * determined relative to the time zone specified in the constructor, or 180 * in the calendar instance passed in the most recent call to the 181 * {@link #peg(Calendar)} method. 182 * 183 * @return The last millisecond of the year. 184 * 185 * @see #getFirstMillisecond() 186 */ 187 @Override 188 public long getLastMillisecond() { 189 return this.lastMillisecond; 190 } 191 192 /** 193 * Recalculates the start date/time and end date/time for this time period 194 * relative to the supplied calendar (which incorporates a time zone). 195 * 196 * @param calendar the calendar ({@code null} not permitted). 197 * 198 * @since 1.0.3 199 */ 200 @Override 201 public void peg(Calendar calendar) { 202 this.firstMillisecond = getFirstMillisecond(calendar); 203 this.lastMillisecond = getLastMillisecond(calendar); 204 } 205 206 /** 207 * Returns the year preceding this one. 208 * 209 * @return The year preceding this one (or {@code null} if the 210 * current year is -9999). 211 */ 212 @Override 213 public RegularTimePeriod previous() { 214 if (this.year > Year.MINIMUM_YEAR) { 215 return new Year(this.year - 1); 216 } 217 else { 218 return null; 219 } 220 } 221 222 /** 223 * Returns the year following this one. 224 * 225 * @return The year following this one (or {@code null} if the current 226 * year is 9999). 227 */ 228 @Override 229 public RegularTimePeriod next() { 230 if (this.year < Year.MAXIMUM_YEAR) { 231 return new Year(this.year + 1); 232 } 233 else { 234 return null; 235 } 236 } 237 238 /** 239 * Returns a serial index number for the year. 240 * <P> 241 * The implementation simply returns the year number (e.g. 2002). 242 * 243 * @return The serial index number. 244 */ 245 @Override 246 public long getSerialIndex() { 247 return this.year; 248 } 249 250 /** 251 * Returns the first millisecond of the year, evaluated using the supplied 252 * calendar (which determines the time zone). 253 * 254 * @param calendar the calendar ({@code null} not permitted). 255 * 256 * @return The first millisecond of the year. 257 * 258 * @throws NullPointerException if {@code calendar} is 259 * {@code null}. 260 */ 261 @Override 262 public long getFirstMillisecond(Calendar calendar) { 263 calendar.set(this.year, Calendar.JANUARY, 1, 0, 0, 0); 264 calendar.set(Calendar.MILLISECOND, 0); 265 return calendar.getTimeInMillis(); 266 } 267 268 /** 269 * Returns the last millisecond of the year, evaluated using the supplied 270 * calendar (which determines the time zone). 271 * 272 * @param calendar the calendar ({@code null} not permitted). 273 * 274 * @return The last millisecond of the year. 275 * 276 * @throws NullPointerException if {@code calendar} is 277 * {@code null}. 278 */ 279 @Override 280 public long getLastMillisecond(Calendar calendar) { 281 calendar.set(this.year, Calendar.DECEMBER, 31, 23, 59, 59); 282 calendar.set(Calendar.MILLISECOND, 999); 283 return calendar.getTimeInMillis(); 284 } 285 286 /** 287 * Tests the equality of this {@code Year} object to an arbitrary 288 * object. Returns {@code true} if the target is a {@code Year} 289 * instance representing the same year as this object. In all other cases, 290 * returns {@code false}. 291 * 292 * @param obj the object ({@code null} permitted). 293 * 294 * @return {@code true} if the year of this and the object are the 295 * same. 296 */ 297 @Override 298 public boolean equals(Object obj) { 299 if (obj == this) { 300 return true; 301 } 302 if (!(obj instanceof Year)) { 303 return false; 304 } 305 Year that = (Year) obj; 306 return (this.year == that.year); 307 } 308 309 /** 310 * Returns a hash code for this object instance. The approach described by 311 * Joshua Bloch in "Effective Java" has been used here: 312 * <p> 313 * {@code http://developer.java.sun.com/developer/Books/effectivejava 314 * /Chapter3.pdf} 315 * 316 * @return A hash code. 317 */ 318 @Override 319 public int hashCode() { 320 int result = 17; 321 int c = this.year; 322 result = 37 * result + c; 323 return result; 324 } 325 326 /** 327 * Returns an integer indicating the order of this {@code Year} object 328 * relative to the specified object: 329 * 330 * negative == before, zero == same, positive == after. 331 * 332 * @param o1 the object to compare. 333 * 334 * @return negative == before, zero == same, positive == after. 335 */ 336 @Override 337 public int compareTo(Object o1) { 338 339 int result; 340 341 // CASE 1 : Comparing to another Year object 342 // ----------------------------------------- 343 if (o1 instanceof Year) { 344 Year y = (Year) o1; 345 result = this.year - y.getYear(); 346 } 347 348 // CASE 2 : Comparing to another TimePeriod object 349 // ----------------------------------------------- 350 else if (o1 instanceof RegularTimePeriod) { 351 // more difficult case - evaluate later... 352 result = 0; 353 } 354 355 // CASE 3 : Comparing to a non-TimePeriod object 356 // --------------------------------------------- 357 else { 358 // consider time periods to be ordered after general objects 359 result = 1; 360 } 361 362 return result; 363 364 } 365 366 /** 367 * Returns a string representing the year.. 368 * 369 * @return A string representing the year. 370 */ 371 @Override 372 public String toString() { 373 return Integer.toString(this.year); 374 } 375 376 /** 377 * Parses the string argument as a year. 378 * <P> 379 * The string format is YYYY. 380 * 381 * @param s a string representing the year. 382 * 383 * @return {@code null} if the string is not parseable, the year 384 * otherwise. 385 */ 386 public static Year parseYear(String s) { 387 388 // parse the string... 389 int y; 390 try { 391 y = Integer.parseInt(s.trim()); 392 } 393 catch (NumberFormatException e) { 394 throw new TimePeriodFormatException("Cannot parse string."); 395 } 396 397 // create the year... 398 try { 399 return new Year(y); 400 } 401 catch (IllegalArgumentException e) { 402 throw new TimePeriodFormatException("Year outside valid range."); 403 } 404 } 405 406}