KosherJava Zmanim Homepage
Includes a dynamic Zmanim calendar generator

net.sourceforge.zmanim
Class AstronomicalCalendar

java.lang.Object
  extended bynet.sourceforge.zmanim.AstronomicalCalendar
Direct Known Subclasses:
ZmanimCalendar

public class AstronomicalCalendar
extends Object

A Java calendar that calculates astronomical time calculations such as sunrise and sunset times. This class contains a Calendar and can therefore use the standard Calendar functionality to change dates etc. The calculation engine used to calculate the astronomical times can be changed to a different implementation by implementing the AstronomicalCalculator and setting it with the setAstronomicalCalculator(AstronomicalCalculator). A number of different implementations are included in the util package
Note: There are times when the algorithms can't calculate proper values for sunrise and sunset. This is usually caused by trying to calculate times for areas either very far North or South, where sunrise / sunset never happen on that date. This is common when calculating twilight with a deep dip below the horizon for locations as south as London in the northern hemisphere. When the calculations encounter this condition a null will be returned when a Date is expected and Double.NaN will be returned when a double is expected. The reason that Exceptions are not thrown in these cases is due to the fact that such problems are expected and will often be encountered when a calendar for a full year is being generated.

Version:
1.1
Author:
© Eliyahu Hershfeld 2004 - 2007

Field Summary
static double ASTRONOMICAL_ZENITH
          Sun's zenith at astronomical twilight (108°).
static double CIVIL_ZENITH
          Sun's zenith at civil twilight (96°).
static double GEOMETRIC_ZENITH
          90° below the vertical.
(package private) static long MINUTE_MILLIS
          constant for milliseconds in a minute (60,000)
static double NAUTICAL_ZENITH
          Sun's zenith at nautical twilight (102°).
 
Constructor Summary
AstronomicalCalendar()
          Default constructor will set a default GeoLocation, use the default (AstronomicalCalculator.getDefault()) AstronomicalCalculator and default the calendar to the current time.
AstronomicalCalendar(GeoLocation geoLocation)
          A constructor that takes in as a parameter geolocation information
 
Method Summary
 boolean equals(Object object)
           
 AstronomicalCalculator getAstronomicalCalculator()
          A method to return the current AstronomicalCalculator set.
 Date getBeginAstronomicalTwilight()
          A method that returns the the beginning of astronomical twilight using a zenith of 108°.
 Date getBeginCivilTwilight()
          A method to return the the beginning of civil twilight (dawn) using a zenith of 96°.
 Date getBeginNauticalTwilight()
          A method to return the the beginning of nautical twilight using a zenith of 102°.
 Calendar getCalendar()
          returns the Calendar object encapsulated by this class.
 Date getEndAstronomicalTwilight()
          A method to return the the end of astronomical twilight using a zenith of 108°.
 Date getEndCivilTwilight()
          A method to return the the end of civil twilight using a zenith of 96°.
 Date getEndNauticalTwilight()
          A method to return the the end of nautical twilight using a zenith of 102°.
 GeoLocation getGeoLocation()
           
 Date getSeaLevelSunrise()
          Method that returns the sunrise without correction for elevation.
 Date getSeaLevelSunset()
          Method that returns the sunset without correction for elevation.
 Date getSunrise()
          The getSunrise method Returns a Date representing the sunrise time.
 Date getSunriseOffsetByDegrees(double offsetZenith)
          A utility method to return the time of an offset by degrees below or above the horizon of sunrise.
 Date getSunset()
          The getSunset method Returns a Date representing the sunset time.
 Date getSunsetOffsetByDegrees(double offsetZenith)
          A utility method to return the time of an offset by degrees below or above the horizon of sunset.
 Date getSunTransit()
          method that returns sundial noon.
 long getTemporalHour()
          Method to return a temporal (solar) hour.
 long getTemporalHour(Date sunrise, Date sunset)
          Utility method that will allow the calculation of a temporal (solar) hour based on the sunrise and sunset passed to this method.
 Date getTimeOffset(Date time, double offset)
          Utility method that returns a time offset.
 Date getTimeOffset(Date time, long offset)
          A utility method to return a time offset.
 double getUTCSeaLevelSunrise(double zenith)
          Method that returns the sunrise in UTC time without correction for time zone offset from GMT and without using daylight savings time.
 double getUTCSeaLevelSunset(double zenith)
          Method that returns the sunset in UTC time without correction for elevation, time zone offset from GMT and without using daylight savings time.
 double getUTCSunrise(double zenith)
          Method that returns the sunrise in UTC time without correction for time zone offset from GMT and without using daylight savings time.
 double getUTCSunset(double zenith)
          Method that returns the sunset in UTC time without correction for time zone offset from GMT and without using daylight savings time.
 int hashCode()
           
