|
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 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 of the North Pole as London in the
northern hemisphere. When the calculations encounter this condition a null
will be returned when a
is expected and
Date
Double.NaN
when a double is expected. The reason that
Exception
s are not thrown in these cases is because the lack
of a rise/set are not exceptions, 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 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 . |
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
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 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 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
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.
Date
representing the exact sunrise time. If
the calculation can not be computed null will be returned.AstronomicalCalculator.adjustZenith(double, double)
public Date getSeaLevelSunrise()
Date
representing the exact sea-level sunrise
time. If the calculation can not be computed null will be
returned.getSunrise()
,
getUTCSeaLevelSunrise(double)
public Date getBeginCivilTwilight()
96°
.
Date
of the beginning of civil twilight using
a zenith of 96°. If the calculation can not be computed 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 not be
computed 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 not be
computed null will be returned.ASTRONOMICAL_ZENITH
public Date getSunset()
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.
Date
representing the exact sunset time. If
the calculation can not be computed null will be returned. If the
time calculationAstronomicalCalculator.adjustZenith(double, double)
public Date getSeaLevelSunset()
Date
representing the exact sea-level sunset
time. If the calculation can not be computed null will be
returned.getSunset()
,
getUTCSeaLevelSunset(double)
public Date getEndCivilTwilight()
96°
.
Date
of the end of civil twilight using a
zenith of 96°
. If the calculation can
not be computed 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 not be computed 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 not be computed 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 not be computed
null will be returned.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 not be computed
null will be returned.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.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.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.getUTCSunset(double)
,
getUTCSeaLevelSunrise(double)
public long getTemporalHour()
long
millisecond length of a temporal hour. If
the calculation can not be computed Long.MIN_VALUE
will
be returned.public long getTemporalHour(Date sunrise, Date sunset)
sunrise
- The start of the day.sunset
- The end of the day.
long
millisecond length of the temporal hour.
If the calculation can not be computed Long.MIN_VALUE
will be returned.getTemporalHour()
public Date getSunTransit()
Date
representing Sun's transit. If the
calculation can not be computed 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
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 |