SolarTime (time4j-android 3.39-2018a API)

java.lang.Object
- net.time4j.calendar.astro.SolarTime

All Implemented Interfaces:: java.io.Serializable, GeoLocation

public final class SolarTime
extends java.lang.Object
implements GeoLocation, java.io.Serializable

Contains various routines to determine solar time.

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

Since:: 3.33/4.28
See Also:: Serialized Form

Nested Class Summary

Nested Classes
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.

Method Summary

All Methods Static Methods Instance Methods Concrete Methods Deprecated Methods
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.

Methods inherited from class java.lang.Object
getClass, notify, notifyAll, wait, wait, wait

- Method Detail
  - ofLocation
```
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.
    
    Returns:
    
    builder for creating a new instance of local solar time
    
    Since:
    
    3.35/4.30
  - ofLocation
```
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.
    
    Parameters:
    
    latitude - geographical latitude in decimal degrees (-90.0 <= x <= +90.0)
    
    longitude - geographical longitude in decimal degrees (-180.0 <= x < 180.0)
    
    Returns:
    
    instance of local solar time
    
    Throws:
    
    java.lang.IllegalArgumentException - if the coordinates are out of range
    
    Since:
    
    3.34/4.29
    
    See Also:
    
    ofLocation(double, double, int, String)
  - ofLocation
```
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.
    
    Parameters:
    
    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 calculator
    
    Returns:
    
    instance of local solar time
    
    Throws:
    
    java.lang.IllegalArgumentException - if the coordinates are out of range or the calculator is unknown
    
    Since:
    
    3.34/4.29
    
    See Also:
    
    SolarTime.Calculator.name()
  - ofLocation
```
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.
    
    Parameters:
    
    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 calculator
    
    Returns:
    
    instance of local solar time
    
    Throws:
    
    java.lang.IllegalArgumentException - if the coordinates are out of range
    
    Since:
    
    3.36/4.31
  - ofJerusalem
```
public 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.
    
    Returns:
    
    SolarTime
    
    Since:
    
    3.37/4.32
  - ofMecca
```
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()).
    
    Returns:
    
    SolarTime
    
    Since:
    
    3.37/4.32
    
    See Also:
    
    StartOfDay.definedBy(ChronoFunction)
  - getLatitude
```
public double getLatitude()
```
    Description copied from interface: GeoLocation
    
    Obtains the geographical latitude of this instance.
    
    Specified by:
    
    getLatitude in interface GeoLocation
    
    Returns:
    
    latitude in decimal degrees (-90.0 <= x <= +90.0)
  - getLongitude
```
public double getLongitude()
```
    Description copied from interface: GeoLocation
    
    Obtains the geographical longitude of this instance.
    
    Specified by:
    
    getLongitude in interface GeoLocation
    
    Returns:
    
    longitude in decimal degrees (-180.0 <= x < 180.0)
  - getAltitude
```
public int getAltitude()
```
    Description copied from interface: GeoLocation
    
    Obtains the geographical altitude of this instance relative to sea level.
    
    Specified by:
    
    getAltitude in interface GeoLocation
    
    Returns:
    
    altitude in meters (0 <= x < 11,0000)
  - getCalculator
```
public SolarTime.Calculator getCalculator()
```
    Obtains the name of the underlying calculator.
    
    Returns:
    
    String
    
    Since:
    
    3.34/4.29
  - sunrise
```
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.
    Returns:
    
    sunrise function applicable on any calendar date
    
    Since:
    
    3.34/4.29
  - sunrise
```
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.
    
    Parameters:
    
    twilight - relevant definition of twilight
    
    Returns:
    
    twilight function at sunrise applicable on any calendar date
    
    Since:
    
    3.34/4.29
  - sunrise
```
@Deprecated
public ChronoFunction<CalendarDate,PlainTime> sunrise(TZID tzid)
```
    Deprecated. This method looses the day information so users are asked to use 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.
    
    Parameters:
    
    tzid - the identifier of the timezone the local time of the result refers to
    
    Returns:
    
    sunrise function applicable on any calendar date
    
    Since:
    
    3.34/4.29
    
    See Also:
    
    sunrise()
  - sunset
```
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.
    Returns:
    
    sunset function applicable on any calendar date
    
    Since:
    
    3.34/4.29
  - sunset
```
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.
    
    Parameters:
    
    twilight - relevant definition of twilight
    
    Returns:
    
    twilight function at sunset applicable on any calendar date
    
    Since:
    
    3.34/4.29
  - sunset
```
@Deprecated
public ChronoFunction<CalendarDate,PlainTime> sunset(TZID tzid)
```
    Deprecated. This method looses the day information so users are asked to use 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.
    
    Parameters:
    
    tzid - the identifier of the timezone the local time of the result refers to
    
    Returns:
    
    sunset function applicable on any calendar date
    
    Since:
    
    3.34/4.29
    
    See Also:
    
    sunset()
  - sunshine
