Every sensor data type definition must include a file with the name "<moduleName>.<sdtName>.sdt.def.xml", which provides a declaration of your sensor data type in XML format.
Example Example 15.2, “The hackyDoc_SimpleSdt.simplesdt.sdt.def.xml file” shows what this file looks like for the SimpleSdt SDT:
Example 15.2. The hackyDoc_SimpleSdt.simplesdt.sdt.def.xml file
<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="elapsedTime"
type="java.lang.Integer"
converter="org.hackystat.doc.simplesdt.SimpleSdt.getInteger"
defaulter="org.hackystat.doc.simplesdt.SimpleSdt.getDefaultElapsedTime" />
</sensordatatype>
</sensordatatypes>
This definition defines a new sensor data type called "SimpleSdt". The SimpleSdt SDT declares two entryattributes: "fileName", and "elapsedTime". Each entryattribute defines a "required field" specific to this sensor data type. The fileName entryattribute has no attributes associated with it, which means that it simply declares a field that contains a String object. The elapsedTime entryattribute declares a "type", a "converter", and a "defaulter". These three Java classes implement an alternative representation to the basic String representation of this entryattribute as an Integer, and also provide a default value for this field when none is supplied by a sensor.
Every SDT XML declaration file must contain the top-level tag <sensordatatypes>. Within it is typically a single SDT definition, enclosed in the tag <sensordatatype>. The following table documents the attributes of the <sensordatatype> tag.
Table 15.2. Structure of a <sensordatatype> declaration
| Attribute | Description |
|---|---|
| name | A unique string identifying the SDT. If an SDT with that name has been previously defined, Hackystat signals an error at server startup time. |
| enabled | A string that should be "True" or "False"; if "False", this SDT definition will be ignored. |
| wrapper | The fully qualified class name for a Java class that is instantiated once for each entry in this SDT. The developer must implement this class. This class "wraps" the raw data associated with each entry to support a more object-oriented style of access, and can provide the developer with a construct to implement additional operations on entries of this type. |
| shellcommand | The fully qualified class name for a Java class that implements the interface org.hackystat.core.kernel.shell.command.ShellCommand. (Typically, the class will choose to extend org.hackystat.core.kernel.shell.command.ShellCommandAdapter instead, which provides default implementations for several important methods and implements ShellCommand.) This shellcommand class extends the SensorShell facility so that data associated with this SDT can be passed to the SensorShell from the tool-specific sensor and then transmitted on to the server. The developer is again responsible for implementing this class. |
| docstring | A short string describing this SDT. |
| contact | A string indicating who to contact for more information regarding this SDT. |
The <sensordatatype> element can contain one or more subelements called <entryattribute>. This next table documents the attributes of the <entryattribute> tag, each of which defines a "required" field for the sensor data type.
Table 15.3. Structure of a <entryattribute> declaration
| Attribute | Description |
|---|---|
| name | A unique string identifying the entry attribute, which corresponds to a "required" field for this SDT. |
| type (optional) | A string containing the fully qualified name of a class that this entry's String representation should be converted to on the server-side for the purposes of analysis. For example, a timestamp may be transmitted to the server as a long UTC value, but its type may be specifed as java.util.Date. |
| converter (required when "type" attribute is provided.) | A string specifying how to convert the String representation of this attribute into its Type representation. The string must contain the fully qualified name of a static method that accepts a String as its parameter and returns an instance of the class specified by the "type" attribute. For example, given a String long UTC value, an acceptable converter string value is "org.hackystat.core.kernel.util.DateInfo.parseDate". This is because the DateInfo class contains a static method named parseDate that accepts a String containing a UTC long value and returns the corresponding java.util.Date instance. |
| defaulter | A string containing the fully qualified name of a static no-arg method that returns a default value to be used for this entryattribute when the sensor does not supply one. This is important in the case of SDT evolution where one desires to add a new "required" field but cannot assume that old sensor data (or new incoming sensor data from old sensors) will contain a value for this field. |
The SimpleSdt SDT declaration explicitly declares two entryattributes: fileName and elapsedTime, which indicates that these two fields are "required". However, these are not the only required entryattributes associated with SimpleSdt. All Sensor Data Type declarations result in implicit definitions of the following three entryattributes: tool, tstamp, and pMap.
The "tool" entryattribute is an implicitly defined, but required field that specifies the development tool that was involved in generating the sensor data. Knowing the tool associated with the sensor data can be very important to appropriate analysis, since different tools might collect sensor data of a given type in slightly different ways. For example, the types of DevEvent sensor data collected by the Eclipse IDE is different than the types of DevEvent sensor data collected by the Emacs IDE. Analyses can use the tool field to perform context-specific analysis. In addition, knowing the tool that generated sensor data can often be useful in debugging installation or configuration problems. The implicit definition of the tool entryattribute corresponds to:
<entryattribute name="tool" />
The "tstamp" entryattribute is another implicitly defined but required attribute that specifies the time at which the sensor data was collected as a UTC long value. For example, the string "1138700000" corresponds to the date 31-Jan-2006 at 9:33:20 AM. UTC timestamps have millisecond accuracy, which is important since all sensor data entries of a given sensor data type must have unique UTC timestamps. The implicit definition of the tstamp attribute corresponds to:
<entryattribute name="tstamp"
type="java.util.Date"
converter="org.hackystat.core.kernel.util.DateInfo.parseDate" />
As you can see, the tstamp attribute will be automatically converted to a Date instance using the parseDate static method in the DateInfo class provided in the Hackystat kernel.
The final implicitly defined but required entryattribute is called "pMap". Up until now, all of the description of the structure of sensor data types has involved "required" attributes. Yet, the high level requirements for sensor data types clearly indicates that it must be possible to associate "optional" information with sensor data, which may or may not be present in any given circumstance. It is the role of the "pMap" (for "PropertyMap") implicit attribute to address this requirement. Hackystat provides a special class, called "SensorDataPropertyMap", which is a kind of Map that: (a) contains String key-value pairs; (b) supports encoding to and decoding from a String representation, and (c) supports concurrent access. Each sensor data instance contains a pMap, which can be used by sensors to attach arbitrary key-value pairs with additional contextual information about the sensor data. The implicit definition of the pMap attribute corresponds to:
<entryattribute name="pMap"
type="org.hackystat.core.kernel.sensordata.SensorDataPropertyMap"
converter="org.hackystat.core.kernel.sensordata.SensorDataPropertyMap.getMap"
defaulter="org.hackystat.core.kernel.sensordata.SensorDataPropertyMap.getDefaultMapString" />
This section illustrated the XML declaration of the SimpleSdt sensor data type. The most important aspect of an SDT declaration is the set of entryattributes, which declare the set of required fields associated with the sensor data type. In addition to the explicitly declared entryattributes, the Sensor Data Type declaration mechanism always implicitly defines three entryattributes called "tool", "tstamp", and "pMap". These entryattributes guarantee that every instance of sensor data will always have a unique timestamp, will indicate the tool it was derived from, and support the inclusion of optional attributes via a SensorDataPropertyMap instance.
Now that the structure of the SimpleSdt sensor data type has been described in abstract terms, the next step is to show how it is implemented concretely.