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