static void main(String[] args)
           
 void setAstronomicalCalculator(AstronomicalCalculator astronomicalCalculator)
          A method to set the AstronomicalCalculator used for astronomical calculations.
 void setCalendar(Calendar calendar)
           
 void setGeoLocation(GeoLocation geoLocation)
           
 String toString()
           
 String toXML()
          A method that returns an XML formatted String representing the serialized Object.
 String toXML2()
           
 
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait
 

Field Detail

GEOMETRIC_ZENITH

public static final double GEOMETRIC_ZENITH
90° below the vertical. Used for certain calculations.
Note : it is important to note the distinction between this zenith and the adjusted zenith used for some solar calculations. This 90 zenith is only used because some calculations in some subclasses are historically calculated as an offset in reference to 90.

See Also:
Constant Field Values

CIVIL_ZENITH

public static final double CIVIL_ZENITH
Sun's zenith at civil twilight (96°).

See Also:
Constant Field Values

NAUTICAL_ZENITH

public static final double NAUTICAL_ZENITH
Sun's zenith at nautical twilight (102°).

See Also:
Constant Field Values

ASTRONOMICAL_ZENITH

public static final double ASTRONOMICAL_ZENITH
Sun's zenith at astronomical twilight (108°).

See Also:
Constant Field Values

MINUTE_MILLIS

static final long MINUTE_MILLIS
constant for milliseconds in a minute (60,000)

See Also:
Constant Field Values
Constructor Detail

AstronomicalCalendar

public AstronomicalCalendar()
Default constructor will set a default GeoLocation, use the default (AstronomicalCalculator.getDefault()) AstronomicalCalculator and default the calendar to the current time.


AstronomicalCalendar

public AstronomicalCalendar(GeoLocation geoLocation)
A constructor that takes in as a parameter geolocation information

Parameters:
geoLocation - The location information used for astronomical calculating sun times.
Method Detail

getSunrise

public Date getSunrise()
The getSunrise method Returns a Date representing the sunrise time. The zenith used for the calculation uses geometric zenith of 90°. This is adjusted by the AstronomicalCalculator that adds approximately 50/60 of a degree to account for 34 archminutes of refraction and 16 archminutes for the sun's radius for a total of 90.83333°. See documentation for the specific implementation of the AstronomicalCalculator that you are using.

Returns:
the Date representing the exact sunrise time. If the calculation can not be computed null will be returned.
See Also:
AstronomicalCalculator.adjustZenith(double, double)

getSeaLevelSunrise

public Date getSeaLevelSunrise()
Method that returns the sunrise without correction for elevation. Non-sunrise and sunset calculations such as dawn and dusk, depend on the amount of visible light, something that is not affected by elevation. This method returns sunrise calculated at sea level. This forms the base for dawn calculations that are calculated as a dip below the horizon before sunrise.

Returns:
the Date representing the exact sea-level sunrise time. If the calculation can not be computed null will be returned.
See Also:
getSunrise(), getUTCSeaLevelSunrise(double)

getBeginCivilTwilight

public Date getBeginCivilTwilight()
A method to return the the beginning of civil twilight (dawn) using a zenith of 96°.

Returns:
The Date of the beginning of civil twilight using a zenith of 96°. If the calculation can not be computed null will be returned.
See Also:
CIVIL_ZENITH

getBeginNauticalTwilight

public Date getBeginNauticalTwilight()
A method to return the the beginning of nautical twilight using a zenith of 102°.

Returns:
The Date of the beginning of nautical twilight using a zenith of 102°. If the calculation can not be computed null will be returned.
See Also:
NAUTICAL_ZENITH

getBeginAstronomicalTwilight

public Date getBeginAstronomicalTwilight()
A method that returns the the beginning of astronomical twilight using a zenith of 108°.

Returns:
The Date of the beginning of astronomical twilight using a zenith of 108°. If the calculation can not be computed null will be returned.
See Also:
ASTRONOMICAL_ZENITH

getSunset

public Date getSunset()
The getSunset method Returns a Date representing the sunset time. The zenith used for the calculation uses geometric zenith of 90°. This is adjusted by the AstronomicalCalculator that adds approximately 50/60 of a degree to account for 34 archminutes of refraction and 16 archminutes for the sun's radius for a total of 90.83333°. See documentation for the specific implementation of the AstronomicalCalculator that you are using. Note: In certain cases the calculates sunset will occur before sunrise. This will typically happen when a timezone other than the local timezone is used (calculating Los Angeles sunset using a GMT timezone for example). In this case the sunset date will be incremented to the following date.

