KosherJava Zmanim API Released Under the LGPL License

LGPL 2.1Until this point the KosherJava Zmanim API has been released under the GPL V2.0 open source license. This had the effect of forcing any application written using the library to release it’s source code under the same license. Being that the Zmanim API is a library, the LGPL is a more appropriate license. The LGPL allows developers to use the KosherJava Zmanim API, yet keep their application code closed source. Only changes to the API itself (such as ports to different languages) would have to be released as open source. I had in the past on request released the source under the LGPL (the Zmanim API .NET port has already been released under the LGPL with my permission), and with the recent 3/27/2011 SVN checkin I formally changed the Java Zmanim API license to the LGPL 2.1 (not the newer LGPL 3.0). The next 1.3.0 release will be the first formal release under the LGPL. In one case the change to the license required permission from developer who wrote code used by the the Zmanim API, and this was done.

Calculating Erev Pesach Zmanim

MatzosThe Zmanim API did not have dedicated zmanim to claculate the Erev Pesach zmanim of sof zman achilas chametz (the latest time one can eat chametz), and sof zman biur chametz (the latest time to burn chametz) till the April 14 check in to the KosherJava Zmanim Project GitHub repository. The latest time for eating chametz is at the end of the 4th hour of the day. This corresponds to sof zman tfila. The API has about 12 of those, so that does not require any special programming, but to help developers who are unaware of how they work I created 3 wrapper getSofZmanAchilasChametz methods (getSofZmanAchilasChametzGRA(), getSofZmanAchilasChametzMGA72Minutes() and getSofZmanAchilasChametzMGA16Point1Degrees()) calling the 3 most commonly used getSofZmanTfila methods (getSofZmanTfilaGRA(), getSofZmanTfilaMGA72Minutes() and getSofZmanTfilaMGA16Point1Degrees()). For example here is the exact code used in getSofZmanAchilasChametzGRA()

public Date getSofZmanAchilasChametzGRA() {
	return getSofZmanTfilaGRA();
}

The API itself is very flexible, and as long as you know the calculation of the zman, you can easily calculate it. For example, to calculate sof zman biur chametz according to the GR"A, the time would be 5 shaos zmaniyos after sunrise. Using the Zmanim API this would be coded as:

Date SofZmanBiurChametzGra = getTimeOffset(getSeaLevelSunrise(), getShaahZmanisGra() * 5);

The exact code used in the API is:

public Date getSofZmanBiurChametzGRA() {
	return getTimeOffset(getSeaLevelSunrise(), getShaahZmanisGra() * 5);
}

Developers who want to use the current API to generate these zmanim can use the following sample as a guide.

String locationName = "Lakewood, NJ";
double latitude = 40.09596; //Lakewood, NJ
double longitude = -74.22213; //Lakewood, NJ
double elevation = 0; //optional elevation
TimeZone timeZone = TimeZone.getTimeZone("America/New_York");
GeoLocation location = new GeoLocation(locationName, latitude, longitude, elevation, timeZone);
ComplexZmanimCalendar czc = new ComplexZmanimCalendar(location);
czc.getCalendar().set(Calendar.YEAR, 2011);
czc.getCalendar().set(Calendar.MONTH, Calendar.APRIL);
czc.getCalendar().set(Calendar.DAY_OF_MONTH, 18);
Date graAchilas = czc.getSofZmanTfilaGRA();
Date graBiur = czc.getTimeOffset(czc.getSeaLevelSunrise(), czc.getShaahZmanisGra() * 5);
Date mga72Achilas = czc.getSofZmanTfilaMGA72Minutes();
Date mga72Biur = czc.getTimeOffset(czc.getAlos72(), czc.getShaahZmanisMGA() * 5);
Date mga16Achilas = czc.getSofZmanTfilaMGA16Point1Degrees();
Date mga16Biur = czc.getTimeOffset(czc.getAlos16Point1Degrees(), czc.getShaahZmanis16Point1Degrees() * 5);
System.out.println("Erev Pesach Zmanim for " + locationName);
System.out.println("Sof Zman Achilas Chametz GRA: " + graAchilas);
System.out.println("Sof Zman Biur Chametz GRA: : " + graBiur);
System.out.println("Sof Zman Achilas Chametz MGA 72 Minutes: " + mga72Achilas);
System.out.println("Sof Zman Biur Chametz MGA 72 Minutes: " + mga72Biur);
System.out.println("Sof Zman Achilas Chametz MGA 16.1 Deg: " + mga16Achilas);
System.out.println("Sof Zman Biur Chametz MGA 16.1 Deg: " + mga16Biur);

