001 /*
002 * Zmanim Java API
003 * Copyright (C) 2004-2008 Eliyahu Hershfeld
004 *
005 * This program is free software; you can redistribute it and/or modify it under the terms of the
006 * GNU General Public License as published by the Free Software Foundation; either version 2 of the
007 * License, or (at your option) any later version.
008 *
009 * This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without
010 * even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
011 * General Public License for more details.
012 *
013 * You should have received a copy of the GNU General Public License along with this program; if
014 * not, write to the Free Software Foundation, Inc. 59 Temple Place - Suite 330, Boston, MA
015 * 02111-1307, USA or connect to: http://www.fsf.org/copyleft/gpl.html
016 */
017 package net.sourceforge.zmanim;
018
019 import java.util.Calendar;
020 import java.util.Date;
021
022 import net.sourceforge.zmanim.util.AstronomicalCalculator;
023 import net.sourceforge.zmanim.util.GeoLocation;
024
025 /**
026 * <p>
027 * Description: A Java library for calculating zmanim.
028 * </p>
029 * The zmanim library is an API is a specialized calendar that can calculate
030 * sunrise and sunset and Jewish <em>zmanim</em> (religious times) for prayers
031 * and other Jewish religious duties. For a much more extensive list of zmanim
032 * use the {@link ComplexZmanimCalendar} that extends this class. This class
033 * contains the main functionality of the Zmanim library.
034 * <h2>Disclaimer:</h2>
035 * While I did my best to get accurate results please do not rely on these
036 * zmanim for <em>halacha lemaaseh</em>
037 *
038 * @author © Eliyahu Hershfeld 2004 - 2008
039 * @version 1.1
040 */
041 public class ZmanimCalendar extends AstronomicalCalendar {
042 private static final long serialVersionUID = 1;
043
044 /**
045 * The zenith of 16.1° below geometric zenith (90°). This
046 * calculation is used for calculating <em>alos</em> (dawn) and
047 * <em>tzais</em> (nightfall) in some opinions. This calculation is based
048 * on the calculation that the time between dawn and sunrise (and sunset to
049 * nightfall) is the time that is takes to walk 4 <em>mil</em> at 18
050 * minutes a mil (<em>Ramba"m</em> and others). The sun's position at 72
051 * minutes before {@link #getSunrise sunrise} in Jerusalem on the equinox is
052 * 16.1° below {@link #GEOMETRIC_ZENITH geometric zenith}.
053 *
054 * @see #getAlosHashachar()
055 * @see ComplexZmanimCalendar#getAlos16Point1Degrees()
056 * @see ComplexZmanimCalendar#getTzais16Point1Degrees()
057 * @see ComplexZmanimCalendar#getSofZmanShmaMGA16Point1Degrees()
058 * @see ComplexZmanimCalendar#getSofZmanTfilaMGA16Point1Degrees()
059 * @see ComplexZmanimCalendar#getMinchaGedola16Point1Degrees()
060 * @see ComplexZmanimCalendar#getMinchaKetana16Point1Degrees()
061 * @see ComplexZmanimCalendar#getPlagHamincha16Point1Degrees()
062 * @see ComplexZmanimCalendar#getPlagAlos16Point1ToTzaisGeonim7Point083Degrees()
063 * @see ComplexZmanimCalendar#getSofZmanShmaAlos16Point1ToSunset()
064 */
065 protected static final double ZENITH_16_POINT_1 = GEOMETRIC_ZENITH + 16.1;
066
067 /**
068 * The zenith of 8.5° below geometric zenith (90°). This calculation
069 * is used for calculating <em>alos</em> (dawn) and <em>tzais</em>
070 * (nightfall) in some opinions. This calculation is based on the position
071 * of the sun 36 minutes after {@link #getSunset sunset} in Jerusalem on March 16,
072 * about 4 days before the equinox, the day that a solar hour is one hour, which is 8.5° below
073 * {@link #GEOMETRIC_ZENITH geometric zenith}. The Ohr Meir considers this
074 * the time that 3 small starts are visible, later than the required 3 medium
075 * stars.
076 *
077 * @see #getTzais()
078 * @see ComplexZmanimCalendar#getTzaisGeonim8Point5Degrees()
079 */
080 protected static final double ZENITH_8_POINT_5 = GEOMETRIC_ZENITH + 8.5;
081
082 // private AstronomicalCalculator astronomicalGeometryCalculator;
083
084 private double candleLightingOffset = 18;
085
086 /**
087 * Returns <em>tzais</em> (nightfall) when the sun is 8.5° below the
088 * western geometric horizon (90°) after {@link #getSunset sunset}. For
089 * information on the source of this calculation see
090 * {@link #ZENITH_8_POINT_5}.
091 *
092 * @return The <code>Date</code> of nightfall.
093 * @see #ZENITH_8_POINT_5
094 */
095 public Date getTzais() {
096 return this.getSunsetOffsetByDegrees(ZENITH_8_POINT_5);
097 }
098
099 /**
100 * Returns <em>alos</em> (dawn) based on the time when the sun is
101 * 16.1° below the eastern {@link #GEOMETRIC_ZENITH geometric horizon}
102 * before {@link #getSunrise sunrise}. For more information the source of
103 * 16.1° see {@link #ZENITH_16_POINT_1}.
104 *
105 * @see net.sourceforge.zmanim.ZmanimCalendar#ZENITH_16_POINT_1
106 * @return The <code>Date</code> of dawn.
107 */
108 public Date getAlosHashachar() {
109 return getSunriseOffsetByDegrees(ZENITH_16_POINT_1);
110 }
111
112 /**
113 * Method to return <em>alos</em> (dawn) calculated using 72 minutes
114 * before {@link #getSeaLevelSunrise() sea level sunrise} (no adjustment for
115 * elevation) based on the time to walk the distance of 4 <em>Mil</em> at
116 * 18 minutes a <em>Mil</em>. This is based on the opinion of most
117 * <em>Rishonim</em> who stated that the time of the <em>Neshef</em>
118 * (time between dawn and sunrise) does not vary by the time of year or
119 * location but purely depends on the time it takes to walk the distance of
120 * 4 <em>Mil</em>.
121 *
122 * @return the <code>Date</code> representing the time.
123 */
124 public Date getAlos72() {
125 return getTimeOffset(getSeaLevelSunrise(), -72 * MINUTE_MILLIS);
126 }
127
128 /**
129 * This method returns <em>chatzos</em> (midday) following the opinion of
130 * the GRA that the day for Jewish halachic times start at
131 * {@link #getSunrise sunrise} and ends at {@link #getSunset sunset}. The
132 * returned value is identical to {@link #getSunTransit()}
133 *
134 * @see AstronomicalCalendar#getSunTransit()
135 * @return the <code>Date</code> of chatzos.
136 */
137 public Date getChatzos() {
138 return getSunTransit();
139 }
140
141 /**
142 * A method that returns "solar" midnight, or the time when the sun is at
143 * it's <a href="http://en.wikipedia.org/wiki/Nadir">nadir</a>. <br/><br/><b>Note:</b>
144 * this method is experimental and might be removed (or moved)
145 *
146 * @return the <code>Date</code> of Solar Midnight (chatzos layla).
147 */
148 public Date getSolarMidnight() {
149 ZmanimCalendar clonedCal = (ZmanimCalendar) clone();
150 clonedCal.getCalendar().add(Calendar.DAY_OF_MONTH, 1);
151 Date sunset = getSunset();
152 Date sunrise = clonedCal.getSunrise();
153 return getTimeOffset(sunset, getTemporalHour(sunset, sunrise) * 6);
154 }
155
156 // public Date getChatzosLaylaRSZ() {
157 // ZmanimCalendar clonedCal = (ZmanimCalendar)clone();
158 // clonedCal.getCalendar().add(Calendar.DAY_OF_MONTH, 1);
159 // Date sunset = getSunset();
160 // Date sunrise = clonedCal.getAlosHashachar();
161 // return getTimeOffset(sunset, getTemporalHour(sunset, sunrise) * 6);
162 // }
163
164 /**
165 * This method returns the latest <em>zman krias shema</em> (time to say
166 * Shema in the morning). This time is 3
167 * <em>{@link #getShaahZmanisGra() shaos zmaniyos}</em> (solar hours)
168 * after {@link #getSunrise() sunrise} based on the opinion of the
169 * <em>GR"A</em> and the <em>Baal Hatanya</em> that the day is
170 * calculated from sunrise to sunset. This returns the time 3 *{@link #getShaahZmanisGra()}
171 * after {@link #getSunrise() sunrise}.
172 *
173 * @see net.sourceforge.zmanim.ZmanimCalendar#getShaahZmanisGra()
174 * @return the <code>Date</code> of the latest zman shema.
175 */
176 public Date getSofZmanShmaGRA() {
177 return getTimeOffset(getSunrise(), getShaahZmanisGra() * 3);
178 }
179
180 /**
181 * This method returns the latest <em>zman krias shema</em> (time to say
182 * Shema in the morning) in the opinion of the <em>MG"A</em> based on
183 * <em>alos</em> being 72 minutes before {@link #getSunrise() sunrise}.
184 * This time is 3 <em> shaos zmaniyos</em> (solar hours) after dawn based
185 * on the opinion of the <em>MG"A</em> that the day is calculated from a
186 * dawn of 72 minutes before sunrise to nightfall of 72 minutes after
187 * sunset. This returns the time of 3 * <em>shaos zmaniyos</em> after
188 * dawn.
189 *
190 * @return the <code>Date</code> of the latest zman shema.
191 * @see ComplexZmanimCalendar#getShaahZmanis72Minutes()
192 * @see ComplexZmanimCalendar#getAlos72()
193 * @see ComplexZmanimCalendar#getSofZmanShmaMGA72Minutes()
194 */
195 public Date getSofZmanShmaMGA() {
196 return getTimeOffset(getAlos72(), getShaahZmanisMGA() * 3);
197 }
198
199 /**
200 * This method returns the <em>tzais</em> (nightfall) based on the opinion
201 * of the <em>Ramba"m</em> and <em>Rabainu Tam</em> that <em>tzais</em>
202 * is calculated as the time it takes to walk 4 <em>Mil</em> at 18 minutes
203 * a <em>Mil</em> for a total of 72 minutes. Even for locations above sea
204 * level, this is calculated at sea level, since the darkness level is not
205 * affected by elevation.
206 *
207 * @return the <code>Date</code> representing 72 minutes after sea level
208 * sunset.
209 */
210 public Date getTzais72() {
211 return getTimeOffset(getSeaLevelSunset(), 72 * MINUTE_MILLIS);
212 }
213
214 /**
215 * A method to return candle lighting time. This is calculated as
216 * {@link #getCandleLightingOffset()} minutes before sunset. This will
217 * return the time for any day of the week, since it can be used to
218 * calculate candle lighting time for <em>yom tov</em> (holidays) as well.
219 *
220 * @return candle lighting time.
221 * @see #getCandleLightingOffset()
222 * @see #setCandleLightingOffset(double)
223 */
224 public Date getCandelLighting() {
225 return getTimeOffset(getSunset(), -getCandleLightingOffset()
226 * MINUTE_MILLIS);
227 }
228
229 /**
230 * This method returns the latest
231 * <em>zman tefilah<em> (time to pray morning prayers). This time is 4
232 * hours into the day based on the opinion of the <em>GR"A</em> and the </em>Baal Hatanya</em>
233 * that the day is calculated from sunrise to sunset. This returns the time
234 * 4 * {@link #getShaahZmanisGra()} after {@link #getSunrise() sunrise}.
235 *
236 * @see net.sourceforge.zmanim.ZmanimCalendar#getShaahZmanisGra()
237 * @return the <code>Date</code> of the latest zman tefilah.
238 */
239 public Date getSofZmanTfilaGRA() {
240 return getTimeOffset(getSunrise(), getShaahZmanisGra() * 4);
241 }
242
243 /**
244 * This method returns the latest <em>zman tfila</em> (time to say the
245 * morning prayers) in the opinion of the <em>MG"A</em> based on
246 * <em>alos</em> being {@link #getAlos72() 72} minutes before
247 * {@link #getSunrise() sunrise}. This time is 4
248 * <em>{@link #getShaahZmanisMGA() shaos zmaniyos}</em> (temporal hours)
249 * after {@link #getAlos72() dawn} based on the opinion of the <em>MG"A</em>
250 * that the day is calculated from a {@link #getAlos72() dawn} of 72 minutes
251 * before sunrise to {@link #getTzais72() nightfall} of 72 minutes after
252 * sunset. This returns the time of 4 * {@link #getShaahZmanisMGA()} after
253 * {@link #getAlos72() dawn}.
254 *
255 * @return the <code>Date</code> of the latest zman tfila.
256 * @see #getShaahZmanisMGA()
257 * @see #getAlos72()
258 */
259 public Date getSofZmanTfilaMGA() {
260 return getTimeOffset(getAlos72(), getShaahZmanisMGA() * 4);
261 }
262
263 /**
264 * This method returns the time of <em>mincha gedola</em>.<em>Mincha gedola</em>
265 * is the earliest time one can pray mincha. The Ramba"m is of the opinion
266 * that it is better to delay <em>mincha</em> until
267 * <em>{@link #getMinchaKetana() mincha ketana}</em> while the <em>Ra"sh,
268 * Tur, GR"A</em>
269 * and others are of the opinion that <em>mincha</em> can be prayed
270 * <em>lechatchila</em> starting at <em>mincha gedola</em>. This is
271 * calculated as 6.5 {@link #getTemporalHour() solar hours} after sunrise.
272 * This calculation is calculated based on the opinion of the <em>GR"A</em>
273 * and the <em>Baal Hatanya</em> that the day is calculated from sunrise
274 * to sunset. This returns the time 6.5 *{@link #getShaahZmanisGra()} after
275 * {@link #getSunrise() sunrise}.
276 *
277 * @see #getShaahZmanisGra()
278 * @see #getMinchaKetana()
279 * @return the <code>Date</code> of the time of mincha gedola.
280 */
281 public Date getMinchaGedola() {
282 return getTimeOffset(getSunrise(), getShaahZmanisGra() * 6.5);
283 }
284
285 /**
286 * This method returns the time of <em>mincha ketana</em>. This is the
287 * perfered earliest time to pray <em>mincha</em> in the opinion of the
288 * Ramba"m and others. For more information on this see the documentation on
289 * <em>{@link #getMinchaGedola() mincha gedola}</em>. This is calculated
290 * as 9.5 {@link #getTemporalHour() solar hours}after sunrise. This
291 * calculation is calculated based on the opinion of the <em>GR"A</em> and
292 * the <em>Baal Hatanya</em> that the day is calculated from sunrise to
293 * sunset. This returns the time 9.5 * {@link #getShaahZmanisGra()} after
294 * {@link #getSunrise() sunrise}.
295 *
296 * @see #getShaahZmanisGra()
297 * @see #getMinchaGedola()
298 * @return the <code>Date</code> of the time of mincha gedola.
299 */
300 public Date getMinchaKetana() {
301 return getTimeOffset(getSunrise(), getShaahZmanisGra() * 9.5);
302 }
303
304 /**
305 * This method returns he time of <em>plag hamincha</em>. This is
306 * calculated as 10.75 hours after sunrise. This calculation is calculated
307 * based on the opinion of the <em>GR"A</em> and the <em>Baal Hatanya</em>
308 * that the day is calculated from sunrise to sunset. This returns the time
309 * 10.75 *{@link #getShaahZmanisGra()} after {@link #getSunrise() sunrise}.
310 *
311 * @return the <code>Date</code> of the time of <em>plag hamincha</em>.
312 */
313 public Date getPlagHamincha() {
314 return getTimeOffset(getSunrise(), getShaahZmanisGra() * 10.75);
315 }
316
317 /**
318 * Method to return a <em>shaah zmanis</em> ({@link #getTemporalHour temporal hour})
319 * according to the opinion of the <em>GR"A</em> and the
320 * <em>Baal Hatanya</em>. This calculation divides the day based on the
321 * opinion of the <em>GR"A</em> and the <em>Baal Hatanya</em> that the
322 * day runs from {@link #getSunrise() sunrise} to {@link #getSunset sunset}.
323 * The day is split into 12 equal parts each part with each one being a
324 * <em>shaah zmanis</em>. This method is identical to
325 * {@link #getTemporalHour} (it is actually a wrapper that calls that
326 * method) and is provided for clarity.
327 *
328 * @return the <code>long</code> millisecond length of a
329 * <em>shaah zmanis</em>.
330 * @see #getTemporalHour()
331 */
332 public long getShaahZmanisGra() {
333 return getTemporalHour();
334 }
335
336 /**
337 * Method to return a <em>shaah zmanis</em> (temporal hour) according to
338 * the opinion of the MGA. This calculation divides the day based on the
339 * opinion of the <em>MGA</em> that the day runs from dawn to dusk (for
340 * sof zman krias shema and tfila). Dawn for this calculation is 72 minutes
341 * before sunrise and dusk is 72 minutes after sunset. This day is split
342 * into 12 equal parts with each part being a <em>shaah zmanis</em>.
343 * Alternate mothods of calculating a <em>shaah zmanis</em> are available
344 * in the subclass {@link ComplexZmanimCalendar}.
345 *
346 * @return the <code>long</code> millisecond length of a
347 * <em>shaah zmanis</em>.
348 */
349 public long getShaahZmanisMGA() {
350 return getTemporalHour(getAlos72(), getTzais72());
351 }
352
353 /**
354 * Default constructor will set a default {@link GeoLocation#GeoLocation()},
355 * a default
356 * {@link AstronomicalCalculator#getDefault() AstronomicalCalculator} and
357 * default the calendar to the current date.
358 *
359 * @see AstronomicalCalendar#AstronomicalCalendar()
360 */
361 public ZmanimCalendar() {
362 super();
363 }
364
365 /**
366 * A constructor that takes a {@link GeoLocation} as a parameter.
367 *
368 * @param location
369 * the location
370 */
371 public ZmanimCalendar(GeoLocation location) {
372 super(location);
373 }
374
375 /**
376 * @see java.lang.Object#equals(Object)
377 */
378 public boolean equals(Object object) {
379 if (this == object) {
380 return true;
381 }
382 if (!(object instanceof ZmanimCalendar)) {
383 return false;
384 }
385 ZmanimCalendar zCal = (ZmanimCalendar) object;
386 // return getCalendar().getTime().equals(zCal.getCalendar().getTime())
387 return getCalendar().equals(zCal.getCalendar())
388 && getGeoLocation().equals(zCal.getGeoLocation())
389 && getAstronomicalCalculator().equals(
390 zCal.getAstronomicalCalculator());
391 }
392
393 /**
394 * @see java.lang.Object#hashCode()
395 */
396 public int hashCode() {
397 int result = 17;
398 // needed or this and subclasses will return identical hash
399 result = 37 * result + getClass().hashCode();
400 result += 37 * result + getCalendar().hashCode();
401 result += 37 * result + getGeoLocation().hashCode();
402 result += 37 * result + getAstronomicalCalculator().hashCode();
403 return result;
404 }
405
406 /**
407 * A method to get the offset in minutes before
408 * {@link AstronomicalCalendar#getSunset() sunset} that is used in
409 * calculating candle lighting time. The default time used is 18 minutes
410 * before sunset. Some calendars use 15 minutes, while the custom in
411 * Jerusalem is to use a 40 minute offset. Please check the local custom for
412 * candel lighting time.
413 *
414 * @return Returns the candle lighting offset to set in minutes..
415 * @see #getCandelLighting()
416 */
417 public double getCandleLightingOffset() {
418 return candleLightingOffset;
419 }
420
421 /**
422 * A method to set the offset in minutes before
423 * {@link AstronomicalCalendar#getSunset() sunset} that is used in
424 * calculating candle lighting time. The default time used is 18 minutes
425 * before sunset. Some calendars use 15 minutes, while the custom in
426 * Jerusalem is to use a 40 minute offset.
427 *
428 * @param candleLightingOffset
429 * The candle lighting offset to set in minutes.
430 * @see #getCandelLighting()
431 */
432 public void setCandleLightingOffset(double candleLightingOffset) {
433 this.candleLightingOffset = candleLightingOffset;
434 }
435 }