Temporal Property

Example: Using a Temporal Collection (Java)

A temporal collection is a simple way to implement a Temporal Property. The basic representation and interface for a temporal collection is similar to a map: provide a get and put operation that uses a date as an index. Indeed a map makes a good backing collection for it.

class TemporalCollection...

  private Map contents = new HashMap();
  public Object get(MfDate when) {
    /** returns the value that was effective on the given date */
    Iterator it = milestones().iterator();
    while (it.hasNext()) {
      MfDate thisDate = (MfDate) it.next();
      if (thisDate.before(when) || thisDate.equals(when)) return contents.get(thisDate);
    }
    throw new IllegalArgumentException("no records that early");
  }
  public void put(MfDate at, Object item) {
    /** the item is valid from the supplied date onwards */
    contents.put(at,item);
    clearMilestoneCache();
  }

The map contains the values indexed by the start date of when they become effective. The milestones method returns these keys in reverse order. The get method then works through these milestones to find the right key. This algorithm works best when you are more likely to ask for the most recent value.

If you access the temporal collection more often than you update it, it may be worth caching the milestones collection.

class TemporalCollection...

  private List _milestoneCache;
  private List milestones() {
    /** a list of all the dates where the value changed, returned in order
    latest first */
    if (_milestoneCache == null)
      calculateMilestones();
    return _milestoneCache;
  }
  private void calculateMilestones() {
    _milestoneCache = new ArrayList(contents.size());
    _milestoneCache.addAll(contents.keySet());
    Collections.sort(_milestoneCache, Collections.reverseOrder());
  }
  private void clearMilestoneCache() {
    _milestoneCache = null;
  }

When you have a temporal collection written, then it is easy to make a temporal collection of addresses for a customer.

class Customer...

  private TemporalCollection addresses = new SingleTemporalCollection();
  public Address getAddress(MfDate date) {
    return (Address) addresses.get(date);
  }
  public Address getAddress() {
    return getAddress(MfDate.today());
  }
  public void putAddress(MfDate date, Address value) {
    addresses.put(date, value);
  }

One of the biggest problems using the temporal collection is if you have to persist the collection into a relational database - the mapping to tables is not exactly straightforward. Essentially the relational database needs to use Effectivity. This often means that you'll need to create an intersection table as a place for the date range. Some of this code can be generalized to the temporal collection class, but some explicit mapping code will be needed.

Example: Implementing a Bi-temporal Property (Java)

Before thinking about how a Bi-temporal property works, it's worth thinking about what it must do. Essentially the bi-temporal property allows us to store historic information over time and retain a full history across both dimensions. So we build up a history like this.

class Tester...

  private Customer martin;
  private Address franklin = new Address ("961 Franklin St");
  private Address worcester = new Address ("88 Worcester St");
  public void setUp () {
    MfDate.setToday(new MfDate(1996,1,1));
    martin = new Customer ("Martin");
    martin.putAddress(new MfDate(1994, 3, 1), worcester);
    MfDate.setToday(new MfDate(1996,8,10));
    martin.putAddress(new MfDate(1996, 7, 4), franklin);
    MfDate.setToday(new MfDate(2000,9,11));
  }

Notice the rhythm to the updates. When we are storing bi-temporal history the record date is always today. So in our tests we change the current date first and then store information in the history. As we put information into the history we supply the actual date.

The resulting history looks like this.

class Tester...

  private MfDate jul1 = new MfDate(1996, 7, 1);
  private MfDate jul15 = new MfDate(1996, 7, 15);
  private MfDate aug1 = new MfDate(1996, 8, 1);
  private MfDate aug10 = new MfDate(1996, 8, 10);
  public void testSimpleBitemporal () {
    assertEquals("jul1 as at aug 1", worcester, martin.getAddress(jul1, aug1));
    assertEquals("jul1 as at aug 10",worcester, martin.getAddress(jul1, aug10));
    assertEquals("jul1 as at now",worcester, martin.getAddress(jul1));

    assertEquals("jul15 as at aug 1", worcester, martin.getAddress(jul15, aug1));
    assertEquals("jul15 as at aug 10",franklin, martin.getAddress(jul15, aug10));
    assertEquals("jul15 as at now",franklin, martin.getAddress(jul15));
  }

Just as you can implement much of the complexity of temporal properties by using a temporal collection, similarly you can define a bi-temporal collection to handle much of the complexities of bi-temporal properties.

Essentially a bi-temporal collection is a temporal collection whose elements are temporal collections. Each temporal collection is a picture of record history.

We'll look at how you get information out of the collection first. The latest temporal collection represents the actual history whose record date is now. So a getting method that only has a actual date uses this current actual history.

class BitemporalCollection...

  private SingleTemporalCollection contents = new SingleTemporalCollection();
  public BitemporalCollection() {
    contents.put(MfDate.today(), new SingleTemporalCollection());
  }
  public Object get(MfDate when) {
    return currentValidHistory().get(when);
  }
  private SingleTemporalCollection currentValidHistory() {
    return (SingleTemporalCollection) contents.get();
  }

(The class SingleTemporalCollection is just the vanilla temporal collection I discussed above, I'll explain the relationship between the two later.)

To to get a true bi-temporal value, we use a getter with both actual and record dates.

class BitemporalCollection...

  public Object get(MfDate validDate, MfDate transactionDate) {
    return validHistoryAt(transactionDate).get(validDate);
  }
  private TemporalCollection validHistoryAt(MfDate transactionDate) {
    return (TemporalCollection) contents.get(transactionDate);
  }

We can then use the bi-temporal collection in a domain class.

class Customer...

  BitemporalCollection addresses = new BitemporalCollection();
  public Address getAddress(MfDate actualDate) {
    return (Address) addresses.get(actualDate);
  }
  public Address getAddress(MfDate actualDate, MfDate recordDate) {
    return (Address) addresses.get(actualDate, recordDate);
  }
  public Address getAddress() {
    return (Address) addresses.get();
  }

Each time we update the collection, we need to keep the old copy of the actual history.

class BitemporalCollection...

  public void put(MfDate validDate, Object item) {
    contents.put(MfDate.today(), currentValidHistory().copy());
    currentValidHistory().put(validDate,item);
  }
  public void put(Object item) {
    put(MfDate.today(),item);
  }

The bi-temporal collection supports a very similar interface to a one dimensional temporal collection. So we can make an interface for temporal collection and provide separate implementations for the one dimensional and two dimensional collections. This allows bi-temporal collections to be substitutable for one dimensional temporal collections, which makes it easy to refactor a single dimensional temporal property into a bi-temporal property.

In this case I'm using Time Point with a date granularity for both the actual and record dates. Although this makes the example simpler to write, it may be better to use a finer granularity for the record time. The issue here is that if you modify a record at 2pm, run a billing process at 3pm and then modify it again at 4pm. With the current implementation the appropriate value, while not completely lost, is not easy to get to. Another approach, often used in business, is only to do things like billing at the end of a business day and not to allow any further updates on that day after billing is done. Post billing updates are then given a record date of the day after billing is done. Again this kind of functionality can easily be added to the appropriate temporal collection classes.