DateTimeFields modified by Stephen Colebourne

Stephen Colebourne — Thu, 22 May 2014 22:08:09 -0000

There are two types of field under discussion - calendar and duration.

Duration fields
Calendar fields
Enums

Duration fields

Such as years or minutes.

It is desirable to be able to represent this information in a type-safe way, so that you cannot confuse seconds with minutes and so on. There are three potential parts to any field:

the unit-safe value, such as "8 months" (as opposed to "7 months", exclusively ISO calendar system)
the unit, such as months (as opposed to minutes, exclusively ISO calendar system)
the cross calendar system concept, such as "months" which could be gregorian, coptic, persian...

The options for duration fields are:

Option 1 - int

The simple option is to use an int to represent the duration field. This option is not unit-safe, as only javadoc tells the user whether a given value is seconds or hours. This is a potential source of bugs.

 int timeout = 6;  // seconds
 public abstract int phoneCallDuration();  // what does this return?
 Duration d = ...;
 int seconds = d.getSeconds();

Option 2 - wrapper class

The most type-safe option is a wrapper class for each field.

This option is unit-safe, and makes it much harder for different fields to be confused. The downside is that one class must be written and used for each field, which makes the javadoc API appear complex. In reality, the API only consists of the concept of a field, there just happen to be a lot of implementations.

 Seconds timeout = seconds(6);
 public abstract Seconds phoneCallDuration();
 Duration d = ...;
 Seconds seconds = d.getSeconds();

Option 3 - generics

The generics option is a single field class with a generic parameter.

This option is unit-safe (assuming generics are used corrrectly), making it much harder for different fields to be confused. The main API only has one class for the field, however the generic parameter still needs to be a class. As a result, the classes for Seconds, Days etc from option 2 still need to be present, however in this case they do not serve any real purpose. The danger is that a user will define a method to take in Days, which will be confusing and pointless as the class is only designed for use as a generic parameter.

 DurationField&lt;Seconds&gt; timeout = seconds(6);
 public abstract DurationField&lt;Seconds&gt; phoneCallDuration();
 Duration d = ...;
 DurationField&lt;Seconds&gt; seconds = d.getSeconds();

Option 4 - JSR-275

This option is to use the classes in JSR-275.

This option is unit-safe, but not unit-explicit. The API that the user works with is in terms of the JSR-275 duration. The unit (seconds) can be queried from the API, but is not part of the code that a user writes. If I understand correctly, auto conversion occurs between units when required.

 Measure&lt;Integer, Duration&gt; timeout = seconds(6);
 public abstract Measure&lt;Integer, Duration&gt; phoneCallDuration();
 Duration d = ...;
 Measure&lt;Integer, Duration&gt; seconds = d.getSeconds();

 Measurable&lt;Duration&gt; timeout = Measure.value(6, SECOND);
 public abstract Measurable&lt;Duration&gt; phoneCallDuration();
 Measurable&lt;Duration&gt; d = phoneCallDuration();
 int seconds = d.intValue(SECOND);

Calendar fields

Such as dayOfWeek or hourOfDay.

The options are similar to duration but complicated by having two possible fields. It is desirable to be able to represent this information in a type-safe way, so that you cannot confuse secondOfMinute with minuteOfHour and so on. There are three potential parts to any field:

the field-safe value, such as "8th dayOfMonth" (as opposed to "7th dayOfMonth", exclusively ISO calendar system)
the field iteself, such as dayOfMonth (as opposed to dayOfWeek, exclusively ISO calendar system)
the cross calendar system concept, such as "dayOfMonth" which could be gregorian, coptic, persian...

The options for calendar fields are:

Option 1 - int

The simple option is to use an int to represent the calendar field. This option is not field-safe, as only javadoc tells the user whether a given value is secondOfMinute or hourOfDay. This is a potential source of bugs, and particularly annoying when passing fields into methods (as Java has no named parameters).

 int dayOfMonth = 6;  // day of month
 public void createDate(int year, int month, int day);  // very easy to pass fields in wrong order
 CalendarDate d = ...;
 int dayOfMonth = d.getDayOfMonth();

Option 1B - int and Enum

Some fields are well suited to Enums, like !MonthOfYear and !DayOfWeek. Option 1B is to use Enum where appropriate and int elsewhere.

 int dayOfMonth = d.getDayOfMonth();
 MonthOfYear month = d.getMonthOfYear();

Option 2 - wrapper class

The most type-safe option is a wrapper class for each field.

This option is field-safe, and makes it much harder for different fields to be confused. The downside is that one class must be written and used for each field, which makes the javadoc API appear complex. In reality, the API only consists of the concept of a field, there just happen to be a lot of implementations.

 DayOfMonth dom = dayOfMonth(6);
 public void createDate(Year year, MonthOfYear month, DayOfMonth day);
 CalendarDate d = ...;
 DayOfMonth dayOfMonth = d.getDayOfMonth();

Option 3 - generics

The generics option is a single field class with generic parameters.

This option is field-safe (assuming generics are used corrrectly), making it much harder for different fields to be confused. The main API only has one class for the field, however the generic parameters still needs to be classes. The generic parameters are one for each concept (shared with duration fields), which are combined to represent the unit and range of the field. The generics add significantly to the complexity of the field. They can also be misused, as you could enter the generic parameters the wrong way around (range before unit).

 CalendarField&lt;Day, Month&gt; timeout = seconds(6);
 public void createDate(CalendarField&lt;Year, Forever&gt; year, CalendarField&lt;Month, Year&gt; month, CalendarField&lt;Day, Month&gt; day);
 CalendarDate d = ...;
 CalendarField&lt;Day, Month&gt; dayOfMonth = d.getDayOfMonth();

Enums

It should be noted that certain calendar fields are well suited to Enums:

DayOfWeek
MonthOfYear
Era (AD/BC - although that gives us problems with BCE/CE)
Meridian (AM/PM)

Home page

Recent changes to DateTimeFields

DateTimeFields modified by Stephen Colebourne

Duration fields

Option 1 - int

Option 2 - wrapper class

Option 3 - generics

Option 4 - JSR-275

Calendar fields

Option 1 - int

Option 1B - int and Enum

Option 2 - wrapper class

Option 3 - generics

Enums