AstronomicalCalculator.java - Add abstract method getUTCMidnight

- Add abstract method getUTCMidnight
- add default constructor to avoid warnings on recent JDKs
- Tweak JavaDocs

src/main/java/com/kosherjava/zmanim/util/AstronomicalCalculator.java

@@ -1,6 +1,6 @@
 /*
  * Zmanim Java API
- * Copyright (C) 2004-2023 Eliyahu Hershfeld
+ * Copyright (C) 2004-2025 Eliyahu Hershfeld
  *
  * This library is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General
  * Public License as published by the Free Software Foundation; either version 2.1 of the License, or (at your option)
@@ -23,12 +23,12 @@
  * @todo Consider methods that would allow atmospheric modeling. This can currently be adjusted by {@link
  * #setRefraction(double) setting the refraction}.
  * 
- * @author © Eliyahu Hershfeld 2004 - 2023
+ * @author © Eliyahu Hershfeld 2004 - 2025
  */
 public abstract class AstronomicalCalculator implements Cloneable {
 	/**
-	 * The commonly used average solar refraction. Calendrical Calculations lists a more accurate global average of
-	 * 34.478885263888294
+	 * The commonly used average solar refraction. <a href="https://www.cs.tau.ac.il//~nachum/calendar-book/index.shtml"
+	 * >Calendrical Calculations</a> lists a more accurate global average of 34.478885263888294
 	 * 
 	 * @see #getRefraction()
 	 */
@@ -49,6 +49,14 @@ public abstract class AstronomicalCalculator implements Cloneable {
 	 * @see #setEarthRadius(double)
 	 */
 	private double earthRadius = 6356.9; // in KM
+
+	/**
+	 * Default constructor using the default {@link #refraction refraction}, {@link #solarRadius solar radius} and
+	 * {@link #earthRadius earth radius}.
+	 */
+	public AstronomicalCalculator() {
+		// keep the defaults for now. 
+	}
 
 	/**
 	 * A method that returns the earth radius in KM. The value currently defaults to 6356.9 KM if not set.
@@ -75,8 +83,8 @@ public void setEarthRadius(double earthRadius) {
 	private static final double GEOMETRIC_ZENITH = 90;
 
 	/**
-	 * Returns the default class for calculating sunrise and sunset. This is currently the more accurate {@link NOAACalculator},
-	 * but this may change.
+	 * Returns the default class for calculating sunrise and sunset. This is currently the more accurate
+	 * {@link NOAACalculator}, but this may change in the future.
 	 * 
 	 * @return AstronomicalCalculator the default class for calculating sunrise and sunset. In the current
 	 *         implementation the default calculator returned is the more accurate {@link NOAACalculator}.
@@ -155,6 +163,22 @@ public abstract double getUTCSunset(Calendar calendar, GeoLocation geoLocation,
 	 * @return the time in minutes from zero UTC
 	 */
 	public abstract double getUTCNoon(Calendar calendar, GeoLocation geoLocation);
+
+
+	/**
+	 * Return <a href="https://en.wikipedia.org/wiki/Midnight">solar midnight</a> (UTC) for the given day at the
+	 * given location on earth. The the {@link com.kosherjava.zmanim.util.NOAACalculator} implementation calculates
+	 * true solar midnight, while the {@link com.kosherjava.zmanim.util.SunTimesCalculator} approximates it, calculating
+	 * the time as 12 hours after halfway between sunrise and sunset.
+	 * 
+	 * @param calendar
+	 *            Used to calculate day of year.
+	 * @param geoLocation
+	 *            The location information used for astronomical calculating sun times.         
+	 * 
+	 * @return the time in minutes from zero UTC
+	 */
+	public abstract double getUTCMidnight(Calendar calendar, GeoLocation geoLocation);
 
 	/**
 	 * Method to return the adjustment to the zenith required to account for the elevation. Since a person at a higher
@@ -169,9 +193,9 @@ public abstract double getUTCSunset(Calendar calendar, GeoLocation geoLocation,
 	 * elevationAdjustment = Math.toDegrees(Math.acos(earthRadiusInMeters / (earthRadiusInMeters + elevationMeters)));
 	 * </pre>
 	 * 
-	 * The source of this algorithm is <a href="http://www.calendarists.com">Calendrical Calculations</a> by Edward M.
-	 * Reingold and Nachum Dershowitz. An alternate algorithm that produces an almost identical (but not accurate)
-	 * result found in Ma'aglay Tzedek by Moishe Kosower and other sources is:
+	 * The source of this algorithm is <a href="https://www.cs.tau.ac.il/~nachum/calendar-book/index.shtml">Calendrical
+	 * Calculations</a> by Edward M. Reingold and Nachum Dershowitz. An alternate algorithm that produces similar (but
+	 * not completely accurate) result found in Ma'aglay Tzedek by Moishe Kosower and other sources is:
 	 * 
 	 * <pre>
 	 * elevationAdjustment = 0.0347 * Math.sqrt(elevationMeters);
@@ -201,7 +225,7 @@ public abstract double getUTCSunset(Calendar calendar, GeoLocation geoLocation,
 	 * account for elevation if available. Note that this will only adjust the value if the zenith is exactly 90 degrees.
 	 * For values below and above this no correction is done. As an example, astronomical twilight is when the sun is
 	 * 18&deg; below the horizon or {@link com.kosherjava.zmanim.AstronomicalCalendar#ASTRONOMICAL_ZENITH 108&deg;
-	 * below the zenith}. This is traditionally calculated with none of the above-mentioned adjustments. The same goes
+	 * below the zenith}. This is traditionally calculated with none of the above mentioned adjustments. The same goes
 	 * for various <em>tzais</em> and <em>alos</em> times such as the
 	 * {@link com.kosherjava.zmanim.ZmanimCalendar#ZENITH_16_POINT_1 16.1&deg;} dip used in
 	 * {@link com.kosherjava.zmanim.ComplexZmanimCalendar#getAlos16Point1Degrees()}.
@@ -228,11 +252,10 @@ public abstract double getUTCSunset(Calendar calendar, GeoLocation geoLocation,
 	}
 
 	/**
-	 * Method to get the refraction value to be used when calculating sunrise and sunset. The default value is 34 arc
-	 * minutes. The <a href=
-	 * "https://web.archive.org/web/20150915094635/http://emr.cs.iit.edu/home/reingold/calendar-book/second-edition/errata.pdf"
-	 * >Errata and Notes for Calendrical Calculations: The Millennium Edition</a> by Edward M. Reingold and Nachum Dershowitz
-	 * lists the actual average refraction value as 34.478885263888294 or approximately 34' 29". The refraction value as well
+	 * Method to get the refraction value to be used when calculating sunrise and sunset. The default value is 34
+	 * arcminutes. The <a href="https://www.cs.tau.ac.il/~nachum/calendar-book/second-edition/errata.pdf">Errata and Notes
+	 * for Calendrical Calculations: The Millennium Edition</a> by Edward M. Reingold and Nachum Dershowitz lists the
+	 * actual average refraction value as 34.478885263888294 or approximately 34' 29". The refraction value as well
 	 * as the solarRadius and elevation adjustment are added to the zenith used to calculate sunrise and sunset.
 	 * 
 	 * @return The refraction in arcminutes.
@@ -263,7 +286,7 @@ public void setRefraction(double refraction) {
 	 * the difference at the location of the <a href="https://www.rmg.co.uk/royal-observatory">Royal Observatory, Greenwich</a>
 	 * shows only a 4.494-second difference between the perihelion and aphelion radii, but moving into the arctic circle the
 	 * difference becomes more noticeable. Tests for Tromso, Norway (latitude 69.672312, longitude 19.049787) show that
-	 * on May 17, the rise of the midnight sun, a 2-minute 23-second difference is observed between the perihelion and
+	 * on May 17, the rise of the midnight sun, a 2 minute and 23 second difference is observed between the perihelion and
 	 * aphelion radii using the USNO algorithm, but only 1 minute and 6 seconds difference using the NOAA algorithm.
 	 * Areas farther north show an even greater difference. Note that these test are not real valid test cases because
 	 * they show the extreme difference on days that are not the perihelion or aphelion, but are shown for illustrative