public final class SolarTime extends java.lang.Object implements GeoLocation, java.io.Serializable
Notice: Most chronological functions use the astronomical equation of time. Hence they are only applicable
for years between -2000 and +3000 otherwise an IllegalArgumentException will be thrown.
Example for sunrise and sunset on the top of Africas highest mountain Kilimanjaro:
PlainDate date = PlainDate.of(2017, 12, 22);
TZID tzid = Timezone.of("Africa/Dar_es_Salaam").getID(); // Tanzania: UTC+03:00
// high altitude implies earlier sunrise and later sunset
SolarTime kibo5895 =
SolarTime.ofLocation()
.southernLatitude(3, 4, 0)
.easternLongitude(37, 21, 33)
.atAltitude(5895)
.usingCalculator(StdSolarCalculator.TIME4J) // this calculator takes into account the altitude
.build();
assertThat(
date.get(kibo5895.sunrise(tzid)),
is(PlainTime.of(6, 10, 34)));
assertThat(
date.get(kibo5895.sunset(tzid)),
is(PlainTime.of(18, 47, 48)));
About limitations of accuracy:
Time4J only models a spherical geometry but not local topology with mountains which can break the horizon line. Furthermore, special weather conditions which can have a bigger impact on atmospheric refraction are not calculatable. The concrete calculator in use is also a limiting factor for accuracy. Users should therefore not expect more than minute precision. This can be even worse for polar regions because the sun crosses then the horizon under a very shallow angle.
Interpretation of calendar dates:
This class interpretes every calendar date input as on LMT (Local Mean Time) unless the builder-method
SolarTime.Builder.inTimezone(TZID) is called. Users only need
to pay attention to this subtile difference if a few areas along the international date border
like Kiribati or Samoa are involved. Following example demonstrates the difference:
LMT-date
TZID tzid = Timezone.of("Pacific/Apia").getID();
SolarTime apia = SolarTime.ofLocation().southernLatitude(13, 50, 0).westernLongitude(171, 45, 0).build();
assertThat(
PlainDate.of(2011, 12, 31).get(apia.sunrise()).toZonalTimestamp(tzid),
is(PlainTimestamp.of(2012, 1, 1, 7, 2, 13))); // civil date is one day later than LMT-date
Zoned date
TZID tzid = Timezone.of("Pacific/Apia").getID();
SolarTime apia =
SolarTime.ofLocation()
.southernLatitude(13, 50, 0)
.westernLongitude(171, 45, 0)
.inTimezone(tzid)
.build();
assertThat(
PlainDate.of(2012, 1, 1).get(apia.sunrise()).toZonalTimestamp(tzid),
is(PlainTimestamp.of(2012, 1, 1, 7, 2, 13))); // civil date is same as input
| Modifier and Type | Class and Description |
|---|---|
static class |
SolarTime.Builder
Helper class to construct a new instance of
SolarTime. |
static interface |
SolarTime.Calculator
An SPI-interface representing a facade for the calculation engine regarding sunrise or sunset.
|
static class |
SolarTime.Sunshine
Collects various data around sunrise and sunset.
|
| Modifier and Type | Method and Description |
|---|---|
static ChronoFunction<Moment,PlainTimestamp> |
apparentAt(ZonalOffset offset)
Determines the apparent solar time of any moment at given local time zone offset.
|
static ChronoFunction<Moment,PlainTimestamp> |
apparentAt(ZonalOffset offset,
java.lang.String calculator)
Determines the apparent solar time of any moment at given local time zone offset.
|
boolean |
equals(java.lang.Object obj) |
static double |
equationOfTime(Moment moment)
Determines the difference between apparent and mean solar time at given moment.
|
static double |
equationOfTime(Moment moment,
java.lang.String calculator)
Determines the difference between apparent and mean solar time at given moment.
|
int |
getAltitude()
Obtains the geographical altitude of this instance relative to sea level.
|
SolarTime.Calculator |
getCalculator()
Obtains the name of the underlying calculator.
|
double |
getLatitude()
Obtains the geographical latitude of this instance.
|
double |
getLongitude()
Obtains the geographical longitude of this instance.
|
int |
hashCode() |
ChronoCondition<CalendarDate> |
midnightSun()
Determines if the sun is visible all day on a given calendar date.
|
static SolarTime |
ofJerusalem()
Obtains an instance of solar time for the temple area in Jerusalem which has a prominent meaning
in Hebrew calendar and time.
|
static SolarTime.Builder |
ofLocation()
Obtains a builder for creating a new instance of local solar time.
|
static SolarTime |
ofLocation(double latitude,
double longitude)
Obtains the solar time for given geographical location at sea level.
|
static SolarTime |
ofLocation(double latitude,
double longitude,
int altitude,
SolarTime.Calculator calculator)
Obtains the solar time for given geographical location.
|
static SolarTime |
ofLocation(double latitude,
double longitude,
int altitude,
java.lang.String calculator)
Obtains the solar time for given geographical location.
|
static SolarTime |
ofMecca()
Obtains an instance of solar time for the Kaaba in Mecca which has a prominent meaning
in islamic calendar.
|
static ChronoFunction<Moment,PlainTimestamp> |
onAverage(ZonalOffset offset)
Determines the mean solar time of any moment at given local time zone offset.
|
ChronoCondition<CalendarDate> |
polarNight()
Determines if the sun is invisible all day on a given calendar date.
|
ChronoFunction<CalendarDate,Moment> |
sunrise()
Calculates the moment of sunrise at the location of this instance.
|
ChronoFunction<CalendarDate,Moment> |
sunrise(Twilight twilight)
Calculates the time of given twilight at sunrise and the location of this instance.
|
ChronoFunction<CalendarDate,PlainTime> |
sunrise(TZID tzid)
Deprecated.
This method looses the day information so users are asked to use
sunrise() instead. |
ChronoFunction<CalendarDate,Moment> |
sunset()
Calculates the moment of sunset at the location of this instance.
|
ChronoFunction<CalendarDate,Moment> |
sunset(Twilight twilight)
Calculates the time of given twilight at sunset and the location of this instance.
|
ChronoFunction<CalendarDate,PlainTime> |
sunset(TZID tzid)
Deprecated.
This method looses the day information so users are asked to use
sunset() instead. |
ChronoFunction<CalendarDate,SolarTime.Sunshine> |
sunshine(TZID tzid)
Queries a given calendar date for its associated sunshine data.
|
java.lang.String |
toString() |
ChronoFunction<CalendarDate,Moment> |
transitAtMidnight()
Calculates the moment of midnight at the location of this instance (lowest position of sun).
|
ChronoFunction<CalendarDate,PlainTime> |
transitAtMidnight(TZID tzid)
Deprecated.
This method looses the day information so users ought to use
transitAtMidnight() instead. |
ChronoFunction<CalendarDate,Moment> |
transitAtNoon()
Calculates the moment of noon at the location of this instance (solar transit).
|
ChronoFunction<CalendarDate,PlainTime> |
transitAtNoon(TZID tzid)
Deprecated.
This method looses the day information so users are asked to use
transitAtNoon() instead. |
public static SolarTime.Builder ofLocation()
Obtains a builder for creating a new instance of local solar time.
This method is the recommended approach if any given geographical position is described in degrees including arc minutes and arc seconds in order to avoid manual conversions to decimal degrees.
public static SolarTime ofLocation(double latitude, double longitude)
Obtains the solar time for given geographical location at sea level.
The default calculator is usually StdSolarCalculator.NOAA unless another calculator was
set up via the service loader mechnism.
This method handles the geographical location in decimal degrees only. If these data are given
in degrees, arc minutes and arc seconds then users should apply the builder
approach instead.
latitude - geographical latitude in decimal degrees (-90.0 <= x <= +90.0)longitude - geographical longitude in decimal degrees (-180.0 <= x < 180.0)java.lang.IllegalArgumentException - if the coordinates are out of rangeofLocation(double, double, int, String)public static SolarTime ofLocation(double latitude, double longitude, int altitude, java.lang.String calculator)
Obtains the solar time for given geographical location.
This method handles the geographical location in decimal degrees only. If these data are given
in degrees, arc minutes and arc seconds then users should apply the builder
approach instead.
latitude - geographical latitude in decimal degrees (-90.0 <= x <= +90.0)longitude - geographical longitude in decimal degrees (-180.0 <= x < 180.0)altitude - geographical altitude relative to sea level in meters (0 <= x < 11,0000)calculator - name of solar time calculatorjava.lang.IllegalArgumentException - if the coordinates are out of range or the calculator is unknownSolarTime.Calculator.name()public static SolarTime ofLocation(double latitude, double longitude, int altitude, SolarTime.Calculator calculator)
Obtains the solar time for given geographical location.
This method handles the geographical location in decimal degrees only. If these data are given
in degrees, arc minutes and arc seconds then users should apply the builder
approach instead.
latitude - geographical latitude in decimal degrees (-90.0 <= x <= +90.0)longitude - geographical longitude in decimal degrees (-180.0 <= x < 180.0)altitude - geographical altitude relative to sea level in meters (0 <= x < 11,0000)calculator - instance of solar time calculatorjava.lang.IllegalArgumentException - if the coordinates are out of rangepublic static SolarTime ofJerusalem()
Obtains an instance of solar time for the temple area in Jerusalem which has a prominent meaning in Hebrew calendar and time.
public static SolarTime ofMecca()
Obtains an instance of solar time for the Kaaba in Mecca which has a prominent meaning in islamic calendar.
The start of day in Mecca can be obtained by the expression
StartOfDay.definedBy(SolarTime.ofMecca().sunset()).
StartOfDay.definedBy(ChronoFunction)public double getLatitude()
GeoLocationObtains the geographical latitude of this instance.
getLatitude in interface GeoLocation-90.0 <= x <= +90.0)public double getLongitude()
GeoLocationObtains the geographical longitude of this instance.
getLongitude in interface GeoLocation-180.0 <= x < 180.0)public int getAltitude()
GeoLocationObtains the geographical altitude of this instance relative to sea level.
getAltitude in interface GeoLocation0 <= x < 11,0000)public SolarTime.Calculator getCalculator()
Obtains the name of the underlying calculator.
public ChronoFunction<CalendarDate,Moment> sunrise()
Calculates the moment of sunrise at the location of this instance.
Example:
SolarTime hamburg = SolarTime.ofLocation(53.55, 10.0);
Optional<Moment> result = PlainDate.nowInSystemTime().get(hamburg.sunrise());
System.out.println(result.get().toZonalTimestamp(() -> "Europe/Berlin"));
Note: The precision is generally constrained to minutes.
public ChronoFunction<CalendarDate,Moment> sunrise(Twilight twilight)
Calculates the time of given twilight at sunrise and the location of this instance.
Note: The precision is generally constrained to minutes. And the atmospheric refraction is here not taken into account.
twilight - relevant definition of twilight@Deprecated public ChronoFunction<CalendarDate,PlainTime> sunrise(TZID tzid)
sunrise() instead.Calculates the local time of sunrise at the location of this instance in given timezone.
Note: The precision is generally constrained to minutes. It is possible in some rare edge cases that the calculated clock time is related to the previous day.
tzid - the identifier of the timezone the local time of the result refers tosunrise()public ChronoFunction<CalendarDate,Moment> sunset()
Calculates the moment of sunset at the location of this instance.
Example:
SolarTime hamburg = SolarTime.ofLocation(53.55, 10.0);
Optional<Moment> result = PlainDate.nowInSystemTime().get(hamburg.sunset());
System.out.println(result.get().toZonalTimestamp(() -> "Europe/Berlin"));
Note: The precision is generally constrained to minutes.
public ChronoFunction<CalendarDate,Moment> sunset(Twilight twilight)
Calculates the time of given twilight at sunset and the location of this instance.
Note: The precision is generally constrained to minutes. And the atmospheric refraction is here not taken into account.
twilight - relevant definition of twilight@Deprecated public ChronoFunction<CalendarDate,PlainTime> sunset(TZID tzid)
sunset() instead.Calculates the local time of sunset at the location of this instance in given timezone.
Note: The precision is generally constrained to minutes. It is possible in some rare edge cases that the calculated clock time is related to the next day.
tzid - the identifier of the timezone the local time of the result refers tosunset()public ChronoFunction<CalendarDate,SolarTime.Sunshine> sunshine(TZID tzid)
Queries a given calendar date for its associated sunshine data.
The timezone parameter enables users to query for solar time data described in terms of a potentially quite different zone of the earth. However, the parameter does not interprete the input calendar date.
tzid - the identifier of the timezone any local times of the result refer topublic ChronoCondition<CalendarDate> polarNight()
Determines if the sun is invisible all day on a given calendar date.
public ChronoCondition<CalendarDate> midnightSun()
Determines if the sun is visible all day on a given calendar date.
public ChronoFunction<CalendarDate,Moment> transitAtNoon()
Calculates the moment of noon at the location of this instance (solar transit).
Note: The transit time does not tell if the sun is above or below the horizon.
@Deprecated public ChronoFunction<CalendarDate,PlainTime> transitAtNoon(TZID tzid)
transitAtNoon() instead.Calculates the local time of noon at the location of this instance in given timezone.
Note: The transit time does not tell if the sun is above or below the horizon.
tzid - the identifier of the timezone the local time of the result refers totransitAtNoon()public ChronoFunction<CalendarDate,Moment> transitAtMidnight()
Calculates the moment of midnight at the location of this instance (lowest position of sun).
Note: The transit time does not tell if the sun is above or below the horizon.
@Deprecated public ChronoFunction<CalendarDate,PlainTime> transitAtMidnight(TZID tzid)
transitAtMidnight() instead.Calculates the local time of midnight at the location of this instance in given timezone.
Note: The transit time does not tell if the sun is above or below the horizon.
tzid - the identifier of the timezone the local time of the result refers totransitAtMidnight()public boolean equals(java.lang.Object obj)
equals in class java.lang.Objectpublic int hashCode()
hashCode in class java.lang.Objectpublic java.lang.String toString()
toString in class java.lang.Objectpublic static ChronoFunction<Moment,PlainTimestamp> apparentAt(ZonalOffset offset)
Determines the apparent solar time of any moment at given local time zone offset.
Based on the astronomical equation of time. The default calculator is usually
StdSolarCalculator.NOAA unless another calculator was set up via the service loader mechnism.
offset - the time zone offset which might depend on the geographical longitudeZonalOffset.atLongitude(OffsetSign, int, int, double),
equationOfTime(Moment)public static ChronoFunction<Moment,PlainTimestamp> apparentAt(ZonalOffset offset, java.lang.String calculator)
Determines the apparent solar time of any moment at given local time zone offset.
Based on the astronomical equation of time.
offset - the time zone offset which might depend on the geographical longitudecalculator - name of solar time calculatorZonalOffset.atLongitude(OffsetSign, int, int, double),
equationOfTime(Moment, String)public static ChronoFunction<Moment,PlainTimestamp> onAverage(ZonalOffset offset)
Determines the mean solar time of any moment at given local time zone offset.
offset - the time zone offset which might depend on the geographical longitudeZonalOffset.atLongitude(OffsetSign, int, int, double)public static double equationOfTime(Moment moment)
Determines the difference between apparent and mean solar time at given moment.
See also Wikipedia. Relation: mean-solar-time + equation-of-time = apparent-solar-time
The default calculator is usually StdSolarCalculator.NOAA unless another calculator was
set up via the service loader mechnism.
moment - the moment when to determine the equation of timejava.lang.IllegalArgumentException - if the moment is out of year range -2000/+3000public static double equationOfTime(Moment moment, java.lang.String calculator)
Determines the difference between apparent and mean solar time at given moment.
See also Wikipedia.
Relation: mean-solar-time + equation-of-time = apparent-solar-time
moment - the moment when to determine the equation of timecalculator - name of solar time calculatorjava.lang.IllegalArgumentException - if the moment is out of year range -2000/+3000 or if the calculator is unknown