Quick News

ObjectLab Open Source News

Reminder: we have moved to GitHub .

2014-05-26 : version 1.3.0 is out and contains a couple of changes to make the usage of the interfaces more fluent but mainly includes a NEW MODULE FOR JDK8. We also officially released the objectlab-utils module for the first time, if you deal with BigDecimal, Collections etc and are fed up with nulls, this is for you! More info on the changes here .

2010-05-10 : version 1.2.0 is out and contains a couple of changes, including the ability to see the registered calendar and unregistering calendars (useful if calendars are dynamic). More info on the changes here . Also, one of the authors is on Twitter, follow your favorite Belgian at http://twitter.com/benoitx .

2007-03-25: version 1.1.0 is out and contains a couple of changes, a new HolidayHandler and the ability to define a valid range for the holiday (and if the calculation is beyond that range, an exception is thrown). This is done via HolidayCalendar which should replace the simple Set<E> for holidays. More info on the changes here .

ObjectLab Kit Introduction

ObjectLab Kit came out of our frustration to have to re-do the same kind of code over and over each time we joined a new company and Bank. Most banks will require basic Date calculation, we did spot another open source project for this but their licence forbids most financial institution from using it. This one is released under the business-friendly Apache 2.0 license. Digg!

Getting Started

DateCalc comes in 3 different implementations, both run on JDK 1.5 or higher :

Maven

If you're using Maven, setup is easy, as DateCalc is in the Maven Central Repository.

To use the JDK Version:

<dependency>
	<groupId>net.objectlab.kit</groupId>
	<artifactId>datecalc-common</artifactId>
	<version>1.3.0</version>
</dependency>
<dependency>
	<groupId>net.objectlab.kit</groupId>
	<artifactId>datecalc-jdk</artifactId>
	<version>1.3.0</version>
</dependency>
				

To use the JODA Version (recommended):

<dependency>
	<groupId>net.objectlab.kit</groupId>
	<artifactId>datecalc-common</artifactId>
	<version>1.3.0</version>
</dependency>
<dependency>
	<groupId>net.objectlab.kit</groupId>
	<artifactId>datecalc-joda</artifactId>
	<version>1.3.0</version>
</dependency>
				

To use the JDK8 Version:

<dependency>
	<groupId>net.objectlab.kit</groupId>
	<artifactId>datecalc-common</artifactId>
	<version>1.3.0</version>
</dependency>
<dependency>
	<groupId>net.objectlab.kit</groupId>
	<artifactId>datecalc-jdk8</artifactId>
	<version>1.3.0</version>
</dependency>
				

Download the Jars

If you are not using Maven, you can download the jars here .

Date Calculations? What is that?

Apart from the very basic "add days" features, most business have to deal with Holidays and what to do when a calculated day falls on a holiday . This library does not attempt to create or guess the holidays, we all know that some bank holidays can be decided at a moment's notice in some markets. All financial institutions or big business will have their own official list of 'holidays' anyway.

Furthermore, "weekends" also need to be handled and some market have a different week to the conventional Monday -> Friday, our library provides you with full flexibility to design a Working Week.

As such a Non-working Day can be a holiday or a 'weekend'.

Ok, what algorithm for handling a holiday do you support?

At the moment, we support the following 6 algorithms:

  1. Do Nothing , i.e. leave the date as-is, even if it is a non-working day.
  2. Forward , if the date is a non-working day, move forward to the next working day.
  3. Backward , if the date is a non-working day, move backward to the previous working day.
  4. Modified Following , if the date is a non-working day, move forward to the next working day, UNLESS it crosses over a new month, in which case we revert to find the last working day of the current month.
  5. Modified Preceeding , if the date is a non-working day, move backward to the previous working day, UNLESS it crosses over a new month, in which case we revert to find the next working day of the current month.
  6. ForwardUnlessNegative (new with v1.1.0), acts like a Forward algo unless the increment is negative, in which case it behaves like Backward.

See this page for some examples .

Main interfaces

The main interfaces are:

Here are the examples of how to get a DateCalculator "forward" for the "UK" holidays (if you have registered the holidays). The WorkingWeek is Mon-Fri by default.

JDK

2 implementations for Pure 'old' JDK have been released

  1. Calendar :
  2. Date :

JODA

2 implementations for Joda have been released

  1. LocalDate (recommended):
  2. YearMonthDay :

JDK8

1 implementations for JDK8 has been released

  1. LocalDate :

How do I use it?

There are several steps

  • Register holidays in the factory by calling registerHolidays(final String name, HolidayCalendar<Date> holidays)
  • Use the factory to get a DateCalculator with a given Handler (forward/backward etc), it is a disposable object that should not be shared accross threads, each thread should get its own!
  • when you get a DateCalculator, you can set the startDate, this sets the currentDate too. The startDate does not move. The current date is the result of your calculations. If the startDate is a non-working day, it may be moved automatically according to the HolidayHandler.
  • when you call moveByDays(..), moveByBusinessDays(..), moveByTenor the currentDate is moved in the Calculator.

Using Joda Time LocalDate

Using JDK Calendar

Using JDK8 LocalDate

Using Util Average

Using Util WeightedAverage

Using Util Pair

Similar usage for Triplet and Quadruplet (but you would probably better model those as proper domain classes).