|
UserGuide
User Guide for SensorShell
1.0 IntroductionThis User Guide provides instructions on how to download, install, configure, and run the Hackystat SensorShell service. It also provides simple examples of its use in interactive and programmatic settings. Note that the SensorShell is a kind of "middleware" for Hackystat, and is primarily used as an embedded component in other sensors. Thus, most users do not need to install or use the SensorShell directly. 2.0 DownloadingYou will normally want to obtain the SensorShell from the latest System Sensors Binary Distribution, available from the Hackystat Downloads page. The file will be named something like hackystat-8.0.1101-sensors-bin.zip. It is also possible to download the sources from the Hackystat-Sensor-Shell SVN repository, but in that case you will need to build the SensorShell executable from sources. The binary system distribution comes with a pre-built version of the sensor shell called sensorshell.jar. 3.0 Installation3.1 Install a binary System distributionAfter downloading, unzip the hackystat-{version}-sensors-bin.zip file, which will create a new subdirectory called hackystat-sensor-shell containing the file sensorshell.jar. 3.2 Install JAXB (Java 5 only)If you are using Java 5, you will need to install JAXB. (It comes by default in Java 6). See http://code.google.com/p/hackystat/wiki/InstallingJAXBinJava5 for details. 4.0 Configure the sensorshell.properties FileBefore running the SensorShell, you will typically want to set up a file called sensorshell.properties in your {user.home}/.hackystat/sensorshell directory. More details can be found in SensorShellProperties. 5.0 Interactive SensorShell UseTo invoke the SensorShell, type 'java -jar sensorshell.jar. Here is an example invocation: admin01:~/svn-google/sensor-shell johnson$ java -jar sensorshell.jar 12/02 20:20:00 Hackystat SensorShell Version: 8.0.1202 12/02 20:20:00 SensorShell started at: Sun Dec 02 20:20:00 HST 2007 12/02 20:20:00 SensorProperties sensorshell.autosend.maxbuffer : 250 sensorshell.autosend.timeinterval : 1.0 sensorshell.logging.level : INFO sensorshell.multishell.autosend.timeinterval : 0.05 sensorshell.multishell.batchsize : 250 sensorshell.multishell.enabled : false sensorshell.multishell.numshells : 10 sensorshell.offline.cache.enabled : true sensorshell.offline.recovery.enabled : true sensorshell.sensorbase.host : http://localhost:9876/sensorbase/ sensorshell.sensorbase.password : <password hidden> sensorshell.sensorbase.user : johnson@hawaii.edu sensorshell.statechange.interval : 30 sensorshell.timeout : 10 sensorshell.properties file location: /Users/johnson/.hackystat/sensorshell/sensorshell.properties 12/02 20:20:00 Type 'help' for a list of commands. 12/02 20:20:00 Host: http://localhost:9876/sensorbase/ is not available 12/02 20:20:00 User johnson@hawaii.edu is not authorized to login at this host. 12/02 20:20:00 AutoSend time interval set to 60 seconds 12/02 20:20:00 Starting a ping... 12/02 20:20:00 Finished the ping... result is: false 12/02 20:20:00 Server not available or offline recovery disabled. 12/02 20:20:00 >> As you can see, the startup messages indicate that it could not find a running SensorBase at http://localhost:9876/sensorbase. If you get this message, this means that you have to download the SensorBase and bring it up. Instructions are available at the SensorBase User Guide. Let's assume that you've now got the SensorBase running in another command shell such as is illustrated here: c:\svn-google\hackystat-sensorbase-uh\trunk>java -jar sensorbase.jar
Loading SensorBase properties from: C:\Documents and Settings\johnson/.hackystat/sensorbase/sensorbase.properties
07/10 13:05:37 Derby: previously initialized.
07/10 13:05:37 Loading SDT defaults from c:\svn-google\hackystat-sensorbase-uh\trunk\xml\defaults\sensordatatypes.defaults.xml
07/10 13:05:38 Loading User defaults from c:\svn-google\hackystat-sensorbase-uh\trunk\xml\defaults\users.defaults.xml
07/10 13:05:38 Loading Project defaults from c:\svn-google\hackystat-sensorbase-uh\trunk\xml\defaults\projects.defaults.xml
07/10 13:05:38 Loading SensorData defaults: c:\svn-google\hackystat-sensorbase-uh\trunk\xml\defaults\sensordata.defaults.xml
07/10 13:05:38 Host: http://localhost:9876/sensorbase/
07/10 13:05:38 SensorBase Properties:
sensorbase.admin.email = johnson@hawaii.edu
sensorbase.admin.password = (removed)
sensorbase.hostname = localhost
sensorbase.context.root = sensorbase
sensorbase.db.dir = c:\sensorbase\db
sensorbase.db.impl = org.hackystat.sensorbase.db.derby.DerbyImplementation
sensorbase.logging.level = INFO
sensorbase.smtp.host = mail.hawaii.edu
sensorbase.port = 9876
sensorbase.test.install = false
sensorbase.xml.dir = c:\svn-google\hackystat-sensorbase-uh\trunk\xml
07/10 13:05:38 SensorBase (Version 8.0.710) now running.Now when you invoke the SensorShell, you should get something similar to the following: admin01:~/svn-google/sensor-shell johnson$ java -jar sensorshell.jar 12/02 20:18:03 Hackystat SensorShell Version: 8.0.1202 12/02 20:18:03 SensorShell started at: Sun Dec 02 20:18:03 HST 2007 12/02 20:18:03 SensorProperties sensorshell.autosend.maxbuffer : 250 sensorshell.autosend.timeinterval : 1.0 sensorshell.logging.level : INFO sensorshell.multishell.autosend.timeinterval : 0.05 sensorshell.multishell.batchsize : 250 sensorshell.multishell.enabled : false sensorshell.multishell.numshells : 10 sensorshell.offline.cache.enabled : true sensorshell.offline.recovery.enabled : true sensorshell.sensorbase.host : http://localhost:9876/sensorbase/ sensorshell.sensorbase.password : <password hidden> sensorshell.sensorbase.user : johnson@hawaii.edu sensorshell.statechange.interval : 30 sensorshell.timeout : 10 sensorshell.properties file location: /Users/johnson/.hackystat/sensorshell/sensorshell.properties 12/02 20:18:03 Type 'help' for a list of commands. 12/02 20:18:04 Host: http://localhost:9876/sensorbase/ is available. 12/02 20:18:04 User johnson@hawaii.edu is authorized to login at this host. 12/02 20:18:04 AutoSend time interval set to 60 seconds 12/02 20:18:04 Starting a ping... 12/02 20:18:04 Finished the ping... result is: true 12/02 20:18:04 Checking for offline data to recover. 12/02 20:18:04 Explicit send of recovered data. 12/02 20:18:04 Starting a ping... 12/02 20:18:04 Finished the ping... result is: true 12/02 20:18:04 No sensor data to send. 12/02 20:18:04 >> >> This time, the startup messages indicate that the server was contacted, and that the email and password supplied in the sensorshel.properties file are valid for this server. (If they are not valid, then you need to register your email address and have the server send you a password. One thing that might be useful to do is to enter the help command, which produces the following information: >> help
SensorShell Command Summary
add#<key>=<value>[#<key>=<value>]...
Adds a new sensor data instance for subsequent sending.
Provide fields and properties as key=value pairs separated by '#'.
Owner, Timestamp, and Runtime fields will default to the current user and time.
Example: add#Tool=Eclipse#SensorDataType=DevEvent#DevEventType=Compile
send
Sends any added sensor data to the server.
Server is pinged, and if it does not respond, then data is stored offline.
Example: send
ping
Pings the server and checks email/password credentials.
Example: ping
statechange#<ResourceCheckSum>#<key>=<value>[#<key>=<value>]...
Generates an 'add' command when the 'state' has changed.
ResourceCheckSum is an integer that represents the current state of the Resource.
This command compares ResourceCheckSum and the Resource field value to the values
saved from the last call to statechange. If either have changed, indicating that
the state has changed, then the key-value pairs are passed to the Add command.
This command facilitates the implementation of timer-based sensor processes that
wake up periodically and emit statechange commands, with the knowledge that if
the user has not been active, these statechange commands will not result in
actual sensor data being sent to the server.
quit
Sends any remaining data and exits the sensorshell.
Example: quit
>>As you can see, the SensorShell supports only four commands: add, send, ping, and quit. The most useful command, of course, is add. When invoking add, you supply a set of case-sensitive key=value pairs, separated by the character '#'. A SensorData instance includes the following fields with specific meanings:
If you do not supply the Timestamp or Runtime keys, then the SensorShell will generate a timestamp associated with the current time and use that. If you do not supply the Owner key, then the value of the HACKYSTAT_EMAIL property in the v8.sensor.properties file will be used instead. So, for example, here is a simple "add" command: >> add#Tool=Eclipse#Resource=file://c:/svn-google/Stuff.java#SensorDataType=DevEvent#DevEventType=Compile Adding: <2007-07-10T13:38:44.157-10:00 DevEvent johnson@hawaii.edu Eclipse file://c:/svn-google/Stuff.java 2007-07-10T13:38:44.157-10:00 DevEventType=Compile As you can see, I provided the "Tool", "Resource", and "SensorDataType" fields. I also provided a Property called "DevEventType". In response, the SensorShell indicated that I added a SensorData instance, and shows that the Timestamp, Owner, and Runtime fields were provided with default values. The next thing I might do is manually invoke the send command: >> send
About to send the following sensor data:
<Timestamp SDT Owner Tool Resource Runtime {Properties}>
<2007-07-10T13:38:44.157-10:00 DevEvent johnson@hawaii.edu Eclipse file://c:/svn-google/Stuff.java 2007-07-10T13:38:44.157-10:00 DevEventType=Compile >
1 SensorData instances sent to http://localhost:9876/sensorbase/In this case, the SensorShell indicates the data that will be sent, and after the data is sent to the server, it indicates how many instances were sent. Note that if you look at your command shell that is running the SensorBase, you will see a single line of output indicating that new sensor data was received: 07/10 13:38:50 Storing sensor data from: johnson@hawaii.edu Other commands are fairly self explanatory. Please note that the keys in the add command are case-sensitive. 6.0 Programmatic SensorShell UseThe SensorShell can also be used programmatically. The client API consists of the SensorShell class. For details of the API, see the SensorShell JavaDocs. The programmatic API follows the interactive API fairly closely. After creating an instance of SensorShell, the methods add, ping, send, setAutoSend, and quit operate much the way they do in the interactive mode. Here is a small code fragment that illustrates the fundamental concepts for building a sensor with the SensorShell programmatic API. // The following creates a SensorProperties instance by reading from ~/.hackystat/sensorshell/sensorshell.properties
// You could also use an alternative constructor and supply the host, email, and password yourself.
SensorShellProperties properties = new SensorShellProperties();
// Create a SensorShell using the above properties. It's non-interactive and log files will be named "Eclipse.log.0.txt"
SensorShell shell = new SensorShell(properties, false, "Eclipse");
// To make a SensorData instance, construct a Map with the desired key-value pairs.
// We will let the SensorShell generate the timestamp.
Map<String, String> keyValMap = new HashMap<String, String>();
keyValMap.put("Tool", "Eclipse");
keyValMap.put("SensorDataType", "DevEvent");
keyValMap.put("DevEvent-Type", "Compile");
// If we want to generate a timestamp or runtime ourselves, here's how to do it.
// The SensorBase Tstamp class makes this easier.
XMLGregorianCalendar runtime = Tstamp.makeTimestamp();
keyValMap.put("Runtime", runtime.toString());
// Now invoke add, which generates a SensorData instance using the data in the Map.
shell.add(keyValMap);
// If we want to explicitly send the data, we can as follows, though this is not necessary due
// to the autosend facility.
shell.send();
// We could do a Ping and change the autosend interval if we wanted.
boolean isAvailable = shell.ping();
shell.setAutoSend(1);
// Make sure to invoke quit when your tool exits so that any remaining data is sent:
shell.quit();
|
Sign in to add a comment