this would output

C:\path\to\code>javac ErevPesachZmanim.java

C:\path\to\code>java ErevPesachZmanim

Erev Pesach Zmanim for Lakewood, NJ
Sof Zman Achilas Chametz GRA: Mon Apr 18 10:42:42 EDT 2011
Sof Zman Biur Chametz GRA: : Mon Apr 18 11:49:39 EDT 2011
Sof Zman Achilas Chametz MGA 72 Minutes: Mon Apr 18 10:18:42 EDT 2011
Sof Zman Biur Chametz MGA 72 Minutes: Mon Apr 18 11:37:39 EDT 2011
Sof Zman Achilas Chametz MGA 16.1 Deg: Mon Apr 18 10:13:56 EDT 2011
Sof Zman Biur Chametz MGA 16.1 Deg: Mon Apr 18 11:35:18 EDT 2011

Zmanim API Now in a Public SVN Server

Code VaultThanks to Jay Gindin, the Zmanim API source code is now in a publicly available SVN server. The Google Code project can be found at code.google.com/p/kosherjava. This will have a number of benefits to the project. It will more easily allow users to find the code, ensure that they have the latest code, track changes, and allow reverting to prior versions in case an issue arises with newly checked in code. It will also allow me to stop the manual backups (part of the projects Ant build script) done as part of every development build. The repository has the new hebrewcalendar package mentioned in the recently posted FAQ: How do I Calculate the Jewish/Hebrew Date for …?. This new code is under heavy revision, and there will be changes that will likely break code using the current alpha version. The pace of changes to the interface will likely remain stable once the first beta version is released (probably after Pesach). The next step will be to touch base with various people who have copies of the API in their own SVN to either update or link to this official project SVN server.

KosherJava Zmanim Code Now in GitHub

With Google shutting down Google Code at the end of 2015, the KosherJava Zmanim source code has been moved to GitHub.

FAQ: How do I Calculate the Jewish/Hebrew Date for …?

Sunrise Calendar

This FAQ is now obsolete. Jewish Calendar Calculations are now supported. See the Zmanim API 1.3.0 Release announcement

Question:

How do I get the Jewish Date for … using the Zmanim API?

Answer:

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 (or download the Zmanim API 1.3.0 alpha release).
I mentioned that it “will be almost the same every year” and this is due the 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 JewishGen calendar conversion tools.

FAQ: Why Some Zmanim Never Occur (Developers Beware)

Question:

Why do Some Zmanim Never Occur in Some Locations? (Developers Beware)

Answer:

While most people realize that the sun may not rise or set in the Arctic and Antarctic Circles (see the Star-K’s When Does One Pray When There Is No Day), many are not aware that some twilight dips will not occur during part of the year as far south of the Arctic Circle as London. For example around the summer solstice in London (on the zmanim map) the sun will never dip far enough below the horizon to reach Alos 16°. This happens in London from June 5th till July 8th. The image seen on the top right (original at timeanddate.com) shows various civil twilights centered on London on Midnight June 21st. Look carefully to see the various bands of twilight. Gateshead will not have Alos 16° from May 16th through July 28th, while Anchorage, Alaska (yes there is a Frum Shul in Anchorage with an interesting davening direction issue that is discussed in the Davening Direction from Alaska post ) will not have Alos 16.1° from April 25th to August 20th. Zmanim based on sunrise such as Also 72 that is a 72 minute offset of sunrise can be calculated as long as sunrise can be calculated, something that will happen as long as you are not in the Arctic or Antarctic Circles.
For this reason, the Zmanim API will return a null when a zman will not happen. A Long.MIN_VALUE will be returned when a long is expected such as in the case of a Shaah Zmanis. While an inconvenience to developers who have to code for this, the alternative of a default date would mean that developers unaware of this would return incorrect zmanim, something far worse than a program error from a NullPointerException.
In recent weeks two publicly available programs using the Zmanim API ran into issues due to nulls returned for early alos times. Being something not anticipated by the developers, the nulls generated errors in the programs that quickly led to fixes. For this reason Yitzchok updated the Zmanim .NET project to return the nullable DateTime? instead of the regular DateTime that it had previously been returning. While the Zmanim API documentation always made the possibility of a null being returned possible, I modified the documentation to make this clear on the return value documentation for every zman. Code with the modified documentation was part of the recently released Zmanim API 1.2.1.

