Greetings, everyone,
First, some introductions: James, Julie, and Austen are working on the client-side hackystat installer system, the screen dumps of which you saw in the HackyExperiment page that Mike put together at <http://csdl.ics.hawaii.edu/Tools/HackyExperiment/>. Forrest, Thiago, and Lorin are researchers at the University of Maryland who wish to use hackyInstaller to support software engineering experimentation using Hackystat. For good measure, I am also cc'ing hackystat-dev-l.
What the Maryland folks have indicated is that they are quite excited by the upcoming availability of the hackyInstaller package, but would like to request a command line interface to the hackyInstaller package. This is because they want to set up sensors in multiple user accounts as part of an experimental process, and they don't want to burden subjects in the experiment with the need to do this themselves. Furthermore, since the experiments take place on a variety of remote machines running unix, the easiest way to do this is with a command line interface to hackyInstaller so that they can ssh to the chosen machine, download hackyInstaller.jar onto that machine, then run a series of hackyInstaller commands to configure the various user accounts.
Because the HackyInstaller package was (excellently) designed using the Model-View-Controller design pattern, it should be relatively straightforward to extend the package to support a command line interface in addition to the current GUI interface. In this email, I want to provide a preliminary specification for what this command line interface might look like and solicit everyone's feedback.
------------------------------------------------------------------
HackyInstaller CLI interface specification
1. The overall behavior of the CLI interface is as follows:
java -jar hackyInstaller.jar <command>
[success | failure] <supplemental output>
In other words, to run the installer from the command line, you invoke it with a <command>. (If there is no <command>, this becomes the implicit "run the GUI" command producing the current installer behavior.)
To simplify CLI interface design and implementation, only one <command> can be provided per invocation of hackyInstaller.
Every invocation of hackyInstaller.jar with a <command> returns a single line containing either "success" or "failure". This is to simplify the development of scripts that invoke hackyInstaller multiple times and wish to check to see if the previous command completed successfully before continuing.
Following the single line containing "success" or "failure" can be any number of optional lines with additional output. The contents of these lines depends upon the <command>.
Every invocation of the Installer implicitly creates a .hackystat directory in the user's home directory if one is not already present, and reads in (and/or creates) a sensor.properties file in that directory.
If hackyInstaller is invoked with an unknown <command>, then it returns "failure" along with supplemental output indicating that the command is unknown.
As with the GUI interface, the results of invocations of hackyInstaller are logged to <home>/.hackystat/logs/hackyInstaller.log. This allows you to check to see what happened if the command line output is lost.
2. Command: SetHostAndKey
java -jar hackyInstaller.jar -SetHostAndKey <host> <key>
[success | failure ] <failure reason>
This command does the following: - sets the host (example: http://hackystat.ics.hawaii.edu/) and 12 character user key (example: jdhd98kemdd2) in the sensor.properties file. - attempts to contact the specified server and log in with the given key.
Returns "success" if the command is successful, "failure" otherwise (with a <failure reason>).
3. Command: SetProperty
java -jar hackyInstaller.jar -SetProperty <property> <value>
[success | failure] <failure reason>
This command sets <property> to <value>. This command should not normally fail (unless there are problems writing out the file, etc.)
Note that <property> can refer to properties stored in the sensor.properties file or the hackyInstaller.xml file (the latter of which contains "properties" specifying the home directory for programs such as Eclipse or Ant needed for certain sensor installations.)
4. Command: InstallOrUpdateSensor
java -jar hackyInstaller.jar -InstallOrUpdateSensor <sensorname>
[success | failure] [<failure reason> | <success info>]
This command does the following: - contacts the host, - attempts to download the specified sensor from the host and install it if not yet installed. - if already installed, but the server has a more recent version, then downloads and installs the new version.
If the command fails, then <failure reason> contains an explanation for why it failed. If the command succeeds, then <success info> contains info on what happened (did the sensor get installed or updated, etc.)
Note that in the event that you run this command and it finds that no update is needed, that constitutes "success".
5. Command: EnableSensor
java -jar hackyInstaller.jar -EnableSensor <sensorname> [true | false]
[success | failure] <failure reason>
This command enables or disables the specified sensor depending upon the boolean passed. It could fail, for example, if <sensorname> is unknown or not installed.
6. Command: UninstallSensor
java -jar hackyInstaller.jar -UninstallSensor <sensorname>
[success | failure] <failure reason>
Uninstalls the specified sensor.
-------------------------------------------------------------------
Let's see how this might work in practice. Here is an example session that illustrates the set of commands required to install the Eclipse sensor. First, of course, the server would need to be running and a user key would be obtained from the server.
java -jar hackyInstaller.jar -SetHostAndKey http://hackystat.ics.hawaii.edu/
RTHFGWI2345 success
java -jar hackyInstaller.jar -SetProperty Eclipse C:\eclipse
success
java -jar hackyInstaller.jar -InstallOrUpdateSensor Eclipse
success Eclipse sensor not found in C:\eclipse\plugins Eclipse sensor 6.5.428 downloaded and installed.
java -jar hackyInstaller.jar -EnableSensor Eclipse true
success
java -jar hackyInstaller.jar -SetProperty ENABLE_ECLIPSE_MONITOR_SENSOR true
success
---------------------------------------------------------------------
A couple of final comments. The assumption is that the CLI interface is in some sense an "expert" interface, in that the user will have to figure out things like the names of properties to set (such as ENABLE_ECLIPSE_MONITOR_SENSOR). A reasonable way to proceed is for the user to first use the GUI interface to set up things appropriately in their own environment, then inspect the contents of sensor.properties and hackyInstaller.xml to see what the "target" values should be, and then define a script containing hackyInstaller commands to reproduce those settings.
In addition, note that the installer command set is defined so that it can be invoked repeatedly. For example, the above script, once set up, could be run again, which would effectively ensure that the sensor is up to date with the newest version. You could also easily imagine creating a parameterized script, where you pass in the value of the user key, and thus set up a bunch of accounts simultaneously.
Please let me know if this seems reasonable and if there are any improvements you can suggest.
Cheers, Philip
