|
KosherJava Zmanim Homepage | |||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Objectnet.sourceforge.zmanim.AstronomicalCalendar
public class AstronomicalCalendar
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, sunset and twilight. 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 far south of the North
Pole as London, in the northern hemisphere. The sun never reaches this dip at
certain times of the year. When the calculations encounter this condition a
null will be returned when a
is expected
and Date
Long.MIN_VALUE
when a long is expected. The reason that
Exception
s are not thrown in these cases is because the lack of
a rise/set or twilight is not an exception, but expected in many parts of the
world.
Here is a simple example of how to use the API to calculate sunrise:
First create the Calendar for the location you would like to calculate:
String locationName = "Lakewood, NJ";
double latitude = 40.0828; // Lakewood, NJ
double longitude = -74.2094; // Lakewood, NJ
double elevation = 20; // optional elevation correction in Meters
// the String parameter in getTimeZone() has to be a valid timezone listed in
// TimeZone.getAvailableIDs()
TimeZone timeZone = TimeZone.getTimeZone("America/New_York");
GeoLocation location = new GeoLocation(locationName, latitude, longitude,
elevation, timeZone);
AstronomicalCalendar ac = new AstronomicalCalendar(location);
To get the time of sunrise, first set the date (if not set, the date will
default to today):
ac.getCalendar().set(Calendar.MONTH, Calendar.FEBRUARY); ac.getCalendar().set(Calendar.DAY_OF_MONTH, 8); Date sunrise = ac.getSunrise();
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 |
HOUR_MILLIS
constant for milliseconds in an hour (3,600,000) |
(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.GeoLocation() ,
a default AstronomicalCalculator and default the calendar to the current date. |
|
AstronomicalCalendar(GeoLocation geoLocation)
A constructor that takes in as a parameter geolocation information |
Method Summary | |
---|---|
Object |
clone()
A method that creates a deep copy of the object. |
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 in this class. |
protected Date |
getDateFromTime(double time)
A method that returns a Date from the time passed in |
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()
A method that returns the currently set GeoLocation that contains
location information used for the astronomical calculations. |
Date |
getSeaLevelSunrise()
Method that returns the sunrise without elevation
adjustment . |
Date |
getSeaLevelSunset()
Method that returns the sunset without elevation
adjustment . |
Date |
getSunrise()
The getSunrise method Returns a Date representing the
elevation
adjusted 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 . |
double |
getSunriseSolarDipFromOffset(double minutes)
Will return the dip below the horizon before sunrise that matches the offset minutes on passed in. |
Date |
getSunset()
The getSunset method Returns a Date representing the
elevation
adjusted 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 . |
double |
getSunsetSolarDipFromOffset(double minutes)
Will return the dip below the horizon after sunset that matches the offset minutes on passed in. |
Date |
getSunTransit()
A method that returns sundial or solar noon. |
long |
getTemporalHour()
Method to return an elevation
adjusted 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 date offset by the offset time passed in. |
Date |
getTimeOffset(Date time,
long offset)
A utility method to return a date offset by the offset time passed in. |
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()
|
void |
setAstronomicalCalculator(AstronomicalCalculator astronomicalCalculator)
A method to set the AstronomicalCalculator used for astronomical
calculations. |
void |
setCalendar(Calendar calendar)
|
void |
setGeoLocation(GeoLocation geoLocation)
Set the GeoLocation to be used for astronomical calculations. |
String |
toString()
|
Methods inherited from class java.lang.Object |
---|
finalize, getClass, notify, notifyAll, wait, wait, wait |
Field Detail |
---|
public static final double GEOMETRIC_ZENITH
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.
public static final double CIVIL_ZENITH
public static final double NAUTICAL_ZENITH
public static final double ASTRONOMICAL_ZENITH
static final long MINUTE_MILLIS
static final long HOUR_MILLIS
Constructor Detail |
---|
public AstronomicalCalendar()
GeoLocation.GeoLocation()
,
a default AstronomicalCalculator
and default the calendar to the current date.
public AstronomicalCalendar(GeoLocation geoLocation)
geoLocation
- The location information used for astronomical calculating sun
times.Method Detail |
---|
public Date getSunrise()
Date
representing the
elevation
adjusted
sunrise time. The zenith used for the calculation uses
geometric zenith
of 90° plus
AstronomicalCalculator.getElevationAdjustment(double)
. This is
adjusted by the AstronomicalCalculator
to add 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.
Date
representing the exact sunrise time. If the
calculation can't be computed such as in the Arctic Circle where
there is at least one day a year where the sun does not rise, and
one where it does not set, a null will be returned. See detailed
explanation on top of the page.AstronomicalCalculator.adjustZenith(double, double)
,
getSeaLevelSunrise()
,
getUTCSunrise(double)
public Date getSeaLevelSunrise()
elevation
adjustment
. 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.
Date
representing the exact sea-level sunrise
time. If the calculation can't be computed such as in the Arctic
Circle where there is at least one day a year where the sun does
not rise, and one where it does not set, a null will be returned.
See detailed explanation on top of the page.getSunrise()
,
getUTCSeaLevelSunrise(double)
,
getSeaLevelSunset()
public Date getBeginCivilTwilight()
96°
.
Date
of the beginning of civil twilight using a
zenith of 96°. If the calculation can't be computed (see
explanation on top of the page), null will be returned.CIVIL_ZENITH
public Date getBeginNauticalTwilight()
102°
.
Date
of the beginning of nautical twilight using
a zenith of 102°. If the calculation can't be computed (see
explanation on top of the page) null will be returned.NAUTICAL_ZENITH
public Date getBeginAstronomicalTwilight()
108°
.
Date
of the beginning of astronomical twilight
using a zenith of 108°. If the calculation can't be computed
(see explanation on top of the page), null will be returned.ASTRONOMICAL_ZENITH
public Date getSunset()
Date
representing the
elevation
adjusted
sunset time. The zenith used for the calculation uses
geometric zenith
of 90° plus
AstronomicalCalculator.getElevationAdjustment(double)
. This is
adjusted by the AstronomicalCalculator
to add 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.
Date
representing the exact sunset time. If the
calculation can't be computed such as in the Arctic Circle where
there is at least one day a year where the sun does not rise, and
one where it does not set, a null will be returned. See detailed
explanation on top of the page.AstronomicalCalculator.adjustZenith(double, double)
,
getSeaLevelSunset()
,
getUTCSunset(double)
public Date getSeaLevelSunset()
elevation
adjustment
. 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.
Date
representing the exact sea-level sunset
time. If the calculation can't be computed such as in the Arctic
Circle where there is at least one day a year where the sun does
not rise, and one where it does not set, a null will be returned.
See detailed explanation on top of the page.getSunset()
,
2see {@link #getSunset()}
public Date getEndCivilTwilight()
96°
.
Date
of the end of civil twilight using a zenith
of 96°
. If the calculation can't be
computed (see explanation on top of the page), null will be
returned.CIVIL_ZENITH
public Date getEndNauticalTwilight()
102°
.
Date
of the end of nautical twilight using a
zenith of 102°
. If the calculation
can't be computed (see explanation on top of the page), null will
be returned.NAUTICAL_ZENITH
public Date getEndAstronomicalTwilight()
108°
.
Date
of the end of astronomical twilight
using a zenith of 108°
. If the
calculation can't be computed (see explanation on top of the
page), null will be returned.ASTRONOMICAL_ZENITH
public Date getTimeOffset(Date time, double offset)
long
and calls
getTimeOffset(Date, long)
.
time
- the start timeoffset
- the offset in milliseconds to add to the time
Date
with the offset added to itpublic Date getTimeOffset(Date time, long offset)
time
- the start timeoffset
- the offset in milliseconds to add to the time.
Date
with the offset in milliseconds added
to itpublic Date getSunriseOffsetByDegrees(double offsetZenith)
sunrise
.
offsetZenith
- the degrees before getSunrise()
to use in the
calculation. For time after sunrise use negative numbers.
Date
of the offset after (or before)
getSunrise()
. If the calculation can't be computed such
as in the Arctic Circle where there is at least one day a year
where the sun does not rise, and one where it does not set, a
null will be returned. See detailed explanation on top of the
page.public Date getSunsetOffsetByDegrees(double offsetZenith)
sunset
.
offsetZenith
- the degrees after getSunset()
to use in the
calculation. For time before sunset use negative numbers.
Date
of the offset after (or before)
getSunset()
. If the calculation can't be computed such
as in the Arctic Circle where there is at least one day a year
where the sun does not rise, and one where it does not set, a
null will be returned. See detailed explanation on top of the
page.public double getUTCSunrise(double zenith)
zenith
- the degrees below the horizon. For time after sunrise use
negative numbers.
Double.NaN
will be returned.public double getUTCSeaLevelSunrise(double zenith)
zenith
- the degrees below the horizon. For time after sunrise use
negative numbers.
Double.NaN
will be returned.
See detailed explanation on top of the page.getUTCSunrise(double)
,
getUTCSeaLevelSunset(double)
public double getUTCSunset(double zenith)
zenith
- the degrees below the horizon. For time after before sunset
use negative numbers.
Double.NaN
will be returned.
See detailed explanation on top of the page.getUTCSeaLevelSunset(double)
public double getUTCSeaLevelSunset(double zenith)
zenith
- the degrees below the horizon. For time before sunset use
negative numbers.
Double.NaN
will be returned.
See detailed explanation on top of the page.getUTCSunset(double)
,
getUTCSeaLevelSunrise(double)
public long getTemporalHour()
elevation
adjusted
temporal (solar) hour. The day from sunrise
to sunset
is split into 12 equal parts with
each one being a temporal hour.
long
millisecond length of a temporal hour. If
the calculation can't be computed (see explanation on top of the
page), Long.MIN_VALUE
will be returned.getSunrise()
,
getSunset()
,
getTemporalHour(Date, Date)
public long getTemporalHour(Date sunrise, Date sunset)
sea level
sunrise
and sea level sunset
.
sunrise
- The start of the day.sunset
- The end of the day.
long
millisecond length of the temporal hour. If
the calculation can't be computed (see explanation on top of the
page) Long.MIN_VALUE
will be returned.getTemporalHour()
public Date getSunTransit()
Date
representing Sun's transit. If the
calculation can't be computed such as in the Arctic Circle where
there is at least one day a year where the sun does not rise, and
one where it does not set, null will be returned.protected Date getDateFromTime(double time)
Date
from the time passed in
time
- The time to be set as the time for the Date
. The
time expected is in the format: 18.75 for 6:45:00 PM
public double getSunriseSolarDipFromOffset(double minutes)
minutes
- offset
getSunsetSolarDipFromOffset(double)
public double getSunsetSolarDipFromOffset(double minutes)
minutes
- offset
getSunriseSolarDipFromOffset(double)
public String toString()
toString
in class Object
toXML
method.ZmanimFormatter.toXML(AstronomicalCalendar)
,
Object.toString()
public boolean equals(Object object)
equals
in class Object
Object.equals(Object)
public int hashCode()
hashCode
in class Object
Object.hashCode()
public GeoLocation getGeoLocation()
GeoLocation
that contains
location information used for the astronomical calculations.
public void setGeoLocation(GeoLocation geoLocation)
GeoLocation
to be used for astronomical calculations.
geoLocation
- The geoLocation to set.public AstronomicalCalculator getAstronomicalCalculator()
setAstronomicalCalculator(AstronomicalCalculator)
public void setAstronomicalCalculator(AstronomicalCalculator astronomicalCalculator)
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.
astronomicalCalculator
- The astronimicalCalculator to set.public Calendar getCalendar()
public void setCalendar(Calendar calendar)
calendar
- The calendar to set.public Object clone()
TimeZone
in the cloned
GeoLocation
will be changed from the
original, it is critical that
getCalendar()
.
setTimeZone(TimeZone)
be
called in order for the AstronomicalCalendar to output times in the
expected offset after being cloned.
clone
in class Object
Object.clone()
|
KosherJava Zmanim Homepage | |||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |