src/share/classes/java/time/Clock.java

Print this page




 360      * A clock will typically obtain the current instant and then convert that
 361      * to a date or time using a time-zone. This method returns a clock with
 362      * similar properties but using a different time-zone.
 363      *
 364      * @param zone  the time-zone to change to, not null
 365      * @return a clock based on this clock with the specified time-zone, not null
 366      */
 367     public abstract Clock withZone(ZoneId zone);
 368 
 369     //-------------------------------------------------------------------------
 370     /**
 371      * Gets the current millisecond instant of the clock.
 372      * <p>
 373      * This returns the millisecond-based instant, measured from 1970-01-01T00:00 UTC.
 374      * This is equivalent to the definition of {@link System#currentTimeMillis()}.
 375      * <p>
 376      * Most applications should avoid this method and use {@link Instant} to represent
 377      * an instant on the time-line rather than a raw millisecond value.
 378      * This method is provided to allow the use of the clock in high performance use cases
 379      * where the creation of an object would be unacceptable.


 380      *
 381      * @return the current millisecond instant from this clock, measured from
 382      *  the Java epoch of 1970-01-01T00:00 UTC, not null
 383      * @throws DateTimeException if the instant cannot be obtained, not thrown by most implementations
 384      */
 385     public abstract long millis();


 386 
 387     //-----------------------------------------------------------------------
 388     /**
 389      * Gets the current instant of the clock.
 390      * <p>
 391      * This returns an instant representing the current instant as defined by the clock.
 392      * <p>
 393      * The default implementation currently calls {@link #millis}.
 394      *
 395      * @return the current instant from this clock, not null
 396      * @throws DateTimeException if the instant cannot be obtained, not thrown by most implementations
 397      */
 398     public Instant instant() {
 399         return Instant.ofEpochMilli(millis());
 400     }
 401 
 402     //-----------------------------------------------------------------------
 403     /**
 404      * Checks if this clock is equal to another clock.
 405      * <p>
 406      * Clocks must compare equal based on their state and behavior.


 407      *
 408      * @param obj  the object to check, null returns false
 409      * @return true if this is equal to the other clock
 410      */
 411     @Override
 412     public abstract boolean equals(Object obj);


 413 
 414     /**
 415      * A hash code for this clock.
 416      *
 417      * @return a suitable hash code
 418      */
 419     @Override
 420     public abstract int hashCode();
 421 
 422     //-----------------------------------------------------------------------
 423     /**
 424      * Returns a string describing this clock.
 425      * <p>
 426      * Clocks must have a string representation based on their state and behavior.
 427      * For example, 'System[Europe/Paris]' could be used to represent the System
 428      * clock in the 'Europe/Paris' time-zone.
 429      *
 430      * @return a string representation of this clock, not null
 431      */
 432     @Override
 433     public abstract String toString();


 434 
 435     //-----------------------------------------------------------------------
 436     /**
 437      * Implementation of a clock that always returns the latest time from
 438      * {@link System#currentTimeMillis()}.
 439      */
 440     static final class SystemClock extends Clock implements Serializable {
 441         private static final long serialVersionUID = 6740630888130243051L;
 442         private final ZoneId zone;
 443 
 444         SystemClock(ZoneId zone) {
 445             this.zone = zone;
 446         }
 447         @Override
 448         public ZoneId getZone() {
 449             return zone;
 450         }
 451         @Override
 452         public Clock withZone(ZoneId zone) {
 453             if (zone.equals(this.zone)) {  // intentional NPE
 454                 return this;
 455             }
 456             return new SystemClock(zone);
 457         }
 458         @Override
 459         public long millis() {
 460             return System.currentTimeMillis();
 461         }
 462         @Override




 463         public boolean equals(Object obj) {
 464             if (obj instanceof SystemClock) {
 465                 return zone.equals(((SystemClock) obj).zone);
 466             }
 467             return false;
 468         }
 469         @Override
 470         public int hashCode() {
 471             return zone.hashCode() + 1;
 472         }
 473         @Override
 474         public String toString() {
 475             return "SystemClock[" + zone + "]";
 476         }
 477     }
 478 
 479     //-----------------------------------------------------------------------
 480     /**
 481      * Implementation of a clock that always returns the same instant.
 482      * This is typically used for testing.




 360      * A clock will typically obtain the current instant and then convert that
 361      * to a date or time using a time-zone. This method returns a clock with
 362      * similar properties but using a different time-zone.
 363      *
 364      * @param zone  the time-zone to change to, not null
 365      * @return a clock based on this clock with the specified time-zone, not null
 366      */
 367     public abstract Clock withZone(ZoneId zone);
 368 
 369     //-------------------------------------------------------------------------
 370     /**
 371      * Gets the current millisecond instant of the clock.
 372      * <p>
 373      * This returns the millisecond-based instant, measured from 1970-01-01T00:00 UTC.
 374      * This is equivalent to the definition of {@link System#currentTimeMillis()}.
 375      * <p>
 376      * Most applications should avoid this method and use {@link Instant} to represent
 377      * an instant on the time-line rather than a raw millisecond value.
 378      * This method is provided to allow the use of the clock in high performance use cases
 379      * where the creation of an object would be unacceptable.
 380      * <p>
 381      * The default implementation currently calls {@link #instant}.
 382      *
 383      * @return the current millisecond instant from this clock, measured from
 384      *  the Java epoch of 1970-01-01T00:00 UTC, not null
 385      * @throws DateTimeException if the instant cannot be obtained, not thrown by most implementations
 386      */
 387     public long millis() {
 388         return instant().toEpochMilli();
 389     }
 390 
 391     //-----------------------------------------------------------------------
 392     /**
 393      * Gets the current instant of the clock.
 394      * <p>
 395      * This returns an instant representing the current instant as defined by the clock.


 396      *
 397      * @return the current instant from this clock, not null
 398      * @throws DateTimeException if the instant cannot be obtained, not thrown by most implementations
 399      */
 400     public abstract Instant instant();


 401 
 402     //-----------------------------------------------------------------------
 403     /**
 404      * Checks if this clock is equal to another clock.
 405      * <p>
 406      * Clocks should override this method to compare equals based on
 407      * their state and to meet the contract of {@link Object#equals}.
 408      * If not overridden, the behavior is defined by {@link Object#equals}
 409      *
 410      * @param obj  the object to check, null returns false
 411      * @return true if this is equal to the other clock
 412      */
 413     @Override
 414     public boolean equals(Object obj) {
 415         return super.equals(obj);
 416     }
 417 
 418     /**
 419      * A hash code for this clock.









 420      * <p>
 421      * Clocks should override this method based on
 422      * their state and to meet the contract of {@link Object#hashCode}.
 423      * If not overridden, the behavior is defined by {@link Object#hashCode}
 424      *
 425      * @return a suitable hash code
 426      */
 427     @Override
 428     public  int hashCode() {
 429         return super.hashCode();
 430     }
 431 
 432     //-----------------------------------------------------------------------
 433     /**
 434      * Implementation of a clock that always returns the latest time from
 435      * {@link System#currentTimeMillis()}.
 436      */
 437     static final class SystemClock extends Clock implements Serializable {
 438         private static final long serialVersionUID = 6740630888130243051L;
 439         private final ZoneId zone;
 440 
 441         SystemClock(ZoneId zone) {
 442             this.zone = zone;
 443         }
 444         @Override
 445         public ZoneId getZone() {
 446             return zone;
 447         }
 448         @Override
 449         public Clock withZone(ZoneId zone) {
 450             if (zone.equals(this.zone)) {  // intentional NPE
 451                 return this;
 452             }
 453             return new SystemClock(zone);
 454         }
 455         @Override
 456         public long millis() {
 457             return System.currentTimeMillis();
 458         }
 459         @Override
 460         public Instant instant() {
 461             return Instant.ofEpochMilli(millis());
 462         }
 463         @Override
 464         public boolean equals(Object obj) {
 465             if (obj instanceof SystemClock) {
 466                 return zone.equals(((SystemClock) obj).zone);
 467             }
 468             return false;
 469         }
 470         @Override
 471         public int hashCode() {
 472             return zone.hashCode() + 1;
 473         }
 474         @Override
 475         public String toString() {
 476             return "SystemClock[" + zone + "]";
 477         }
 478     }
 479 
 480     //-----------------------------------------------------------------------
 481     /**
 482      * Implementation of a clock that always returns the same instant.
 483      * This is typically used for testing.