Each time the SensorShell starts up, it performs a number of initialization tasks, as illustrated below. A newline is inserted below to separate the output related to each task.

C:\>java -jar sensorshell.jar
Hackystat Version: 7.3.220 (February 20 2006 12:37:30)
SensorShell started at: 02/20/2006 12:59:46
Type 'help' for a list of commands.

Host: http://hackystat.ics.hawaii.edu/ is available and key is valid.

Defined shell command: DevEvent
Defined shell command: UnitTest
Defined shell command: BuffTrans
Defined shell command: Commit
Defined shell command: Build

AutoSend enabled every 10 minutes.

Checking for offline data to recover.
No offline data found.

First, the SensorShell prints out its version and build time, and the time at which it started up. (All information printed to the command shell is also saved in a log file, which is one motivation for this descriptive information upon startup.) The SensorShell also reminds you to type 'help' to find out the available commands.

Next, the SensorShell reads in the the contents of this user's sensor.properties file to determine the URL of the Hackystat host server and this user's Hackystat key. It uses this information during an attempt to contact the server to see if the server is available and if the key is valid on this server. In this example, the host was found at the displayed URL, and the key (not shown) was found to be valid.

Next, the SensorShell inspects its jar file for all available sensor data type definitions, and loads their associated ShellCommand classes. The set of commands that one can provide to the SensorShell are based upon the set of defined SDT ShellCommand classes, as will be shown further below. It prints out the shell commands it retrieved for reference purposes. In this example, five shell commands were found.

Next, the SensorShell prints out the current autosend time interval. As noted in Section 16.2, “Requirements for the SensorShell”, sensors should both buffer the sensor data they collect (i.e. they should not send each sensor data instance immediately to the server in a SOAP request), and not buffer too much sensor data (i.e. they should periodically send any accumulated sensor data to the server). The SensorShell implements this requirement by buffering any data it receives, and by providing an "AutoSend" command that controls how long to wait before sending any accumulated data to the server. Each user can control the interval of time that the SensorShell should wait before sending buffered data using HackyInstaller (under "File | Edit common settings..."). In this example, the autosend interval is 10 minutes, which is the default.

