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 * Hour.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 * 18-Dec-2001 : Changed order of parameters in constructor (DG); 039 * 19-Dec-2001 : Added a new constructor as suggested by Paul English (DG); 040 * 14-Feb-2002 : Fixed bug in Hour(Date) constructor (DG); 041 * 26-Feb-2002 : Changed getStart(), getMiddle() and getEnd() methods to 042 * evaluate with reference to a particular time zone (DG); 043 * 15-Mar-2002 : Changed API (DG); 044 * 16-Apr-2002 : Fixed small time zone bug in constructor (DG); 045 * 10-Sep-2002 : Added getSerialIndex() method (DG); 046 * 07-Oct-2002 : Fixed errors reported by Checkstyle (DG); 047 * 10-Jan-2003 : Changed base class and method names (DG); 048 * 13-Mar-2003 : Moved to com.jrefinery.data.time package, and implemented 049 * Serializable (DG); 050 * 21-Oct-2003 : Added hashCode() method, and new constructor for 051 * convenience (DG); 052 * 30-Sep-2004 : Replaced getTime().getTime() with getTimeInMillis() (DG); 053 * 04-Nov-2004 : Reverted change of 30-Sep-2004, because it won't work for 054 * JDK 1.3 (DG); 055 * ------------- JFREECHART 1.0.x --------------------------------------------- 056 * 05-Oct-2006 : Updated API docs (DG); 057 * 06-Oct-2006 : Refactored to cache first and last millisecond values (DG); 058 * 04-Apr-2007 : In Hour(Date, TimeZone), peg milliseconds using specified 059 * time zone (DG); 060 * 16-Sep-2008 : Deprecated DEFAULT_TIME_ZONE (DG); 061 * 02-Mar-2009 : Added new constructor with Locale (DG); 062 * 05-Jul-2012 : Replaced getTime().getTime() with getTimeInMillis() (DG); 063 * 03-Jul-2013 : Use ParamChecks (DG); 064 * 065 */ 066 067package org.jfree.data.time; 068 069import java.io.Serializable; 070import java.util.Calendar; 071import java.util.Date; 072import java.util.Locale; 073import java.util.TimeZone; 074import org.jfree.chart.util.Args; 075 076/** 077 * Represents an hour in a specific day. This class is immutable, which is a 078 * requirement for all {@link RegularTimePeriod} subclasses. 079 */ 080public class Hour extends RegularTimePeriod implements Serializable { 081 082 /** For serialization. */ 083 private static final long serialVersionUID = -835471579831937652L; 084 085 /** Useful constant for the first hour in the day. */ 086 public static final int FIRST_HOUR_IN_DAY = 0; 087 088 /** Useful constant for the last hour in the day. */ 089 public static final int LAST_HOUR_IN_DAY = 23; 090 091 /** The day. */ 092 private Day day; 093 094 /** The hour. */ 095 private byte hour; 096 097 /** The first millisecond. */ 098 private long firstMillisecond; 099 100 /** The last millisecond. */ 101 private long lastMillisecond; 102 103 /** 104 * Constructs a new Hour, based on the system date/time. 105 */ 106 public Hour() { 107 this(new Date()); 108 } 109 110 /** 111 * Constructs a new Hour. 112 * 113 * @param hour the hour (in the range 0 to 23). 114 * @param day the day ({@code null} not permitted). 115 */ 116 public Hour(int hour, Day day) { 117 Args.nullNotPermitted(day, "day"); 118 this.hour = (byte) hour; 119 this.day = day; 120 peg(Calendar.getInstance()); 121 } 122 123 /** 124 * Creates a new hour. 125 * 126 * @param hour the hour (0-23). 127 * @param day the day (1-31). 128 * @param month the month (1-12). 129 * @param year the year (1900-9999). 130 */ 131 public Hour(int hour, int day, int month, int year) { 132 this(hour, new Day(day, month, year)); 133 } 134 135 /** 136 * Constructs a new instance, based on the supplied date/time and 137 * the default time zone. 138 * 139 * @param time the date-time ({@code null} not permitted). 140 * 141 * @see #Hour(Date, TimeZone, Locale) 142 */ 143 public Hour(Date time) { 144 // defer argument checking... 145 this(time, TimeZone.getDefault(), Locale.getDefault()); 146 } 147 148 /** 149 * Constructs a new instance, based on the supplied date/time evaluated 150 * in the specified time zone. 151 * 152 * @param time the date-time ({@code null} not permitted). 153 * @param zone the time zone ({@code null} not permitted). 154 * @param locale the locale ({@code null} not permitted). 155 * 156 * @since 1.0.13 157 */ 158 public Hour(Date time, TimeZone zone, Locale locale) { 159 Args.nullNotPermitted(time, "time"); 160 Args.nullNotPermitted(zone, "zone"); 161 Args.nullNotPermitted(locale, "locale"); 162 Calendar calendar = Calendar.getInstance(zone, locale); 163 calendar.setTime(time); 164 this.hour = (byte) calendar.get(Calendar.HOUR_OF_DAY); 165 this.day = new Day(time, zone, locale); 166 peg(calendar); 167 } 168 169 /** 170 * Returns the hour. 171 * 172 * @return The hour (0 <= hour <= 23). 173 */ 174 public int getHour() { 175 return this.hour; 176 } 177 178 /** 179 * Returns the day in which this hour falls. 180 * 181 * @return The day. 182 */ 183 public Day getDay() { 184 return this.day; 185 } 186 187 /** 188 * Returns the year in which this hour falls. 189 * 190 * @return The year. 191 */ 192 public int getYear() { 193 return this.day.getYear(); 194 } 195 196 /** 197 * Returns the month in which this hour falls. 198 * 199 * @return The month. 200 */ 201 public int getMonth() { 202 return this.day.getMonth(); 203 } 204 205 /** 206 * Returns the day-of-the-month in which this hour falls. 207 * 208 * @return The day-of-the-month. 209 */ 210 public int getDayOfMonth() { 211 return this.day.getDayOfMonth(); 212 } 213 214 /** 215 * Returns the first millisecond of the hour. This will be determined 216 * relative to the time zone specified in the constructor, or in the 217 * calendar instance passed in the most recent call to the 218 * {@link #peg(Calendar)} method. 219 * 220 * @return The first millisecond of the hour. 221 * 222 * @see #getLastMillisecond() 223 */ 224 @Override 225 public long getFirstMillisecond() { 226 return this.firstMillisecond; 227 } 228 229 /** 230 * Returns the last millisecond of the hour. This will be 231 * determined relative to the time zone specified in the constructor, or 232 * in the calendar instance passed in the most recent call to the 233 * {@link #peg(Calendar)} method. 234 * 235 * @return The last millisecond of the hour. 236 * 237 * @see #getFirstMillisecond() 238 */ 239 @Override 240 public long getLastMillisecond() { 241 return this.lastMillisecond; 242 } 243 244 /** 245 * Recalculates the start date/time and end date/time for this time period 246 * relative to the supplied calendar (which incorporates a time zone). 247 * 248 * @param calendar the calendar ({@code null} not permitted). 249 * 250 * @since 1.0.3 251 */ 252 @Override 253 public void peg(Calendar calendar) { 254 this.firstMillisecond = getFirstMillisecond(calendar); 255 this.lastMillisecond = getLastMillisecond(calendar); 256 } 257 258 /** 259 * Returns the hour preceding this one. 260 * 261 * @return The hour preceding this one. 262 */ 263 @Override 264 public RegularTimePeriod previous() { 265 Hour result; 266 if (this.hour != FIRST_HOUR_IN_DAY) { 267 result = new Hour(this.hour - 1, this.day); 268 } 269 else { // we are at the first hour in the day... 270 Day prevDay = (Day) this.day.previous(); 271 if (prevDay != null) { 272 result = new Hour(LAST_HOUR_IN_DAY, prevDay); 273 } 274 else { 275 result = null; 276 } 277 } 278 return result; 279 } 280 281 /** 282 * Returns the hour following this one. 283 * 284 * @return The hour following this one. 285 */ 286 @Override 287 public RegularTimePeriod next() { 288 Hour result; 289 if (this.hour != LAST_HOUR_IN_DAY) { 290 result = new Hour(this.hour + 1, this.day); 291 } 292 else { // we are at the last hour in the day... 293 Day nextDay = (Day) this.day.next(); 294 if (nextDay != null) { 295 result = new Hour(FIRST_HOUR_IN_DAY, nextDay); 296 } 297 else { 298 result = null; 299 } 300 } 301 return result; 302 } 303 304 /** 305 * Returns a serial index number for the hour. 306 * 307 * @return The serial index number. 308 */ 309 @Override 310 public long getSerialIndex() { 311 return this.day.getSerialIndex() * 24L + this.hour; 312 } 313 314 /** 315 * Returns the first millisecond of the hour. 316 * 317 * @param calendar the calendar/timezone ({@code null} not permitted). 318 * 319 * @return The first millisecond. 320 * 321 * @throws NullPointerException if {@code calendar} is 322 * {@code null}. 323 */ 324 @Override 325 public long getFirstMillisecond(Calendar calendar) { 326 int year = this.day.getYear(); 327 int month = this.day.getMonth() - 1; 328 int dom = this.day.getDayOfMonth(); 329 calendar.set(year, month, dom, this.hour, 0, 0); 330 calendar.set(Calendar.MILLISECOND, 0); 331 return calendar.getTimeInMillis(); 332 } 333 334 /** 335 * Returns the last millisecond of the hour. 336 * 337 * @param calendar the calendar/timezone ({@code null} not permitted). 338 * 339 * @return The last millisecond. 340 * 341 * @throws NullPointerException if {@code calendar} is 342 * {@code null}. 343 */ 344 @Override 345 public long getLastMillisecond(Calendar calendar) { 346 int year = this.day.getYear(); 347 int month = this.day.getMonth() - 1; 348 int dom = this.day.getDayOfMonth(); 349 calendar.set(year, month, dom, this.hour, 59, 59); 350 calendar.set(Calendar.MILLISECOND, 999); 351 return calendar.getTimeInMillis(); 352 } 353 354 /** 355 * Tests the equality of this object against an arbitrary Object. 356 * <P> 357 * This method will return true ONLY if the object is an Hour object 358 * representing the same hour as this instance. 359 * 360 * @param obj the object to compare ({@code null} permitted). 361 * 362 * @return {@code true} if the hour and day value of the object 363 * is the same as this. 364 */ 365 @Override 366 public boolean equals(Object obj) { 367 if (obj == this) { 368 return true; 369 } 370 if (!(obj instanceof Hour)) { 371 return false; 372 } 373 Hour that = (Hour) obj; 374 if (this.hour != that.hour) { 375 return false; 376 } 377 if (!this.day.equals(that.day)) { 378 return false; 379 } 380 return true; 381 } 382 383 /** 384 * Returns a string representation of this instance, for debugging 385 * purposes. 386 * 387 * @return A string. 388 */ 389 @Override 390 public String toString() { 391 return "[" + this.hour + "," + getDayOfMonth() + "/" + getMonth() + "/" 392 + getYear() + "]"; 393 } 394 395 /** 396 * Returns a hash code for this object instance. The approach described by 397 * Joshua Bloch in "Effective Java" has been used here: 398 * <p> 399 * {@code http://developer.java.sun.com/developer/Books/effectivejava 400 * /Chapter3.pdf} 401 * 402 * @return A hash code. 403 */ 404 @Override 405 public int hashCode() { 406 int result = 17; 407 result = 37 * result + this.hour; 408 result = 37 * result + this.day.hashCode(); 409 return result; 410 } 411 412 /** 413 * Returns an integer indicating the order of this Hour object relative to 414 * the specified object: 415 * 416 * negative == before, zero == same, positive == after. 417 * 418 * @param o1 the object to compare. 419 * 420 * @return negative == before, zero == same, positive == after. 421 */ 422 @Override 423 public int compareTo(Object o1) { 424 int result; 425 426 // CASE 1 : Comparing to another Hour object 427 // ----------------------------------------- 428 if (o1 instanceof Hour) { 429 Hour h = (Hour) o1; 430 result = getDay().compareTo(h.getDay()); 431 if (result == 0) { 432 result = this.hour - h.getHour(); 433 } 434 } 435 436 // CASE 2 : Comparing to another TimePeriod object 437 // ----------------------------------------------- 438 else if (o1 instanceof RegularTimePeriod) { 439 // more difficult case - evaluate later... 440 result = 0; 441 } 442 443 // CASE 3 : Comparing to a non-TimePeriod object 444 // --------------------------------------------- 445 else { 446 // consider time periods to be ordered after general objects 447 result = 1; 448 } 449 450 return result; 451 } 452 453 /** 454 * Creates an Hour instance by parsing a string. The string is assumed to 455 * be in the format "YYYY-MM-DD HH", perhaps with leading or trailing 456 * whitespace. 457 * 458 * @param s the hour string to parse. 459 * 460 * @return {@code null} if the string is not parseable, the hour 461 * otherwise. 462 */ 463 public static Hour parseHour(String s) { 464 Hour result = null; 465 s = s.trim(); 466 467 String daystr = s.substring(0, Math.min(10, s.length())); 468 Day day = Day.parseDay(daystr); 469 if (day != null) { 470 String hourstr = s.substring( 471 Math.min(daystr.length() + 1, s.length()), s.length() 472 ); 473 hourstr = hourstr.trim(); 474 int hour = Integer.parseInt(hourstr); 475 // if the hour is 0 - 23 then create an hour 476 if ((hour >= FIRST_HOUR_IN_DAY) && (hour <= LAST_HOUR_IN_DAY)) { 477 result = new Hour(hour, day); 478 } 479 } 480 481 return result; 482 } 483 484}