Returns:
the Date representing the exact sunset time. If the calculation can not be computed null will be returned. If the time calculation
See Also:
AstronomicalCalculator.adjustZenith(double, double)

getSeaLevelSunset

public Date getSeaLevelSunset()
Method that returns the sunset without correction for elevation. Non-sunrise and sunset calculations such as dawn and dusk, depend on the amount of visible light, something that is not affected by elevation. This method returns sunset calculated at sea level. This forms the base for dusk calculations that are calculated as a dip below the horizon after sunset.

Returns:
the Date representing the exact sea-level sunset time. If the calculation can not be computed null will be returned.
See Also:
getSunset(), getUTCSeaLevelSunset(double)

getEndCivilTwilight

public Date getEndCivilTwilight()
A method to return the the end of civil twilight using a zenith of 96°.

Returns:
The Date of the end of civil twilight using a zenith of 96°. If the calculation can not be computed null will be returned.
See Also:
CIVIL_ZENITH

getEndNauticalTwilight

public Date getEndNauticalTwilight()
A method to return the the end of nautical twilight using a zenith of 102°.

Returns:
The Date of the end of nautical twilight using a zenith of 102°. If the calculation can not be computed null will be returned.
See Also:
NAUTICAL_ZENITH

getEndAstronomicalTwilight

public Date getEndAstronomicalTwilight()
A method to return the the end of astronomical twilight using a zenith of 108°.

Returns:
The The Date of the end of astronomical twilight using a zenith of 108°. If the calculation can not be computed null will be returned.
See Also:
ASTRONOMICAL_ZENITH

getTimeOffset

public Date getTimeOffset(Date time,
                          double offset)
Utility method that returns a time offset. This method casts the offset as a long and calls getTimeOffset(Date, long).

Parameters:
time - the start time
offset - the offset in milliseconds to add to the time
Returns:
the Datewith the offset added to it

getTimeOffset

public Date getTimeOffset(Date time,
                          long offset)
A utility method to return a time offset.

Parameters:
time - the start time
offset - the offset in milliseconds to add to the time.
Returns:
the Date with the offset in milliseconds added to it

getSunriseOffsetByDegrees

public Date getSunriseOffsetByDegrees(double offsetZenith)
A utility method to return the time of an offset by degrees below or above the horizon of sunrise.

Parameters:
offsetZenith - the degrees before getSunrise() to use in the calculation. For time after sunrise use negative numbers.
Returns:
The Date of the offset after (or before) getSunrise(). If the calculation can not be computed null will be returned.

getSunsetOffsetByDegrees

public Date getSunsetOffsetByDegrees(double offsetZenith)
A utility method to return the time of an offset by degrees below or above the horizon of sunset.

Parameters:
offsetZenith - the degrees after getSunset() to use in the calculation. For time before sunset use negative numbers.
Returns:
The Dateof the offset after (or before) getSunset(). If the calculation can not be computed null will be returned.

getUTCSunrise

public double getUTCSunrise(double zenith)
Method that returns the sunrise in UTC time without correction for time zone offset from GMT and without using daylight savings time.

Parameters:
zenith - the degrees below the horizon. For time after sunrise use negative numbers.
Returns:
The time in the format: 18.75 for 18:45:00 UTC/GMT. If the calculation can not be computed Double.NaN will be returned.

getUTCSeaLevelSunrise

public double getUTCSeaLevelSunrise(double zenith)
Method that returns the sunrise in UTC time without correction for time zone offset from GMT and without using daylight savings time. Non-sunrise and sunset calculations such as dawn and dusk, depend on the amount of visible light, something that is not affected by elevation. This method returns UTC sunrise calculated at sea level. This forms the base for dawn calculations that are calculated as a dip below the horizon before sunrise.

Parameters:
zenith - the degrees below the horizon. For time after sunrise use negative numbers.
Returns:
The time in the format: 18.75 for 18:45:00 UTC/GMT. If the calculation can not be computed Double.NaN will be returned.
See Also:
getUTCSunrise(double), getUTCSeaLevelSunset(double)

getUTCSunset

public double getUTCSunset(double zenith)
Method that returns the sunset in UTC time without correction for time zone offset from GMT and without using daylight savings time.

Parameters:
zenith - the degrees below the horizon. For time after before sunset use negative numbers.
Returns:
The time in the format: 18.75 for 18:45:00 UTC/GMT. If the calculation can not be computed Double.NaN will be returned.
See Also:
getUTCSeaLevelSunset(double)

getUTCSeaLevelSunset

