net.time4j.ZonalClock Maven / Gradle / Ivy
/*
* -----------------------------------------------------------------------
* Copyright © 2013-2015 Meno Hochschild, Represents a clock which yields the current local time according
* to a timezone.
*
* This class is immutable as long as the underlying implementations
* of time source and time zone are.
*
* @author Meno Hochschild
* @see SystemClock#inLocalView()
* @see SystemClock#inZonalView(TZID)
*/
/*[deutsch]
* Repräsentiert eine Uhr, die die aktuelle lokale Zeit anzeigt.
*
* Diese Klasse ist solange immutable (unveränderlich), wie
* die zugrundeliegenden Implementierungen der Zeitquelle und der Zeitzone
* es sind.
*
* @author Meno Hochschild
* @see SystemClock#inLocalView()
* @see SystemClock#inZonalView(TZID)
*/
public final class ZonalClock {
// --------------------
// Implementation note:
// --------------------
// This class does not implement the interface TimeSource intentionally
// because it is really designed for querying "zonal" times but not for
// being injected into any test class or business object. Otherwise
// zonal dependencies could be obfuscated from a user-perspective.
// Instead users are strongly encouraged to use expressions like
// SystemClock#inZonalView(TZID).
//~ Statische Felder/Initialisierungen --------------------------------
private static final ZonalClock SYSTEM = new ZonalClock();
//~ Instanzvariablen --------------------------------------------------
private final TimeSource timeSource;
private final Timezone timezone;
//~ Konstruktoren -----------------------------------------------------
/**
* Constructs a new clock which can yield the current local time in
* given timezone.
*
* Most users have no need to directly call this constructor. It is
* mainly designed for being called by dedicated expressions like
* {@code SystemClock.inZonalView(tzid)} etc.
*
* @param timeSource source for current world time (UTC)
* @param tzid timezone id
* @throws IllegalArgumentException if given timezone cannot be loaded
*/
/*[deutsch]
* Konstruiert eine neue Uhr, die die aktuelle Zeit in einer Zeitzone
* ermitteln kann.
*
* Die meisten Anwender brauchen diesen Konstruktor nicht. Er ist
* im wesentlichen für den Aufruf durch spezielle Ausdrücke
* wie {@code SystemClock.inZonalView(tzid)} etc. gedacht.
*
* @param timeSource source for current world time (UTC)
* @param tzid timezone id
* @throws IllegalArgumentException if given timezone cannot be loaded
*/
public ZonalClock(
TimeSource timeSource,
TZID tzid
) {
if (timeSource == null) {
throw new NullPointerException("Missing time source.");
} else if (tzid == null) {
throw new NullPointerException("Missing timezone id.");
}
this.timeSource = timeSource;
this.timezone = Timezone.of(tzid);
}
/**
* Constructs a new clock which can yield the current local time in
* given timezone.
*
* Most users have no need to directly call this constructor. It is
* mainly designed for being called by dedicated expressions like
* {@code SystemClock.inZonalView(tzid)} etc.
*
* @param timeSource source for current world time (UTC)
* @param tzid timezone id
* @throws IllegalArgumentException if given timezone cannot be loaded
*/
/*[deutsch]
* Konstruiert eine neue Uhr, die die aktuelle Zeit in einer Zeitzone
* ermitteln kann.
*
* Die meisten Anwender brauchen diesen Konstruktor nicht. Er ist
* im wesentlichen für den Aufruf durch spezielle Ausdrücke
* wie {@code SystemClock.inZonalView(tzid)} etc. gedacht.
*
* @param timeSource source for current world time (UTC)
* @param tzid timezone id
* @throws IllegalArgumentException if given timezone cannot be loaded
*/
public ZonalClock(
TimeSource timeSource,
String tzid
) {
if (timeSource == null) {
throw new NullPointerException("Missing time source.");
} else if (tzid.isEmpty()) {
throw new NullPointerException("Timezone id is empty.");
}
this.timeSource = timeSource;
this.timezone = Timezone.of(tzid);
}
private ZonalClock() {
super();
this.timeSource = SystemClock.INSTANCE;
this.timezone = Timezone.ofSystem();
}
//~ Methoden ----------------------------------------------------------
/**
* Gets the current timestamp in the associated timezone.
*
* @return current local timestamp
*/
/*[deutsch]
* Ermittelt die aktuelle Zeit in der assoziierten Zeitzone.
*
* @return current local timestamp
*/
public PlainTimestamp now() {
final UnixTime ut = this.timeSource.currentTime();
return PlainTimestamp.from(ut, this.timezone.getOffset(ut));
}
/**
* Gets the current date in the associated timezone.
*
* @return calendar date representing today
*/
/**
* Ermittelt das aktuelle Datum in der assoziierten Zeitzone.
*
* @return calendar date representing today
*/
public PlainDate today() {
final UnixTime ut = this.timeSource.currentTime();
return PlainDate.from(ut, this.timezone.getOffset(ut));
}
/**
* Gets the associated clock.
*
* @return time source
*/
/*[deutsch]
* Liefert die assoziierte Uhr.
*
* @return Zeitquelle
*/
public TimeSource getSource() {
return this.timeSource;
}
/**
* Gets the associated timezone.
*
* @return timezone id
*/
/*[deutsch]
* Liefert die assoziierte Zeitzone.
*
* @return timezone id
*/
public TZID getTimezone() {
return this.timezone.getID();
}
/**
* Zonale Uhr basierend auf den Systemeinstellungen beim Laden
* dieser Klasse.
*
* @return local clock in default system timezone
*/
static ZonalClock ofSystem() {
return SYSTEM;
}
}