Two data types to represent a period of time with NHibernate user types

Introdutcion

DateTimeRange and DateRange are two data types that represents a period of time with specific start and end points. DateTimeRange is a range of time that starts and ends with a specific date time, i.e., 8a.m. Jan 1, 08 to 10a.m. Jan 1, 08. DateRange is a range of time that starts and ends with specific dates, i.e., Jan 1, 08 to Jan 31, 08.

The classes

One of the power of these two classes is that they have useful functions in it. Here is the list:

• To easily define a period of a month or a quarter of a year: Other than the basic constructors, DateRange offers a set of static factory methods for you to create a certain period. Here are some examples:

DateTimeRange(DateTime? start, DateTime? end);
DateRange.ThisMonth();
DateRange.NextMonth();
DateRange.LastMonth();
DateRange.MonthOf(DateTime time);
DateRange.ThisQuarter();
...

• To easily compare two periods or a period with a DateTime: TimeRange has the following method for you to do a comparison.

bool LagerOrEqual(DateRange dr);
bool LaterEqualThanStart(DateTime? time)

bool EarlierEqualThanEnd(DateTime? time)

• To easily output the period to string using FormatString:

string ToString(string formatString);

Another strength of these types is that using the NHibernate user type, you can easily map and query a time range property. Class code example:

public class YourClass{
    private DateRange validePeriod;
    public DateRange ValidePeriod{

            get{return validePeriod;}  set{ validePeriod = value;}
    }
}

HBM file example:

<property name="ValidePeriod" 
          type="MindHarbor.TimeDataUtil.DateRangeUserType,MindHarbor.TimeDataUtil">
    <column name="RangeStart"/>
    <column name="RangeEnd" />

 </property>

You can query like this using HQL:

sess.CreateQuery("from YourClass ms where ms.ValidePeriod.Start = :d")
                .SetDateTime("d", d1.Value).List();

or you can query using Criteria:

IList result = sess.CreateCriteria(typeof(YourClass))
          .Add(Expression.Eq("ValidePeriod", new DateRange(d1, d5)))

Last but not least, DateRange and DateTimeRange supports open periods - periods with only one end: DateTimeRange(new DateTime(1,1, 2005), null) represents a time range that starts at Jan,1 2005 and lasts infinitely. This kind of an open period can also be queried.

Another special feature DateTimeRange supports is a WithinExpression to create a NHibernate ICriterion that the DateTimeRange property must be within this date time range. The following code queries for yourClass that has a ValidePreiod within the next 10 days.

DateRange fromTodayOn = new DateRange(DateTime.Today, DateTime.Today.AddDays(10));
sess.CreateCriteria(typeof (YourClass))

                .Add(fromTodayOn.WithinExpression("ValidePeriod"))
                .List();

The following code queries for yourClass that has a ValidePeriod later than today:

DateRange fromTodayOn = new DateRange(DateTime.Today, null);
sess.CreateCriteria(typeof (YourClass))
                .Add(fromTodayOn.WithinExpression("ValidePeriod"))
                .List();

These two types are included in an assembly called TimeDataUtil in the MindLib project. To use them, download the MindLib project from Sourceforge.net and copy the MindHarbor.TimeDataUtil.dll and the NHibernate related DLLs out of the bin folder. You can also find more sample code using it in the Unit test project: TimeDataUtil.Test which can be found in the MindLib source code package.