public double getUTCSeaLevelSunset(double zenith)
Method that returns the sunset in UTC time without correction for elevation, time zone offset from GMT and without using daylight savings time. Non-sunrise and sunset calculations such as dawn and dusk, depend on the amount of visible light, something that is not affected by elevation. This method returns UTC sunset calculated at sea level. This forms the base for dusk calculations that are calculated as a dip below the horizon after sunset.

Parameters:
zenith - the degrees below the horizon. For time before sunset use negative numbers.
Returns:
The time in the format: 18.75 for 18:45:00 UTC/GMT. If the calculation can not be computed Double.NaN will be returned.
See Also:
getUTCSunset(double), getUTCSeaLevelSunrise(double)

getTemporalHour

public long getTemporalHour()
Method to return a temporal (solar) hour. The day from sunrise to sunset is split into 12 equal parts with each one being a temporal hour.

Returns:
the long millisecond length of a temporal hour. If the calculation can not be computed Long.MIN_VALUE will be returned.

getTemporalHour

public long getTemporalHour(Date sunrise,
                            Date sunset)
Utility method that will allow the calculation of a temporal (solar) hour based on the sunrise and sunset passed to this method.

Parameters:
sunrise - The start of the day.
sunset - The end of the day.
Returns:
the long millisecond length of the temporal hour. If the calculation can not be computed Long.MIN_VALUE will be returned.
See Also:
getTemporalHour()

getSunTransit

public Date getSunTransit()
method that returns sundial noon. This is calculated as halfway between sunrise and sunset.

Returns:
the Date representing Sun's transit. If the calculation can not be computed null will be returned.

toString

public String toString()
Returns:
an XML formatted representation of the class. It returns the default output of the toXML method.
See Also:
toXML(), Object.toString()

equals

public boolean equals(Object object)
See Also:
Object.equals(Object)

hashCode

public int hashCode()
See Also:
Object.hashCode()

getGeoLocation

public GeoLocation getGeoLocation()
Returns:
Returns the geoLocation.

setGeoLocation

public void setGeoLocation(GeoLocation geoLocation)
Parameters:
geoLocation - The geoLocation to set.

getAstronomicalCalculator

public AstronomicalCalculator getAstronomicalCalculator()
A method to return the current AstronomicalCalculator set.

Returns:
Returns the astronimicalCalculator.
See Also:
setAstronomicalCalculator(AstronomicalCalculator)

setAstronomicalCalculator

public void setAstronomicalCalculator(AstronomicalCalculator astronomicalCalculator)
A method to set the AstronomicalCalculator used for astronomical calculations. The Zmanim package ships with a number of different implementations of the abstract AstronomicalCalculator based on different algorithms, including one implementation based on the US Naval Observatory's algorithm, and another based on NOAA's algorithm. This allows easy runtime switching and comparison of different algorithms.

Parameters:
astronomicalCalculator - The astronimicalCalculator to set.

getCalendar

public Calendar getCalendar()
returns the Calendar object encapsulated by this class.

Returns:
Returns the calendar.

setCalendar

public void setCalendar(Calendar calendar)
Parameters:
calendar - The calendar to set.

toXML

public String toXML()
A method that returns an XML formatted String representing the serialized Object. The format used is:
  <AstronomicalTimes date="1969-02-08" type="net.sourceforge.zmanim.AstronomicalCalendar algorithm="US Naval Almanac Algorithm" location="Lakewood, NJ" latitude="40.095965" longitude="-74.22213" elevation="31.0" timeZoneName="Eastern Standard Time" timeZoneID="America/New_York" timeZoneOffset="-5">
     <Sunrise>2007-02-18T06:45:27-05:00</Sunrise>
     <TemporalHour>PT54M17.529S</TemporalHour>
     ...
   </AstronomicalTimes>   
 
Note that the output uses the xsd:dateTime format for times such as sunrise, and xsd:duration format for times that are a duration such as the length of a temporal hour. The output of this method is returned by the toString }.

Returns:
The XML formatted String. The format will be:
  <AstronomicalTimes date="1969-02-08" type="net.sourceforge.zmanim.AstronomicalCalendar algorithm="US Naval Almanac Algorithm" location="Lakewood, NJ" latitude="40.095965" longitude="-74.22213" elevation="31.0" timeZoneName="Eastern Standard Time" timeZoneID="America/New_York" timeZoneOffset="-5">
     <Sunrise>2007-02-18T06:45:27-05:00</Sunrise>
     <TemporalHour>PT54M17.529S</TemporalHour>
     ...
  </AstronomicalTimes>   
 

toXML2

public String toXML2()

main

public static void main(String[] args)

KosherJava Zmanim Homepage
Includes a dynamic Zmanim calendar generator

Copyright © 2004 - 2007 Eliyahu Hershfeld. All Rights Reserved.