Zmanim API 1.2.1 Released

Zmanim API 1.2.1 ReleaseThe 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

Zmanim API Ported to .NET (C#)

Yitzchok ported the Zmanim API from Java to a .NET API using C#. The Zmanim .NET project was released under the LGPL. This is a change from the GPL used by the Java API, something that may change shortly. Also part of the project was the creation of a C# version of the Zmanim CLI, matching Moshe Wagner’s Java Zmanim CLI. When developing the project, Yitzchok created the ZmanimTest JUnit test case class to confirm that the C# port output matched the Java API. I will likely add this to the core Zmanim API in the near future. The port currently relies on IKVM assemblies as can be seen in the Java references in the code sample below, mostly because of the lack of a native .NET equivalent of the Java TimeZone class. Yitzchok also created some examples of the use of the Zmanim .NET API that will be of help to developers. Below are two of the simpler examples in C# and VB.NET demonstrating a very simple use of the API to output zmanim from the console.

C#

using Zmanim.TimeZone;
using Zmanim.TzDatebase; //in Zmanim.TzDatebase.dll assembly
using Zmanim.Utilities;

namespace Zmanim.Samples.Console
{
    class Program
    {
        static void Main(string[] args)
        {
            string locationName = "Lakewood, NJ";
            double latitude = 40.09596; //Lakewood, NJ
            double longitude = -74.22213; //Lakewood, NJ
            double elevation = 0; //optional elevation
            ITimeZone timeZone = new OlsonTimeZone("America/New_York");
            GeoLocation location = new GeoLocation(locationName, latitude, longitude, elevation, timeZone);
            ComplexZmanimCalendar zc = new ComplexZmanimCalendar(location);
            //optionally set it to a specific date with a year, month and day
            //ComplexZmanimCalendar zc = new ComplexZmanimCalendar(new DateTime(1969, 2, 8), location);

            System.Console.WriteLine("Today's Zmanim for " + locationName);
            System.Console.WriteLine("Sunrise: " + zc.GetSunrise()); //output sunrise
            System.Console.WriteLine("Sof Zman Shema MGA: " + zc.GetSofZmanShmaMGA()); //output Sof Zman Shema MGA
            System.Console.WriteLine("Sof Zman Shema GRA: " + zc.GetSofZmanShmaGRA()); //output Sof Zman Shema GRA
            System.Console.WriteLine("Sunset: " + zc.GetSunset()); //output sunset

            System.Console.WriteLine("Press enter to exit.");
            System.Console.ReadLine();
        }
    }
}

VB.NET

mports Zmanim.TzDatebase 'in Zmanim.TzDatebase.dll assembly
Imports Zmanim.Utilities
Imports Zmanim.TimeZone

Module Module1

    Sub Main()
        Dim locationName As String = "Lakewood, NJ"
        Dim latitude As Double = 40.09596 'Lakewood, NJ
        Dim longitude As Double = -74.22213 'Lakewood, NJ
        Dim elevation As Double = 0 'optional elevation
        Dim timeZone As ITimeZone = New OlsonTimeZone("America/New_York")
        Dim location As New GeoLocation(locationName, latitude, longitude, elevation, timeZone)
        Dim zc As New ComplexZmanimCalendar(location)
        'optionally set it to a specific date with a year, month and day
        'Dim zc As New ComplexZmanimCalendar(New DateTime(1969, 2, 8), location)
        System.Console.WriteLine("Today's Zmanim for " & locationName)
        System.Console.WriteLine("Sunrise: " & zc.GetSunrise().ToString)
        'output sunrise
        System.Console.WriteLine("Sof Zman Shema MGA: " & zc.GetSofZmanShmaMGA().ToString)
        'output Sof Zman Shema MGA
        System.Console.WriteLine("Sof Zman Shema GRA: " & zc.GetSofZmanShmaGRA().ToString)
        'output Sof Zman Shema GRA
        System.Console.WriteLine("Sunset: " & zc.GetSunset().ToString)
        'output sunset
        System.Console.WriteLine("Press enter to exit.")
        System.Console.ReadLine()

    End Sub

End Module

The current Zmanim .NET TODO list for the project includes:

  • Remove dependency to Java (IKVM assemblies)
  • The API should follow the .NET guidelines
  • Make it Linq friendly
  • Add examples how to use this project in a ASP.NET MVC site and WPF Application
  • Try to get it to work on Silverlight