138
139 /**
140 * Obtains a clock that returns the current instant using the best available
141 * system clock, converting to date and time using the UTC time-zone.
142 * <p>
143 * This clock, rather than {@link #systemDefaultZone()}, should be used when
144 * you need the current instant without the date or time.
145 * <p>
146 * This clock is based on the best available system clock.
147 * This may use {@link System#currentTimeMillis()}, or a higher resolution
148 * clock if one is available.
149 * <p>
150 * Conversion from instant to date or time uses the {@linkplain ZoneOffset#UTC UTC time-zone}.
151 * <p>
152 * The returned implementation is immutable, thread-safe and {@code Serializable}.
153 * It is equivalent to {@code system(ZoneOffset.UTC)}.
154 *
155 * @return a clock that uses the best available system clock in the UTC zone, not null
156 */
157 public static Clock systemUTC() {
158 return new SystemClock(ZoneOffset.UTC);
159 }
160
161 /**
162 * Obtains a clock that returns the current instant using the best available
163 * system clock, converting to date and time using the default time-zone.
164 * <p>
165 * This clock is based on the best available system clock.
166 * This may use {@link System#currentTimeMillis()}, or a higher resolution
167 * clock if one is available.
168 * <p>
169 * Using this method hard codes a dependency to the default time-zone into your application.
170 * It is recommended to avoid this and use a specific time-zone whenever possible.
171 * The {@link #systemUTC() UTC clock} should be used when you need the current instant
172 * without the date or time.
173 * <p>
174 * The returned implementation is immutable, thread-safe and {@code Serializable}.
175 * It is equivalent to {@code system(ZoneId.systemDefault())}.
176 *
177 * @return a clock that uses the best available system clock in the default zone, not null
178 * @see ZoneId#systemDefault()
181 return new SystemClock(ZoneId.systemDefault());
182 }
183
184 /**
185 * Obtains a clock that returns the current instant using best available
186 * system clock.
187 * <p>
188 * This clock is based on the best available system clock.
189 * This may use {@link System#currentTimeMillis()}, or a higher resolution
190 * clock if one is available.
191 * <p>
192 * Conversion from instant to date or time uses the specified time-zone.
193 * <p>
194 * The returned implementation is immutable, thread-safe and {@code Serializable}.
195 *
196 * @param zone the time-zone to use to convert the instant to date-time, not null
197 * @return a clock that uses the best available system clock in the specified zone, not null
198 */
199 public static Clock system(ZoneId zone) {
200 Objects.requireNonNull(zone, "zone");
201 return new SystemClock(zone);
202 }
203
204 //-------------------------------------------------------------------------
205 /**
206 * Obtains a clock that returns the current instant ticking in whole seconds
207 * using best available system clock.
208 * <p>
209 * This clock will always have the nano-of-second field set to zero.
210 * This ensures that the visible time ticks in whole seconds.
211 * The underlying clock is the best available system clock, equivalent to
212 * using {@link #system(ZoneId)}.
213 * <p>
214 * Implementations may use a caching strategy for performance reasons.
215 * As such, it is possible that the start of the second observed via this
216 * clock will be later than that observed directly via the underlying clock.
217 * <p>
218 * The returned implementation is immutable, thread-safe and {@code Serializable}.
219 * It is equivalent to {@code tick(system(zone), Duration.ofSeconds(1))}.
220 *
434 * Clocks should override this method based on
435 * their state and to meet the contract of {@link Object#hashCode}.
436 * If not overridden, the behavior is defined by {@link Object#hashCode}
437 *
438 * @return a suitable hash code
439 */
440 @Override
441 public int hashCode() {
442 return super.hashCode();
443 }
444
445 //-----------------------------------------------------------------------
446 /**
447 * Implementation of a clock that always returns the latest time from
448 * {@link System#currentTimeMillis()}.
449 */
450 static final class SystemClock extends Clock implements Serializable {
451 private static final long serialVersionUID = 6740630888130243051L;
452 private static final long OFFSET_SEED =
453 System.currentTimeMillis()/1000 - 1024; // initial offest
454 private final ZoneId zone;
455 // We don't actually need a volatile here.
456 // We don't care if offset is set or read concurrently by multiple
457 // threads - we just need a value which is 'recent enough' - in other
458 // words something that has been updated at least once in the last
459 // 2^32 secs (~136 years). And even if we by chance see an invalid
460 // offset, the worst that can happen is that we will get a -1 value
461 // from getNanoTimeAdjustment, forcing us to update the offset
462 // once again.
463 private transient long offset;
464
465 SystemClock(ZoneId zone) {
466 this.zone = zone;
467 this.offset = OFFSET_SEED;
468 }
469 @Override
470 public ZoneId getZone() {
471 return zone;
472 }
473 @Override
|
138
139 /**
140 * Obtains a clock that returns the current instant using the best available
141 * system clock, converting to date and time using the UTC time-zone.
142 * <p>
143 * This clock, rather than {@link #systemDefaultZone()}, should be used when
144 * you need the current instant without the date or time.
145 * <p>
146 * This clock is based on the best available system clock.
147 * This may use {@link System#currentTimeMillis()}, or a higher resolution
148 * clock if one is available.
149 * <p>
150 * Conversion from instant to date or time uses the {@linkplain ZoneOffset#UTC UTC time-zone}.
151 * <p>
152 * The returned implementation is immutable, thread-safe and {@code Serializable}.
153 * It is equivalent to {@code system(ZoneOffset.UTC)}.
154 *
155 * @return a clock that uses the best available system clock in the UTC zone, not null
156 */
157 public static Clock systemUTC() {
158 return SystemClock.UTC;
159 }
160
161 /**
162 * Obtains a clock that returns the current instant using the best available
163 * system clock, converting to date and time using the default time-zone.
164 * <p>
165 * This clock is based on the best available system clock.
166 * This may use {@link System#currentTimeMillis()}, or a higher resolution
167 * clock if one is available.
168 * <p>
169 * Using this method hard codes a dependency to the default time-zone into your application.
170 * It is recommended to avoid this and use a specific time-zone whenever possible.
171 * The {@link #systemUTC() UTC clock} should be used when you need the current instant
172 * without the date or time.
173 * <p>
174 * The returned implementation is immutable, thread-safe and {@code Serializable}.
175 * It is equivalent to {@code system(ZoneId.systemDefault())}.
176 *
177 * @return a clock that uses the best available system clock in the default zone, not null
178 * @see ZoneId#systemDefault()
181 return new SystemClock(ZoneId.systemDefault());
182 }
183
184 /**
185 * Obtains a clock that returns the current instant using best available
186 * system clock.
187 * <p>
188 * This clock is based on the best available system clock.
189 * This may use {@link System#currentTimeMillis()}, or a higher resolution
190 * clock if one is available.
191 * <p>
192 * Conversion from instant to date or time uses the specified time-zone.
193 * <p>
194 * The returned implementation is immutable, thread-safe and {@code Serializable}.
195 *
196 * @param zone the time-zone to use to convert the instant to date-time, not null
197 * @return a clock that uses the best available system clock in the specified zone, not null
198 */
199 public static Clock system(ZoneId zone) {
200 Objects.requireNonNull(zone, "zone");
201 if (zone == ZoneOffset.UTC) {
202 return SystemClock.UTC;
203 }
204 return new SystemClock(zone);
205 }
206
207 //-------------------------------------------------------------------------
208 /**
209 * Obtains a clock that returns the current instant ticking in whole seconds
210 * using best available system clock.
211 * <p>
212 * This clock will always have the nano-of-second field set to zero.
213 * This ensures that the visible time ticks in whole seconds.
214 * The underlying clock is the best available system clock, equivalent to
215 * using {@link #system(ZoneId)}.
216 * <p>
217 * Implementations may use a caching strategy for performance reasons.
218 * As such, it is possible that the start of the second observed via this
219 * clock will be later than that observed directly via the underlying clock.
220 * <p>
221 * The returned implementation is immutable, thread-safe and {@code Serializable}.
222 * It is equivalent to {@code tick(system(zone), Duration.ofSeconds(1))}.
223 *
437 * Clocks should override this method based on
438 * their state and to meet the contract of {@link Object#hashCode}.
439 * If not overridden, the behavior is defined by {@link Object#hashCode}
440 *
441 * @return a suitable hash code
442 */
443 @Override
444 public int hashCode() {
445 return super.hashCode();
446 }
447
448 //-----------------------------------------------------------------------
449 /**
450 * Implementation of a clock that always returns the latest time from
451 * {@link System#currentTimeMillis()}.
452 */
453 static final class SystemClock extends Clock implements Serializable {
454 private static final long serialVersionUID = 6740630888130243051L;
455 private static final long OFFSET_SEED =
456 System.currentTimeMillis()/1000 - 1024; // initial offest
457 static final SystemClock UTC = new SystemClock(ZoneOffset.UTC);
458
459 private final ZoneId zone;
460 // We don't actually need a volatile here.
461 // We don't care if offset is set or read concurrently by multiple
462 // threads - we just need a value which is 'recent enough' - in other
463 // words something that has been updated at least once in the last
464 // 2^32 secs (~136 years). And even if we by chance see an invalid
465 // offset, the worst that can happen is that we will get a -1 value
466 // from getNanoTimeAdjustment, forcing us to update the offset
467 // once again.
468 private transient long offset;
469
470 SystemClock(ZoneId zone) {
471 this.zone = zone;
472 this.offset = OFFSET_SEED;
473 }
474 @Override
475 public ZoneId getZone() {
476 return zone;
477 }
478 @Override
|