The final task performed by the SensorShell during startup initialization is to check to see if there is any sensor data cached locally by some previous sensor who could not contact the Hackystat host after collecting data. This data is called "offline" data, since it is collected when the Hackystat host (and/or the user's computer) was not "online". In this example, no offline data was found.

Invoking "help" tells the SensorShell to print out the set of all ShellCommand commands known to it. The resulting help string is generated by appending together the strings returned by invoking the getHelpString method on each known ShellCommand. (Section 15.7, “Anatomy of SimpleSdt: the "ShellCommand class"” provides details on this class and the getHelpString method). Example output follows, with the logical "sections" of ShellCommands separated by a newline.

>> help
SensorShell Command Summary
help
  This message.
quit
  Exit this sensor shell and send all accumulated data.
send
  Send all accumulated data.
Ping
  Attempts to contact the hackystat server and indicates success.
AutoSend#<number>
  Sets the number of minutes between background sending of any sensor data.
  Setting <number> to 0 disables autosending.
  The HACKYSTAT_AUTOSEND_INTERVAL property in sensor.properties can set AutoSend.

DevEvent#set#tool=<tool>
  Sets the default tool attribute value for subsequent DevEvent shell commands.
DevEvent#add#<key1>=<val1>#<key2>=<val2>...
  <keyN> is: path, type, [pMap]
DevEvent#edit#path=<filename>#size=<buffersize>
  Adds a DevEvent only if the <size> associated with <path> has changed.

Commit#set#tool=<tool>
  Sets the default tool attribute value for subsequent Cli shell commands.
Commit#add#<key1>=<val1>#<key2>=<val2>...
  <keyN> is: commitTime, fileName, author, vcsRepository, branchNumber,
    versionNumber, TotalLines, LinesAdded, LinesDeleted, log, [tool], [pMap]

BuffTrans#set#tool=<tool>
  Sets the default tool attribute value for subsequent BuffTrans shell commands.
BuffTrans#add#<key1>=<val1>#<key2>=<val2>...
  <keyN> is: fromFile, toFile, mod, [tool], [pMap]

UnitTest#set#tool=<tool>
  Sets the default tool attribute value for subsequent UnitTest shell commands.
UnitTest#add#<key1>=<val1>#<key2>=<val2>...
  <keyN> is one of: testCaseName, testName, elapsedTime, [failureString], [errorString]
  [tool], [pMap]

Build#set#tool=<tool>
  Sets the default tool attribute value for subsequent Build shell commands.
Build#add#<key1>=<value1>#<key2>=<value2>...
  <keyN> is: result, failureType, failureMessage, runtimeStamp,
  startTimeMillis, endTimeMillis, buildLocation, buildTarget, additionalData,
  [tool], [pMap]

The first section of the help command output describes the five built-in commands associated with all instances of the sensorshell: help, quit, send, Ping, and AutoSend. These are pretty self-explanatory.

The following five sections document the commands associated with the five ShellCommand classes available in this configuration of the SensorShell. All of the five ShellCommands implement a "set" command and an "add" command. In addition, the DevEvent ShellCommand implements an "edit" command. There is no limit to the number of commands that a ShellCommand can make available, although the needs of most sensors is satisfied by the "set" and "add" commands.

One of the most simple commands to execute is "Ping", which just checks to see if the server specified in the sensor.properties file is available and the key is valid. As you might guess, the SensorShell automatically performs a Ping each time it starts up. Here is an example invocation of Ping and its results.

>> Ping
Ping OK (contacted server http://hackystat.ics.hawaii.edu/ with valid key.)

As you can see, it's all good.

A more interesting command invocation involves an actual CommandShell command, such as the DevEvent "add" command:

>> DevEvent#add#path=c:\foo#type=edit
DevEvent add OK (1 total)

This command illustrates the standard approach to interactive command line invocation. The user must first specify the CommandShell name ("DevEvent"), followed by the command ("add"), followed by one or more key-value pairs ("path=c:\foo"). In the case of the DevEvent "edit" command, the associated help string specifies that the "path" and "type" key-value pairs are required. Since this is a legal invocation of the DevEvent "add" command, the SensorShell responds that the add command was "OK". It also lists how many buffered DevEvent instances it is currently holding (in this case, just 1).

In addition to the required key-value pairs, a sensor can also supply any number of other key-value pairs that might provide useful contextual information about the sensor data. These will be stored in the "pMap", or SensorDataPropertyMap, associated with this instance of the sensor data. For example, the following illustrates the creation of DevEvent sensor data with an optional "location" property:

>> DevEvent#add#path=c:\foo#type=edit#location=office
DevEvent add OK (2 total)

Finally, the SensorShell will throw an error if the command is not valid or the required fields are not provided, as illustrated below:

>> DevEvent#add
DevEvent add error (Invalid element(s).
{tool=Sensor Shell, tstamp=1140559713046}
org.hackystat.core.kernel.sdt.SensorDataTypeException: 3 SensorData instantiation error: DevEvent {tool=Sensor Shell, tstamp=1140559713046}

Invocation of CommandShell commands, such as the "add" command illustrated above, provide sensor data to the SensorShell but does not immediately lead to that data being sent to the Hackystat server. Instead, it is buffered until one of three things happen: (1) the "send" command is explicitly invoked; (2) the "AutoSend" interval elapses, resulting in an implicit invocation of the "send" command; or (3) the SensorShell exits, which triggers a final "send" command to send any unsent data. The following example illustrates the explicit invocation of the "send" command:

>> send
Sending sensor data (02/20 13:01:04)
  Ping: Ping OK (contacted server http://hackystat.ics.hawaii.edu/ with valid key.)
  AutoSend: AutoSend OK ('send' command ignored)
  DevEvent: Send OK (1 entries)
  Coverage: Send OK (No entries to send.)
  Commit: Send OK (No entries to send.)
  BuffTrans: Send OK (No entries to send.)
  UnitTest: Send OK (No entries to send.)
  Build: Send OK (No entries to send.)

The "send" command begins by performing a "Ping" of the server to make sure it is still available. If so, it proceeds with the sending of the data. (Note that should the server go down after the successful Ping attempt but before the sensor data in this batch has been successfully sent, the remaining data will be lost. Hackystat does not implement the kind of transactional support necessary to guarantee successful transmission of the data. Given that losing a few minutes of sensor data is rarely a mission critical failure for an organization, and given that we have not to our knowledge in five years of Hackystat development witnessed this event, we're not too worried.)

The output from the SensorShell illustrates how it implements the "send" command: after checking the Ping, it simply cycles through all the known CommandShells and invokes their internal "send" method. The output indicates whether any data was actually sent or not.

The final command in our example is "quit", which exits the SensorShell. As the output illustrates, the "quit" command invokes the "send" command prior to terminating the SensorShell:

>> quit
Sending sensor data (02/20 13:01:14)
  Ping: Ping OK (contacted server http://hackystat.ics.hawaii.edu/ with valid key.)
  AutoSend: AutoSend OK ('send' command ignored)
  DevEvent: Send OK (No entries to send.)
  Coverage: Send OK (No entries to send.)
  Commit: Send OK (No entries to send.)
  BuffTrans: Send OK (No entries to send.)
  UnitTest: Send OK (No entries to send.)
  Build: Send OK (No entries to send.)
>>
C:\>