org.hackystat.sensorshell
Class SensorShell

java.lang.Object
  extended by org.hackystat.sensorshell.SensorShell
All Implemented Interfaces:
Shell

public class SensorShell
extends java.lang.Object
implements Shell

Provides "middleware" for accumulating and sending notification (sensor) data to Hackystat. SensorShell has two modes of interaction: command line and programmatic.

Command line mode is entered by invoking the main() method, and is intended to be used as a kind of subshell to which commands to add and send notification data of various types can be sent. The SensorShell can be invoked without any additional arguments as follows:

java -jar sensorshell.jar
Or you can invoke it with one, two, or three additional arguments:
java -jar sensorshell.jar [tool] [sensorshell.properties] [command file]

Programmatic mode involves creating an instance of SensorShell, retrieving the appropriate command instance (Ping, Add, etc.) and invoking the appropriate method.

Author:
Philip M. Johnson

Constructor Summary
SensorShell(SensorShellProperties properties, boolean isInteractive)
          Constructs a new SensorShell instance that can be provided with notification data to be sent eventually to a specific user key and host.
SensorShell(SensorShellProperties properties, boolean isInteractive, java.lang.String tool)
          Constructs a new SensorShell instance that can be provided with notification data to be sent eventually to a specific user key and host.
SensorShell(SensorShellProperties properties, boolean isInteractive, java.lang.String toolName, java.io.File commandFile)
          Constructs a new SensorShell instance that can be provided with notification data to be sent eventually to a specific user key and host.
 
Method Summary
 void add(java.util.Map<java.lang.String,java.lang.String> keyValMap)
          Converts the values in the KeyValMap to a SensorData instance and adds it to the Shell.
 void add(org.hackystat.sensorbase.resource.sensordata.jaxb.SensorData sensorData)
          Adds the passed SensorData instance to the Shell.
 SensorShellProperties getProperties()
          Returns the SensorShell properties instance used to create this SensorShell.
 boolean hasOfflineData()
          Returns true if any of shells in this interface have stored data offline.
static void main(java.lang.String[] args)
          The command line shell interface for invoking a single sensor shell interactively.
 boolean ping()
          Returns true if the host can be pinged and the email/password combination is valid.
 void quit()
          Invokes quit() on this Shell, which invokes a final send() and closes any logging files.
 int send()
          Immediately invokes send() on this Shell.
 void statechange(long resourceCheckSum, java.util.Map<java.lang.String,java.lang.String> keyValMap)
          Implements the "StateChange" algorithm.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

SensorShell

public SensorShell(SensorShellProperties properties,
                   boolean isInteractive)
Constructs a new SensorShell instance that can be provided with notification data to be sent eventually to a specific user key and host. The toolName field in the log file name is set to "interactive" if the tool is invoked interactively and "tool" if it is invoked programmatically.

Parameters:
properties - The sensor properties instance for this run.
isInteractive - Whether this SensorShell is being interactively invoked or not.

SensorShell

public SensorShell(SensorShellProperties properties,
                   boolean isInteractive,
                   java.lang.String tool)
Constructs a new SensorShell instance that can be provided with notification data to be sent eventually to a specific user key and host.

Parameters:
properties - The sensor properties instance for this run.
isInteractive - Whether this SensorShell is being interactively invoked or not.
tool - Indicates the invoking tool that is added to the log file name.

SensorShell

public SensorShell(SensorShellProperties properties,
                   boolean isInteractive,
                   java.lang.String toolName,
                   java.io.File commandFile)
Constructs a new SensorShell instance that can be provided with notification data to be sent eventually to a specific user key and host.

Parameters:
properties - The sensor properties instance for this run.
isInteractive - Whether this SensorShell is being interactively invoked or not.
toolName - The invoking tool that is added to the log file name.
commandFile - A file containing shell commands, or null if none provided.
Method Detail

add

public void add(java.util.Map<java.lang.String,java.lang.String> keyValMap)
         throws SensorShellException
Converts the values in the KeyValMap to a SensorData instance and adds it to the Shell. Owner will default to the hackystat user in the sensor.properties file. Timestamp and Runtime will default to the current time.

Specified by:
add in interface Shell
Parameters:
keyValMap - The map of key-value pairs.
Throws:
SensorShellException - If the Map cannot be translated into SensorData, typically because a value was passed for Timestamp or Runtime that could not be parsed into XMLGregorianCalendar. Or if problems occur sending the data.

add

public void add(org.hackystat.sensorbase.resource.sensordata.jaxb.SensorData sensorData)
         throws SensorShellException
Adds the passed SensorData instance to the Shell.

Specified by:
add in interface Shell
Parameters:
sensorData - The SensorData instance to be queued for transmission.
Throws:
SensorShellException - If problems occur sending the data.

send

public int send()
         throws SensorShellException
Immediately invokes send() on this Shell. Note that you will rarely want to invoke this method. Instead, during normal operation you will rely on the autoSendTimeInterval to invoke send() in a separate thread, and then invoke quit() to invoke send() at the conclusion of the run.

Specified by:
send in interface Shell
Returns:
The total number of instances sent by Shell.
Throws:
SensorShellException - If problems occur sending the data.

quit

public void quit()
          throws SensorShellException
Invokes quit() on this Shell, which invokes a final send() and closes any logging files.

Specified by:
quit in interface Shell
Throws:
SensorShellException - If an exception occurred during any autosend.

hasOfflineData

public boolean hasOfflineData()
Returns true if any of shells in this interface have stored data offline.

Specified by:
hasOfflineData in interface Shell
Returns:
True if any of these shells have stored offline data during this session.

ping

public boolean ping()
Returns true if the host can be pinged and the email/password combination is valid.

Specified by:
ping in interface Shell
Returns:
True if the host can be pinged and the user credentials are valid.

getProperties

public SensorShellProperties getProperties()
Returns the SensorShell properties instance used to create this SensorShell.

Specified by:
getProperties in interface Shell
Returns:
The SensorShellProperties instance.

statechange

public void statechange(long resourceCheckSum,
                        java.util.Map<java.lang.String,java.lang.String> keyValMap)
                 throws java.lang.Exception
Implements the "StateChange" algorithm. The goal of StateChange is to add a new SensorData instance for sending to the SensorBase only when "something has changed" in the tool (which is typically an interactive editor or IDE). This method is designed to be used in conjunction with a timer-based process in the sensor client. The timer-based process should wake up at regular intervals, determine the currently "active" resource (typically a file), and compute a "checksum" for that resource representing its state. (This checksum is typically the size of the resource in bytes or characters.) Having obtained those two values, the sensor client can then create a keyValMap as if it were going to do a regular Add command, and invoke this method with it as well as with the resourceCheckSum. This method keeps track of the last Resource and last ResourceCheckSum provided to it, and if either has changed, it will automatically invoke the Add command, passing the keyValMap to it.

Thus, if an editor is running but the user is out at lunch, repeated invocations of the StateChange method will not result in any new data being sent to the server.

Specified by:
statechange in interface Shell
Parameters:
resourceCheckSum - An integer representing the state of the Resource.
keyValMap - A map of key-value pairs representing sensor data fields and properties.
Throws:
java.lang.Exception - If problems occur during the Add (if the Add actually occurs.)

main

public static void main(java.lang.String[] args)
                 throws SensorShellException
The command line shell interface for invoking a single sensor shell interactively. Unless three arguments are provided, the shell then provides a ">>" prompt and supports interactive entry of sensor data. The following commands are supported:

Parameters:
args - The command line parameters. See above for details.
Throws:
SensorShellException - If problems occur sending data.