Adding the new entryattribute is quite simple. We just need to make sure we include the defaulter method so that old sensor data have a value for this field.

<sensordatatypes>
  <sensordatatype name="SimpleSdt"
                  enabled="true"
                  wrapper="org.hackystat.doc.simplesdt.SimpleSdt"
                  shellcommand="org.hackystat.doc.simplesdt.SimpleSdtShellCommand"
                  docstring="Simple sensor data type."
                  contact="Philip Johnson (johnson@hawaii.edu)">
    <entryattribute name="fileName" />
    <entryattribute name="location" 
                    defaulter="org.hackystat.doc.simplesdt.SimpleSdt.getDefaultLocation" />
    <entryattribute name="elapsedTime" 
                    type="java.lang.Integer"
                    converter="org.hackystat.doc.simplesdt.SimpleSdt.getInteger"
                    defaulter="org.hackystat.doc.simplesdt.SimpleSdt.getDefaultElapsedTime" />
  </sensordatatype>
</sensordatatypes>

Again, this is quite straightforward. Here is the modified wrapper class implementation with two additional methods: getLocation and getDefaultLocation:

package org.hackystat.doc.simplesdt;

public class SimpleSdt extends SensorDataEntry {

  public SimpleSdt (Map keyValStringMap, SensorDataType sdt) throws SensorDataException {
    super(keyValStringMap, sdt);
  }

  public String getFileName() {
    return this.getAttributeValue("fileName");
  }

  public String getLocation() {
    return this.getAttributeValue("location");
  }

  public int getElapsedTime() {
    return ((Integer)(this.getConvertedAttributeValue("elapsedTime"))).intValue();
  }
  
  public String getErrors() {
    String errorMessage = "";
    if (getFileName() == null) { errorMessage += "Invalid fileName; "; }
    if (getElapsedTime() <= 0) { errorMessage += "Invalid elapsed time; "; }
    return (errorMessage == "") ? null : errorMessage;
  }
  
  public static Integer getInteger(String intString) {
    return new Integer(intString);
  }

  public static String getDefaultElapsedTime() {
    return "100";
  }

  public static String getDefaultLocation() {
    return "unknown";
  }
  
  public List getFilePaths() {
    List filePaths = new ArrayList();
    filePaths.add(getFileName());
    return filePaths;
  }
}  

Here is what the new getHelpString method would look like, with the location field added as an optional field:

  public String getHelpString() {
    return
    "SimpleSdt#set#tool=<tool>" + cr +
    "  Sets the Tool attribute value used in subsequent SimpleSdt sensor shell commands." + cr +
    "SimpleSdt#add#<key1>=<value1>#<key2>=<value2>#..." + cr +
    "  <keyN> is: fileName, elapsedTime, [location], [tool], [pMap]." + cr;
  }

Finally, we must update the test case to check that our SDT functions both with and without the location field. The first change is to the testSDT method, which should now check for the default value of location:

  public void testSDT() throws Exception {
    keyValStringMap.clear();
    keyValStringMap.put("tool", tool);
    keyValStringMap.put("tstamp", String.valueOf(timestamp.getTime()));
    keyValStringMap.put("fileName", fileName);
    keyValStringMap.put("elapsedTime", elapsedTimeString);
    pMap.put("environment", macOSX);
    keyValStringMap.put("pMap", pMap.encode());

    SimpleSdt entry = (SimpleSdt) SensorDataEntryFactory.getEntry(sensorType, keyValStringMap);

    assertEquals("Checking timestamp", timestamp, entry.getTimestamp());
    assertEquals("Checking tool", tool, entry.getTool());
    assertEquals("Checking fileName", fileName, entry.getFileName());
    assertEquals("Checking elapsedTime", 1000, entry.getElapsedTime());
    assertEquals("Checking environment", macOSX, entry.getProperty("environment"));
    assertEquals("Checking default location", "unknown", entry.getLocation());
  }

One should also implement a new test method that sets the location explicitly and tests that it is retrieved correctly, as illustrated next.

  public void testSDTWithLocation() throws Exception {
    String location = "Honolulu, HI";
    keyValStringMap.clear();
    keyValStringMap.put("tool", tool);
    keyValStringMap.put("tstamp", String.valueOf(timestamp.getTime()));
    keyValStringMap.put("fileName", fileName);
    keyValStringMap.put("elapsedTime", elapsedTimeString);
    keyValStringMap.put("location", location);
    pMap.put("environment", macOSX);
    keyValStringMap.put("pMap", pMap.encode());

    SimpleSdt entry = (SimpleSdt) SensorDataEntryFactory.getEntry(sensorType, keyValStringMap);

    assertEquals("Checking timestamp", timestamp, entry.getTimestamp());
    assertEquals("Checking tool", tool, entry.getTool());
    assertEquals("Checking fileName", fileName, entry.getFileName());
    assertEquals("Checking elapsedTime", 1000, entry.getElapsedTime());
    assertEquals("Checking environment", macOSX, entry.getProperty("environment"));
    assertEquals("Checking location", location, entry.getLocation());
  }

This part is quite easy: it just returns the sdt.simplesdt.xml file and its wrapper class to its original state.

Here is what such a reorganizeData method would look like:

  public void reorganizeData() {
    if (hasAttributeValue("location")) {
      this.putProperty("location", this.getAttributeValue("location"));
    }
  }

Properly evolving an SDT in a way that minimizes the ripple effect can be quite challenging. Consider the above example where the location field has moved from a "required" entryattribute to an "optional" property on the pMap. There are a number of implications of this change.

First, analysis code that depended upon the location entryattribute may no longer compile. Previously, the analysis code could access the location field using the getLocation method, as illustrated below.

SimpleSdt entry = // get a SimpleSdt instance somehow
String location = entry.getLocation()

After the change, the location field (if it exists) must be accessed by analysis code using the getProperty method:

String location = entry.getProperty("location")

However, note a more subtle difference: before the evolution, the getLocation() method would always return a String value, which would default to "unknown". After the evolution, the location variable could be null if the property is not present. This could result in run-time null pointer exceptions in analysis code at unpredictable times.

There are a number of ways to deal with this kind of issue. One approach is to keep the getLocation accessor in the SDT definition, but rewrite it to mimic the prior behavior:

  public String getLocation() {
    return this.getProperty("location", "unknown");
  }

Note that this code uses an alternative form of the getProperty method that allows a default value to be returned. A more dramatic approach might be to throw an exception if the analysis code invokes getLocation on an entry that does not have location data:

  public String getLocation() throws Exception {
    String location = this.getProperty("location");
    if (location == null) {
      throw new Exception("Attempt to access missing location data.");
    }
    return location;
  }

In this case, analysis code would need to explicitly check for the presence of the location field:

if (entry.hasProperty("location") {
  String location = entry.getLocation();
  // continue processing
}