Jollyday
Jollyday - A worldwide public holidays library
Install / Use
/learn @focus-shift/JollydayREADME
Jollyday 
Jollyday is a Java library to query public holidays. Currently, we support over 100 countries.
Note: the main branch contains the 2.x release line of Jollyday. The legacy 1.x branch continues the 1.x line is available at 1.x. A migration guide for upgrading to 2.0 is available in the project wiki: Jollyday 2.0 Migration Guide.
How to use it
Jollyday is based on Java 17 and can be used directly as dependency via maven or Gradle e.g. The calculation basis of the public holidays for each country is based on an XML file and will be mapped via Jakarta XML Binding or Jackson. If you already use one of these libraries in your project than just use the specific jollyday dependency.
<details> <summary>Maven (click to expand)</summary>You need the core library, that defines all functionality and the api for you as developer.
<dependency>
<groupId>de.focus-shift</groupId>
<artifactId>jollyday-core</artifactId>
<version>${version}</version>
</dependency>
XML-Binding libraries
Additionally, the XML-Binding library of your choice. At the moment we do support JAXB and Jackson, but in the future there could be more that these.
Jakarta XML Binding (JAXB)
<dependency>
<groupId>de.focus-shift</groupId>
<artifactId>jollyday-jaxb</artifactId>
<version>${version}</version>
</dependency>
Jackson
<dependency>
<groupId>de.focus-shift</groupId>
<artifactId>jollyday-jackson</artifactId>
<version>${version}</version>
</dependency>
You need the core library, that defines all functionality and the api for you as developer.
implementation group: 'de.focus-shift', name: 'jollyday-core', version: '${version}'
XML-Binding libraries
Additionally, the XML-Binding library of your choice. At the moment we do support JAXB and Jackson, but in the future there could be more that these.
Jakarta XML Binding (JAXB)
implementation group: 'de.focus-shift', name: 'jollyday-jaxb', version: '${version}'
Jackson
implementation group: 'de.focus-shift', name: 'jollyday-jackson', version: '${version}'
If you want to use Jollyday in a project that is modularized via java modules you need to require the de.focus_shift.jollyday.core module via
module your.application {
...
requires de.focus_shift.jollyday.core;
...
}
Examples
<details> <summary>Retrieve public holidays for a year (click to expand)</summary>Returns all german public holidays in 2022
import de.focus_shift.jollyday.core.Holiday;
import de.focus_shift.jollyday.core.HolidayManager;
import de.focus_shift.jollyday.core.ManagerParameters;
import java.util.Set;
import static de.focus_shift.jollyday.core.HolidayCalendar.GERMANY;
final HolidayManager holidayManager = HolidayManager.getInstance(ManagerParameters.create(GERMANY));
final Set<Holiday> holidays = holidayManager.getHolidays(Year.of(2022));
Returns all german public holidays from the 15th of april in 2022 until the 31st of may in 2023
import de.focus_shift.jollyday.core.Holiday;
import de.focus_shift.jollyday.core.HolidayManager;
import de.focus_shift.jollyday.core.ManagerParameters;
import java.time.LocalDate;
import java.util.Set;
import static de.focus_shift.jollyday.core.HolidayCalendar.GERMANY;
final HolidayManager holidayManager = HolidayManager.getInstance(ManagerParameters.create(GERMANY));
final Set<Holiday> holidays = holidayManager.getHolidays(LocalDate.of(2022, 4, 15), LocalDate.of(2023, 5, 31));
Returns true or false if a date is a public holidays in Germany.
import de.focus_shift.jollyday.core.HolidayManager;
import de.focus_shift.jollyday.core.ManagerParameters;
import java.time.LocalDate;
import static de.focus_shift.jollyday.core.HolidayCalendar.GERMANY;
final HolidayManager holidayManager = HolidayManager.getInstance(ManagerParameters.create(GERMANY));
final boolean isHoliday = holidayManager.isHoliday(LocalDate.of(2022, 6, 6));
Returns true or false if a date is a public holidays in Baden-Württemberg in Germany.
import de.focus_shift.jollyday.core.HolidayManager;
import de.focus_shift.jollyday.core.ManagerParameters;
import java.time.LocalDate;
import static de.focus_shift.jollyday.core.HolidayCalendar.GERMANY;
final HolidayManager holidayManager = HolidayManager.getInstance(ManagerParameters.create(GERMANY));
final boolean isHoliday = holidayManager.isHoliday(LocalDate.of(2022, 6, 6), "bw");
If you want to override the public holidays of a provided country like Germany, you need to put a holiday file
under the path holidays/ and name it Holidays_de.xml on your classpath. Jollyday will pick up yours at first.
The file and the hierarchy need to be identical to the one you want to override.
The holiday file structure needs to look like the one below. The XML Schema Definition file can be viewed here
<?xml version="1.0" encoding="UTF-8"?>
<Configuration hierarchy="de" description="Germany"
xmlns="https://focus_shift.de/jollyday/schema/holiday"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="https://focus_shift.de/jollyday/schema/holiday https://focus_shift.de/jollyday/schema/holiday/holiday.xsd">
<Holidays>
<!-- Add the holidays here-->
</Holidays>
...
<SubConfigurations hierarchy="bw" description="Baden-Württemberg">
<Holidays>
...
</Holidays>
</SubConfigurations>
</Configuration>
Configuration
Providing own configuration
The configuration resides within the jollyday.properties and can be overridden or added:
import de.focus_shift.jollyday.core.Holiday;
import de.focus_shift.jollyday.core.HolidayManager;
import de.focus_shift.jollyday.core.ManagerParameters;
import static de.focus_shift.jollyday.core.HolidayCalendar.GERMANY;
final ManagerParameter managerParameter = ManagerParameters.create(GERMANY);
managerParameter.setProperty("manager.impl", "de.focus_shift.jollyday.core.impl.SpecialHolidayManager");
The ManagerParameters can be used to add new or override existing configuration.
This will override the via own Configuration Provider Classes, via own jollyday.properties and the via url specified configurations.
</details> <details> <summary>via own Configuration Provider Classes (click to expand)</summary>Providing a comma separated list of classes through the system property de.focus_shift.jollyday.config.providers
which implement the ConfigurationProvider interface.
This will override the via own jollyday.properties and the via url specified configurations.
-Dde.focus_shift.jollyday.config.providers=some.package.name.MyConfigurationProvider,some.other.package.AnotherConfigurationProvider
Providing a comma separated list of urls through the system property de.focus_shift.jollyday.config.urls which point
to configuration files.
This will override the via own jollyday.properties specified configurations.
-Dde.focus_shift.jollyday.config.urls=file:/some/path/new.properties,http://myserver/some/path/further.properties,jar:file:myLibrary.jar!/my.properties
You can define your own jollyday.properties in your classpath, e.g. in a spring boot application in the ressource directory.
This will override the base jollyday.properties provided by jollyday itself.
Providing own implementations
<details> <summary>of Holiday Manager (click to expand)</summary> A manager implementation extends the abstract `HolidayManager` class and does the actual holiday parsing. The basic API properties are used to define the manager implementation class used for the specific country the manager is created for.manager.impl=de.focus_shift.jollyday.core.impl.DefaultHolidayManager
This configuration defines a manager implementation class used a
