business-hours-java

This java library helps dealing with business hours, such as "Monday through Friday from 9am to 6pm, and from 9am to 12pm on Saturdays".

What does it do ?

• It tells you if the business is open at any given time:

  boolean open = businessHours.isOpen(LocalDateTime.now());

• It tells you how long it will be before the next business opening:

  long secondsToOpening = businessHours.timeBeforeOpening(LocalDateTime.now(), ChronoUnit.SECONDS);

• If you need to perform specific actions at each business opening, it gives you cron expressions that will fire at each opening time. You can feed them to Cron4j, Quartz or Spring to schedule whatever you fancy.

  Set<String> cronExpressions = businessHours.getOpeningCrons();

  For instance, new BusinessHours("wday{Mon-Fri} hr{9-18}").getOpeningCrons() will return a single cron expression: 0 9 * * 1-5.
  Consider a business open on Wednesdays and Thursdays from 21pm to 3am. It opens on Wednesdays and Thursdays at 21pm, but also on Wednesdays at midnight.
  new BusinessHours("wday{We-Th} hr{21-3}").getOpeningCrons() will thus return two cron expressions: 0 0 * * 3 and 0 21 * * 3-4.

How do I get a BusinessHours instance ?

Simply call the BusinessHours constructor:

BusinessHours businessHours = new BusinessHours("wday{Mon-Fri} hour{9am-6pm}, wday{Sat} hour{9am-12pm}");

The constructor argument is a String representation of the business hours which must adhere to the format:

sub-period[, sub-period...]

If the period is blank, then the business is supposed to be always open.
A sub-period is of the form:

  scale {range [range ...]} [scale {range [range ...]}]

Scale must be one of three different scales (or their equivalent codes):

Scale	Scale code	Valid range values
wday	wd	1 (Monday) to 7 (Sunday) or mo, tu, we, th, fr, sa, su
hour	hr	0-23 or 12am 1am-11am 12noon 12pm 1pm-11pm
minute	min	0-59

The same scale type may be specified multiple times. Additional scales simply extend the range defined by previous scales of the same type.
The range for a given scale must be a valid value in the form of v or v-v.
For the range specification v-v, if the second value is larger than the first value, the range wraps around.
v isn't a point in time. In the context of the hour scale, 9 specifies the time period from 9:00 am to 9:59. This is what most people would call 9-10.

Note that whitespaces can be anywhere. Furthermore, when using letters to specify week days, only the first two are significant and the case is not important: Sunday or Sun are valid specifications for su.

Examples:

To specify business hours that go from Monday through Friday, 9am to 5pm:

wd {Mon-Fri} hr {9am-4pm}

To specify business hours that go from Monday through Friday, 9am to 5pm on Monday, Wednesday, and Friday, and 9am to 3pm on Tuesday and Thursday, use a period such as:

wd {Mon Wed Fri} hr {9am-4pm}, wd{Tue Thu} hr {9am-2pm}

To specify business hours open every other half-hour, use something like:

minute { 0-29 }

To specify the morning, use:

hour { 12am-11am }

Remember, 11am is not 11:00am, but rather 11:00am - 11:59am.

Dependency Management

The project binaries are available in Maven Central. Just add the following to your maven configuration or taylor to your own dependency management system.

<dependency>
    <groupId>org.dhatim</groupId>
    <artifactId>business-hours</artifactId>
    <version>1.0.0</version>
</dependency>

Javadoc

The librairy javadoc can be found here.

Credits

The string representation of business hours and its associated documentation are strongly inpired from Patrick Ryan's Time::Period Perl module.