```
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.
    
    Parameters:
    
    tzid - the identifier of the timezone any local times of the result refer to
    
    Returns:
    
    function for obtaining sunshine data
    
    Since:
    
    3.34/4.29
  - polarNight
```
public ChronoCondition<CalendarDate> polarNight()
```
    Determines if the sun is invisible all day on a given calendar date.
    
    Returns:
    
    ChronoCondition
    
    Since:
    
    3.34/4.29
  - midnightSun
```
public ChronoCondition<CalendarDate> midnightSun()
```
    Determines if the sun is visible all day on a given calendar date.
    
    Returns:
    
    ChronoCondition
    
    Since:
    
    3.34/4.29
  - transitAtNoon
```
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.
    
    Returns:
    
    noon function applicable on any calendar date
    
    Since:
    
    3.34/4.29
  - transitAtNoon
```
@Deprecated
public ChronoFunction<CalendarDate,PlainTime> transitAtNoon(TZID tzid)
```
    Deprecated. This method looses the day information so users are asked to use 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.
    
    Parameters:
    
    tzid - the identifier of the timezone the local time of the result refers to
    
    Returns:
    
    noon function applicable on any calendar date
    
    Since:
    
    3.34/4.29
    
    See Also:
    
    transitAtNoon()
  - transitAtMidnight
```
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.
    
    Returns:
    
    midnight function applicable on any calendar date
    
    Since:
    
    3.34/4.29
  - transitAtMidnight
```
@Deprecated
public ChronoFunction<CalendarDate,PlainTime> transitAtMidnight(TZID tzid)
```
    Deprecated. This method looses the day information so users ought to use 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.
    
    Parameters:
    
    tzid - the identifier of the timezone the local time of the result refers to
    
    Returns:
    
    midnight function applicable on any calendar date
    
    Since:
    
    3.34/4.29
    
    See Also:
    
    transitAtMidnight()
  - equals
```
public boolean equals(java.lang.Object obj)
```
    Overrides:
    
    equals in class java.lang.Object
  - hashCode
```
public int hashCode()
```
    Overrides:
    
    hashCode in class java.lang.Object
  - toString
```
public java.lang.String toString()
```
    Overrides:
    
    toString in class java.lang.Object
  - apparentAt
```
public 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.
    
    Parameters:
    
    offset - the time zone offset which might depend on the geographical longitude
    
    Returns:
    
    function for getting the apparent solar time
    
    See Also:
    
    ZonalOffset.atLongitude(OffsetSign, int, int, double), equationOfTime(Moment)
  - apparentAt
```
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.
    
    Parameters:
    
    offset - the time zone offset which might depend on the geographical longitude
    
    calculator - name of solar time calculator
    
    Returns:
    
    function for getting the apparent solar time
    
    Since:
    
    3.34/4.29
    
    See Also:
    
    ZonalOffset.atLongitude(OffsetSign, int, int, double), equationOfTime(Moment, String)
  - onAverage
```
public static ChronoFunction<Moment,PlainTimestamp> onAverage(ZonalOffset offset)
```
    Determines the mean solar time of any moment at given local time zone offset.
    
    Parameters:
    
    offset - the time zone offset which might depend on the geographical longitude
    
    Returns:
    
    function for getting the mean solar time
    
    See Also:
    
    ZonalOffset.atLongitude(OffsetSign, int, int, double)
  - equationOfTime
```
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.
    
    Parameters:
    
    moment - the moment when to determine the equation of time
    
    Returns:
    
    difference between apparent solar time and mean solar time in seconds
    
    Throws:
    
    java.lang.IllegalArgumentException - if the moment is out of year range -2000/+3000
  - equationOfTime
```
public 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
    
    Parameters:
    
    moment - the moment when to determine the equation of time
    
    calculator - name of solar time calculator
    
    Returns:
    
    difference between apparent solar time and mean solar time in seconds
    
    Throws:
    
    java.lang.IllegalArgumentException - if the moment is out of year range -2000/+3000 or if the calculator is unknown
    
    Since:
    
    3.34/4.29

Class SolarTime

Nested Class Summary

Method Summary

Methods inherited from class java.lang.Object

Method Detail

ofLocation

ofLocation

ofLocation

ofLocation

ofJerusalem

ofMecca

getLatitude

getLongitude

getAltitude

getCalculator

sunrise

sunrise

sunrise

sunset

sunset

sunset

sunshine

polarNight

midnightSun

transitAtNoon

transitAtNoon

transitAtMidnight

transitAtMidnight

equals

hashCode

toString

apparentAt

apparentAt

onAverage

equationOfTime

equationOfTime