The KosherJava Zmanim API version 2.3.0 was released on Dec 7th, 2021 ג׳ טבת תשפ״ב in Maven and GitHub. While there have been numerous releases over the years, this is the first release-related post since the v1.3.0 release in 2013. If you have not updated since that time, you can expect some changes. The most significant changes (besides a lot of new functionality) are the simple to fix breaking changes listed below.
The KosherJava zmanim library originally went live in 2004. There was an existing C/C++ zmanim project by Ken Bloom hosted on SourceForge (that was at the time the equivalent of what GitHub is today). The Java package structure name net.sourceforge.zmanim was based on the one used by Ken’s project (despite not being hosted there), and remained that way for 16 years. On August 3, 2020, Eli Julian modernized the library’s build process from the previously used Ant, to Maven & Gradle. This change simplified the workflow for many developers using the zmanim API. As part of the change, the package name was updated to com.kosherjava.zmanim. The KosherJava zmanim Maven / Gradle artifacts are available at the KosherJava zmanim Maven Central page. A direct Jar download is available at Maven Central (see the KosherJava Downloads page for instructions). The old code was branched into zmanim-1.5 and will allow people who do not want to upgrade to continue to use the old structure (and Ant build process) while continuing to receive emergency bug fixes. This will allow the codebase to use more modern Java language features, without impacting users who want to remain on the legacy code. The new code has a minimum Java 8 requirement (a version released in March 2014). Releases based on the new build process will use SemVer (Semantic Versioning) to make things simpler for developers. The upgraded build process also allowed automated GitHub’s CodeQLvulnerability scanning for the KosherJava Zmanim project. You can add the KosherJava zmanim library as a Maven or Gradle dependency. For Maven add the following to your pom.xml.
The Zmanim API version 1.3.0 was released on March 4th, 2013 כ״א אדר תשע״ג. Various changes in the new release VS the previous version 1.2.1 that was released in May 2010 can be seen below. This release includes beta support for Jewish Calendar calculations as well as a number of updated zmanim and refactored code. The Jewish Calendar support in the Zmanim API is based on Avrom Finkelstien’s HebrewDate project released in 2002. Unlike the Zmanim code, the Jewish calendar interfaces may change significantly in the future (see Jay Gindin’s various changes that may make it into this API) and should therefore be considered beta.
Changes in the Zmanim API 1.3.0 release
Refactoring of zmanim calculations to allow more flexibility in generating custom zmanim. New generic methods that take an arbitrary start and end of day for many zmanim such as sofZmanShema and getPlagHamincha etc. This makes calculating atypical zmanim that I had not anticipated when creating the API. I receive such requests from time to time, and the changes greatly simplify these types of calculations. Examples of recent requests are:
Zman krias Shema calculated from alos as 72 minutes before netz and tzais as 7.083 degrees
Plag hamincha from alos 7.083° to tzais 7.083°
Many rounds of general code refactoring to simplify and stabilize the code and make it easier to port. Thank you Jay Gindin for his many suggestions.
Deprecation of the getSofZmanShmaKolEliyahu() method. Thank you to Rabbi Yisroel Boruch Twerski for pointing out that the Yisrael Vehazmanim was incorrect in including this zman. This is something he discussed with Rabbi Harfenes.
Uniformly return zmanim based on sea level sunrise and sunset. Most zmanim had this fix a long time ago, but there were a few zmanim such as candle lighting time that were corrected.
How do I get the Jewish Date for … using the Zmanim API?
The current version of the Zanim API does not support Jewish calendrical calculations. Zmanim are almost exclusively based on the solar calendar, so for example, the sunrise on February 8th this year in Montreal (or any other date and location), will be almost the same every year. for this reason there was little point (as far as zmanim) to support Jewish date calculations in the API. One of the only zmanim to rely on a Jewish date is the sof zman kidush levanah calculation, though there are some opinions that it is purely molad based, and this can be calculated without a Jewish calendar component to the API. This zman is obviously not currently implemented in the Zmanim API. I am currently working on adding Jewish date support to the API. The code is based off Avrom Finkelstein‘s no longer active HebrewDate project. I refactored a lot of the code and fixed a number of bugs. Anyone interested in alpha testing this code can download the latest Zmanim SVN code. I mentioned that it “will be almost the same every year” and this is due the approximate 1/4 day drift between the 356 day calendar year and the approximately 365.25 days actually present in the astronomical year, a discrepancy corrected every leap year. A future FAQ (probably a few of them) may delve specifically into this drift as well as general zmanim accuracy issues in detail. If you are simply looking to convert a Hebrew date to Gregorian or Gregorian to Hebrew online without the API, try the JewishGencalendar conversion tools.
The Zmanim API 1.2.1 was released today. Changed in this release were the addition of a few very early Tzais zmanim, and the removal of references to the GregorianCalendar in favor of the base Calendar class to ease Noah Blumenthal’s use of the Zmanim API in a zmanim application for the BlackBerry. This change has no impact on functionality as tested using Yitzchok’s new JUnit tests. Additionally, the JavaDoc Zmanim API documentation was modified to clearly indicate that zmanim can return nulls. A followup post will have details on this. The main download is the Zmanim 1.2.1 release zip file that includes source files and JavaDoc documentation. Also available for download (included in the above zip file) is the main zmanim-1.2.1.jar and the zmanimAstronomical-1.2.1.jar that only includes the AstronomicalCalendar. The removal of the GregorianCalendar was in this class. Additional detail on the downloads can be seen on the Zmanim Download page