dorkhub
show your thing

jollyday

Jollyday - A worldwide public holidays library

focus-shift
Java★ 134⑂ 35 forksApache-2.0updated 1 day ago
bank-holidayscalculate-holidayscalendarhacktoberfestholidayholiday-apiholidayapiholidays
git clone https://github.com/focus-shift/jollyday.gitfocus-shift/jollyday
README.mdfork it — it’s yours

Jollyday Build Status Coverage Maven Central Javadocs

Jollyday is a Java library to query public holidays. Currently, we support over 230 countries.

World map with countries colored in blue that are supported by jollyday

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.

Maven (click to expand)

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>
Gradle (click to expand)

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}'
with the Java Platform Module System (click to expand)

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

Retrieve public holidays for a year (click to expand)

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));
Retrieve public holidays for a period of days (click to expand)

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));
Check if a specific date is a public holiday (click to expand)

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");
Override an existing country (click to expand)

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:

via ManagerParameter (click to expand) 
  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.

via own Configuration Provider Classes (click to expand)

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
via url (click to expand)

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
via own `jollyday.properties` (click to expand)

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

of Holiday Manager (click to expand) 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 as a default for every country. You can define a manager implementation on a per country base.

manager.impl=de.focus_shift.jollyday.core.impl.XMLManager
manager.impl.us=de.focus_shift.jollyday.core.impl.MyXMLManager

This will let the MyXMLManager class be used for calculating US holidays and the XMLManager for all other countries.

of Holiday Parser (click to expand)

A parser implementation is used for parsing the XML file content. There are several parsers configured depending on the class to parse the info from.

parser.impl.de.focus_shift.jollyday.core.spi.FixedHolidayConfiguration                       = de.focus_shift.jollyday.core.parser.impl.FixedParser
parser.impl.de.focus_shift.jollyday.core.spi.FixedWeekdayInMonthHolidayConfiguration         = de.focus_shift.jollyday.core.parser.impl.FixedWeekdayInMonthParser
parser.impl.de.focus_shift.jollyday.core.spi.IslamicHolidayConfiguration                     = de.focus_shift.jollyday.core.parser.impl.IslamicHolidayParser
parser.impl.de.focus_shift.jollyday.core.spi.ChristianHolidayConfiguration                   = de.focus_shift.jollyday.core.parser.impl.ChristianHolidayParser
parser.impl.de.focus_shift.jollyday.core.spi.RelativeToFixedHolidayConfiguration             = de.focus_shift.jollyday.core.parser.impl.RelativeToFixedParser
parser.impl.de.focus_shift.jollyday.core.spi.RelativeToWeekdayInMonthHolidayConfiguration    = de.focus_shift.jollyday.core.parser.impl.RelativeToWeekdayInMonthParser
parser.impl.de.focus_shift.jollyday.core.spi.FixedWeekdayBetweenFixedHolidayConfiguration    = de.focus_shift.jollyday.core.parser.impl.FixedWeekdayBetweenFixedParser
parser.impl.de.focus_shift.jollyday.core.spi.FixedWeekdayRelativeToFixedHolidayConfiguration = de.focus_shift.jollyday.core.parser.impl.FixedWeekdayRelativeToFixedParser
parser.impl.de.focus_shift.jollyday.core.spi.EthiopianOrthodoxHolidayConfiguration           = de.focus_shift.jollyday.core.parser.impl.EthiopianOrthodoxHolidayParser
parser.impl.de.focus_shift.jollyday.core.spi.RelativeToEasterSundayHolidayConfiguration      = de.focus_shift.jollyday.core.parser.impl.RelativeToEasterSundayParser

The configuration property name starts with parser.impl and finishes with the XML class name. The value is the parser implementation class name which implements the HolidayParser interface.

of Configuration Service (click to expand) A configuration service implementation is used to define which XML unmarshalling implementation should be used 
configuration.service.impl = de.focus_shift.jollyday.jackson.JacksonConfigurationService

The configuration property configuration.service.impl contains the class name as string. The value is the configuration service implementation class name which implements the HolidayCalendarConfigurationService interface.

Values are:

  • de.focus_shift.jollyday.jackson.JacksonConfigurationService (default)
  • de.focus_shift.jollyday.jaxb.JaxbConfigurationService

ISO 3166

To retrieve the public holidays of a country the ISO 3166-1 alpha-2 standard is used. A list of current ISO 3166-1 alpha-2 codes is available at wikipedia.

To access the public holidays of a subdivision of a country, e.g. Baden-Württemberg of Germany the ISO 3166-2 standard is used. A list of current ISO 3166-2 codes is available at wikipedia.

Data precision

Precision Supported
Country (ISO 3166-1 alpha-2) Yes
Subdivisions (ISO 3166-2) Yes
City Holiday Yes

Financial market calendars

Besides countries, jollyday also supports the closing days of a few financial markets/systems. These are addressed via the constants of HolidayCalendar (not via an ISO 3166 code) and can be used like any other calendar, e.g. HolidayManager.getInstance(ManagerParameters.create(HolidayCalendar.NYSE)).

Calendar HolidayCalendar constant Hierarchy key
New York Stock Exchange (NYSE) NYSE nyse
New York Stock Exchange Euronext NYSE_EURONEXT nyse-euronext
London Metal Exchange (LME) LONDON_METAL_EXCHANGE lme
TARGET (Trans-European Automated Real-time Gross settlement Express Transfer system) TARGET target
TARGET2-Securities (T2S) TARGET2_SECURITIES target2-securities

Holiday types

The following holiday types are supported:

Public Holiday
Public holidays are days when most of the public enjoys a paid non-working days. These days are determined by local laws and regulations. Countries use various names for these official non-working days, such as:

Other Names for Public Holiday Country Businesses
Bank Holiday United Kingdom Closed
National Holiday Most Countries Closed
Red Days Norway Closed
Regular Holidays Philippines Closed
Restricted Holidays India Closed
Statutory Holiday Canada Closed

We will declare all of these as Public Holiday

Bank Holiday
Bank holidays are days when financial institutions and government offices (and government-regulated businesses) are closed as determined by local laws and regulations. Other businesses, such as offices and retail stores, may also be closed on these days, though are not mandated to by local laws and regulations.

Observance
Observance, is a celebration or commemoration that doesn't include a day off from work. When people celebrate or commemorate something, but do not have a day off from work for that reason, we call it an observance. There are different types of observance like Religious, Secular, Awareness, International or National observance. We will declare all of these as Observance

Development

If you want to support us at the development on jollyday than take a look at Contributing to jollyday. If you have any kind of questions please go to Discussions and see if there are already answers and if not please open a discussion with your question. If you want to raise an issue or bug you can create a new issue

Requirements

Architecture decision record (ADR)

git hooks (optional)

There are some app specific git hooks to automate stuff like:

  • Add 'closes #issue-number' to the commit message

If you want to take advantage of this automation you can run:

git config core.hooksPath '.githooks'

The git hooks can be found in the .githooks directory.

License

Apache License, Version 2.0

more like this

ForwardWidgets

Widgets for Douban and Trakt watchlists plus personalized recommendations, live TV streaming including PlutoTV, Yatu ra…

JavaScript★ 247
@huangxd-

markItDown

📱 A React app to preview and edit Markdown✍. You can also export it as HTML.

JavaScript★ 51
@aromalanil

search

search projects, people, and tags