org.hackystat.sensorshell
Class SensorShellProperties

java.lang.Object
  extended by org.hackystat.sensorshell.SensorShellProperties

public class SensorShellProperties
extends java.lang.Object

Provides Hackystat sensors with access to standard Hackystat sensorshell properties. These properties are generally stored in ~/.hackystat/sensorshell/sensorshell.properties. This class manages access to those files for sensors, performs type conversions on the String-based properties when appropriate, and sets default values when the properties are missing or incorrectly specified.

See the public static final Strings for descriptions of the "standard" Hackystat sensorshell properties.

Author:
Philip M. Johnson, Aaron A. Kagawa

Field Summary
static java.lang.String SENSORSHELL_AUTOSEND_MAXBUFFER_KEY
          The property key retrieving an integer indicating the maximum number of sensor instances to buffer locally between autosends of sensor data.
static java.lang.String SENSORSHELL_AUTOSEND_TIMEINTERVAL_KEY
          The property key retrieving a double indicating how many minutes between autosends of sensor data when not in MultiShell mode.
static java.lang.String SENSORSHELL_LOGGING_LEVEL_KEY
          The property key retrieving a string indicating the logging level for the SensorShell(s).
static java.lang.String SENSORSHELL_MULTISHELL_AUTOSEND_TIMEINTERVAL_KEY
          The property key retrieving a double indicating how many minutes between autosends of sensor data for each shell in a MultiShell.
static java.lang.String SENSORSHELL_MULTISHELL_BATCHSIZE_KEY
          The property key retrieving an integer indicating the number of instances to send to a single shell in the MultiSensorShell at once.
static java.lang.String SENSORSHELL_MULTISHELL_ENABLED_KEY
          The property key retrieving a boolean indicating whether the MultiSensorShell is enabled.
static java.lang.String SENSORSHELL_MULTISHELL_MAXBUFFER_KEY
          The property key retrieving an integer indicating the maximum number of instances to buffer in each shell in the MultiSensorShell before a blocking send() is invoked.
static java.lang.String SENSORSHELL_MULTISHELL_NUMSHELLS_KEY
          The property key retrieving an integer indicating the number of shells to instantiate when the MultiSensorShell is enabled.
static java.lang.String SENSORSHELL_OFFLINE_CACHE_ENABLED_KEY
          The property key retrieving a boolean indicating if data will be cached locally if the SensorBase cannot be contacted.
static java.lang.String SENSORSHELL_OFFLINE_RECOVERY_ENABLED_KEY
          The property key retrieving a boolean indicating if offline data will be recovered at startup if the SensorBase can be contacted.
static java.lang.String SENSORSHELL_PING_TIMEOUT_KEY
          The property key retrieving the timeout value (in seconds) for SensorShell 'PING' requests.
static java.lang.String SENSORSHELL_SENSORBASE_HOST_KEY
          The property key retrieving an URL indicating the location of the SensorBase host.
static java.lang.String SENSORSHELL_SENSORBASE_PASSWORD_KEY
          The property key retrieving the password associated with the user.
static java.lang.String SENSORSHELL_SENSORBASE_USER_KEY
          The property key retrieving the user account associated with the SensorBase.
static java.lang.String SENSORSHELL_STATECHANGE_INTERVAL_KEY
          The property key retrieving an integer indicating the number of seconds between "wakeups" of tool subprocesses that check for state changes.
static java.lang.String SENSORSHELL_TIMEOUT_KEY
          The property key retrieving the timeout value (in seconds) for SensorShell HTTP requests.
 
Constructor Summary
SensorShellProperties()
          Initializes SensorShell properties using the default sensorshell.properties file.
SensorShellProperties(java.io.File sensorFile)
          Creates a SensorShellProperties instance using the specified properties file.
SensorShellProperties(java.util.Properties properties, boolean overrideFile)
          Creates a SensorShell properties instance, initializing it using the passed properties as well as any settings found in the sensorshell.properties file.
SensorShellProperties(SensorShellProperties orig, java.util.Properties newProps)
          Creates and returns a new SensorShellProperties instance which is initialized to the contents of the passed SensorProperties instance, with additional new properties overriding the previous selection.
SensorShellProperties(java.lang.String host, java.lang.String email, java.lang.String password)
          Constructs a "basic" instance with the supplied three required properties.
SensorShellProperties(java.lang.String host, java.lang.String email, java.lang.String password, java.util.Properties properties, boolean overrideFile)
          Constructs an instance with the supplied three required properties and any other properties provided in the properties argument.
 
Method Summary
 int getAutoSendMaxBuffer()
          Returns the AutoSend batch size, such as 250.
 double getAutoSendTimeInterval()
          Returns the AutoSend time interval, such as 1.0.
 java.util.logging.Level getLoggingLevel()
          Returns the logging level specified for SensorShells.
 double getMultiShellAutoSendTimeInterval()
          Returns the MultiShell AutoSend time interval, such as 0.10.
 int getMultiShellBatchSize()
          Returns the number of instances to send to one shell in a row if multishell processing.
 int getMultiShellMaxBuffer()
          Returns the maximum number of instances to buffer before a blocking send is invoked in multishell mode.
 int getMultiShellNumShells()
          Returns the number of shells to instantiate if multishell processing is enabled.
static SensorShellProperties getOfflineMode(SensorShellProperties properties)
          Returns a new SensorShellProperties instance customized for offline data recovery.
 int getPingTimeout()
          Returns the current timeout setting for Ping requests.
 java.lang.String getProperty(java.lang.String key)
          Returns the trimmed property value associated with the property key.
 java.lang.String getSensorBaseHost()
          Returns the sensorbase host, such as "http://dasha.ics.hawaii.edu:9876/sensorbase".
 java.lang.String getSensorBasePassword()
          Returns the password for this user, such as "xu876csld".
 java.lang.String getSensorBaseUser()
          Returns the account for this user, such as "johnson@hawaii.edu".
 int getStateChangeInterval()
          Returns the StateChange interval.
static SensorShellProperties getTestInstance(java.lang.String host, java.lang.String email, java.lang.String password)
          Constructs a "test" instance with the supplied three required properties.
 int getTimeout()
          Returns the current timeout setting for non-Ping requests.
 boolean isMultiShellEnabled()
          Returns true if multishell processing is enabled.
 boolean isOfflineCacheEnabled()
          Returns true if offline cache data saving is enabled.
 boolean isOfflineRecoveryEnabled()
          Returns true if offline data recovery is enabled.
 void switchToMultiShellMode()
          Sets the autosend time interval and autosend max buffer size to the multishell versions.
 java.lang.String toString()
          Returns the set of SensorProperties as a multi-line string.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

SENSORSHELL_SENSORBASE_HOST_KEY

public static final java.lang.String SENSORSHELL_SENSORBASE_HOST_KEY
The property key retrieving an URL indicating the location of the SensorBase host. This a required property; if not supplied, instantiation will fail. Example: "http://dasha.ics.hawaii.edu:9876/sensorbase". No default value.

See Also:
Constant Field Values

SENSORSHELL_SENSORBASE_USER_KEY

public static final java.lang.String SENSORSHELL_SENSORBASE_USER_KEY
The property key retrieving the user account associated with the SensorBase. This a required property; if not supplied, instantiation will fail. Example: "johnson@hawaii.edu". No default value.

See Also:
Constant Field Values

SENSORSHELL_SENSORBASE_PASSWORD_KEY

public static final java.lang.String SENSORSHELL_SENSORBASE_PASSWORD_KEY
The property key retrieving the password associated with the user. This a required property; if not supplied, instantiation will fail. Example: "xykdclwck". No default value.

See Also:
Constant Field Values

SENSORSHELL_TIMEOUT_KEY

public static final java.lang.String SENSORSHELL_TIMEOUT_KEY
The property key retrieving the timeout value (in seconds) for SensorShell HTTP requests. Default: "10".

See Also:
Constant Field Values

SENSORSHELL_PING_TIMEOUT_KEY

public static final java.lang.String SENSORSHELL_PING_TIMEOUT_KEY
The property key retrieving the timeout value (in seconds) for SensorShell 'PING' requests. Default: "2".

See Also:
Constant Field Values

SENSORSHELL_MULTISHELL_ENABLED_KEY

public static final java.lang.String SENSORSHELL_MULTISHELL_ENABLED_KEY
The property key retrieving a boolean indicating whether the MultiSensorShell is enabled. If true, offline recovery and storage will be automatically disabled. Default: "false".

See Also:
Constant Field Values

SENSORSHELL_MULTISHELL_NUMSHELLS_KEY

public static final java.lang.String SENSORSHELL_MULTISHELL_NUMSHELLS_KEY
The property key retrieving an integer indicating the number of shells to instantiate when the MultiSensorShell is enabled. Default: "10".

See Also:
Constant Field Values

SENSORSHELL_MULTISHELL_BATCHSIZE_KEY

public static final java.lang.String SENSORSHELL_MULTISHELL_BATCHSIZE_KEY
The property key retrieving an integer indicating the number of instances to send to a single shell in the MultiSensorShell at once. We make this one less than the default multishell maxbuffer value so that the non-blocking autosend has chance to run rather than the blocking send() resulting from hitting the maxbuffer size. Default: "499".

See Also:
Constant Field Values

SENSORSHELL_MULTISHELL_MAXBUFFER_KEY

public static final java.lang.String SENSORSHELL_MULTISHELL_MAXBUFFER_KEY
The property key retrieving an integer indicating the maximum number of instances to buffer in each shell in the MultiSensorShell before a blocking send() is invoked. Default: "500".

See Also:
Constant Field Values

SENSORSHELL_MULTISHELL_AUTOSEND_TIMEINTERVAL_KEY

public static final java.lang.String SENSORSHELL_MULTISHELL_AUTOSEND_TIMEINTERVAL_KEY
The property key retrieving a double indicating how many minutes between autosends of sensor data for each shell in a MultiShell. If "0.0", then sensor data is not sent unless the client invokes the send() method explicitly. This value is typically around 0.05 to 0.10 (i.e. 3 to 6 seconds). Default: "0.05".

See Also:
Constant Field Values

SENSORSHELL_OFFLINE_CACHE_ENABLED_KEY

public static final java.lang.String SENSORSHELL_OFFLINE_CACHE_ENABLED_KEY
The property key retrieving a boolean indicating if data will be cached locally if the SensorBase cannot be contacted. Default: "true" if multi-shell is disabled. If multishell is enabled, then set to false.

See Also:
Constant Field Values

SENSORSHELL_OFFLINE_RECOVERY_ENABLED_KEY

public static final java.lang.String SENSORSHELL_OFFLINE_RECOVERY_ENABLED_KEY
The property key retrieving a boolean indicating if offline data will be recovered at startup if the SensorBase can be contacted. Default: "true" if multi-shell is disabled. If multishell is enabled, then set to false.

See Also:
Constant Field Values

SENSORSHELL_STATECHANGE_INTERVAL_KEY

public static final java.lang.String SENSORSHELL_STATECHANGE_INTERVAL_KEY
The property key retrieving an integer indicating the number of seconds between "wakeups" of tool subprocesses that check for state changes. Typically used by editors such as Emacs or Eclipse to provide a standard measure of developer activity. Default: "30".

See Also:
Constant Field Values

SENSORSHELL_AUTOSEND_TIMEINTERVAL_KEY

public static final java.lang.String SENSORSHELL_AUTOSEND_TIMEINTERVAL_KEY
The property key retrieving a double indicating how many minutes between autosends of sensor data when not in MultiShell mode. If "0.0", then sensor data is not sent unless the client invokes the send() method explicitly. This value typically varies from 1.0 to 10.0 (i.e. 1 to 10 minutes). Default: "1.0".

See Also:
Constant Field Values

SENSORSHELL_AUTOSEND_MAXBUFFER_KEY

public static final java.lang.String SENSORSHELL_AUTOSEND_MAXBUFFER_KEY
The property key retrieving an integer indicating the maximum number of sensor instances to buffer locally between autosends of sensor data. If "0", then no maximum size is defined. Default: "250". Note that this is the value used when multishell is not enabled, otherwise the value associated with SENSORSHELL_MULTISHELL_MAXBUFFER_KEY is used.

See Also:
Constant Field Values

SENSORSHELL_LOGGING_LEVEL_KEY

public static final java.lang.String SENSORSHELL_LOGGING_LEVEL_KEY
The property key retrieving a string indicating the logging level for the SensorShell(s). Default: "INFO".

See Also:
Constant Field Values
Constructor Detail

SensorShellProperties

public SensorShellProperties()
                      throws SensorShellException
Initializes SensorShell properties using the default sensorshell.properties file. It could be located in user.home, or hackystat.user.home (if the user has set the latter in the System properties before invoking this constructor.)

Throws:
SensorShellException - If the SensorProperties instance cannot be instantiated due to a missing host, user, and/or password properties.

SensorShellProperties

public SensorShellProperties(java.io.File sensorFile)
                      throws SensorShellException
Creates a SensorShellProperties instance using the specified properties file. All unspecified properties are set to their built-in default values.

Parameters:
sensorFile - The sensorshell properties file to read.
Throws:
SensorShellException - If the SensorProperties instance cannot be instantiated due to a missing host, user, and/or password properties.

SensorShellProperties

public SensorShellProperties(java.lang.String host,
                             java.lang.String email,
                             java.lang.String password)
                      throws SensorShellException
Constructs a "basic" instance with the supplied three required properties. All other properties are assigned values from sensorshell.properties, or the built-in defaults if not specified there.

Use SensorShellProperties.getTestInstance to create an instance for testing purposes, since it will override certain properties that may be present in the sensorshell.properties file.

Parameters:
host - The hackystat host.
email - The user's email.
password - The user's password.
Throws:
SensorShellException - If the SensorProperties instance cannot be instantiated due to a missing host, user, and/or password properties.

SensorShellProperties

public SensorShellProperties(java.lang.String host,
                             java.lang.String email,
                             java.lang.String password,
                             java.util.Properties properties,
                             boolean overrideFile)
                      throws SensorShellException
Constructs an instance with the supplied three required properties and any other properties provided in the properties argument. Any remaining properties are assigned values from sensorshell.properties, or the built-in defaults if not specified there.

Parameters:
host - The hackystat host.
email - The user's email.
password - The user's password.
properties - A properties instance with other properties.
overrideFile - If true, then the passed properties override sensorshell.properties.
Throws:
SensorShellException - If the SensorProperties instance cannot be instantiated due to a missing host, user, and/or password properties.

SensorShellProperties

public SensorShellProperties(SensorShellProperties orig,
                             java.util.Properties newProps)
                      throws SensorShellException
Creates and returns a new SensorShellProperties instance which is initialized to the contents of the passed SensorProperties instance, with additional new properties overriding the previous selection.

Parameters:
orig - The original properties.
newProps - The replacing properties.
Throws:
SensorShellException - If the SensorProperties instance cannot be instantiated due to invalid or missing properties.

SensorShellProperties

public SensorShellProperties(java.util.Properties properties,
                             boolean overrideFile)
                      throws SensorShellException
Creates a SensorShell properties instance, initializing it using the passed properties as well as any settings found in the sensorshell.properties file. If overrideFile is true, then the passed properties and settings will override matching properties and settings found in the sensorshell.properties file. If false, then the property settings found in the sensorshell.properties will override the passed properties.

This constructor enables the user to provide default settings in sensorshell.properties for things like MultiSensorShell, but enable a tool to provide command line args that could override these defaults. The tool could do this by processing its command line args, then creating a Properties instance containing the overridding values, then passing that in to this constructor.

If overrideFile is false, then these properties will only take effect if the user has not specified them in their sensorshell.properties file.

Standard properties not specified by either the sensorshell.properties file or the passed properties instance will be given default values.

Parameters:
properties - The properties.
overrideFile - If true, then the passed properties will override any matching sensorshell.properties properties.
Throws:
SensorShellException - if problems occur.
Method Detail

getTestInstance

public static SensorShellProperties getTestInstance(java.lang.String host,
                                                    java.lang.String email,
                                                    java.lang.String password)
                                             throws SensorShellException
Constructs a "test" instance with the supplied three required properties.

This testing-only factory class sets the three required properties, and overrides the following properties for testing purposes:

All remaining properties are set to their built-in default values.

Parameters:
host - The hackystat host.
email - The user's email.
password - The user's password.
Returns:
the new SensorShellProperties instance.
Throws:
SensorShellException - If the SensorProperties instance cannot be instantiated due to a missing host, user, and/or password properties.

getProperty

public final java.lang.String getProperty(java.lang.String key)
Returns the trimmed property value associated with the property key. This is useful for clients who want to look for "non-standard" properties supplied in sensorshell.properties. For standard properties, clients should use the accessor methods, since these will perform type conversion.

Parameters:
key - The parameter key.
Returns:
The trimmed property value associated with this property key, or null if not found.

getSensorBaseHost

public java.lang.String getSensorBaseHost()
Returns the sensorbase host, such as "http://dasha.ics.hawaii.edu:9876/sensorbase".

Returns:
The sensorbase host.

getSensorBasePassword

public java.lang.String getSensorBasePassword()
Returns the password for this user, such as "xu876csld".

Returns:
The user password.

getSensorBaseUser

public java.lang.String getSensorBaseUser()
Returns the account for this user, such as "johnson@hawaii.edu".

Returns:
The user account.

getAutoSendTimeInterval

public double getAutoSendTimeInterval()
Returns the AutoSend time interval, such as 1.0.

Returns:
The autosend interval.

getAutoSendMaxBuffer

public int getAutoSendMaxBuffer()
Returns the AutoSend batch size, such as 250.

Returns:
The autosend batch size.

getStateChangeInterval

public int getStateChangeInterval()
Returns the StateChange interval.

Returns:
The state change interval in seconds.

getTimeout

public int getTimeout()
Returns the current timeout setting for non-Ping requests.

Returns:
The timeout in seconds.

getPingTimeout

public int getPingTimeout()
Returns the current timeout setting for Ping requests.

Returns:
The ping timeout in seconds.

getLoggingLevel

public java.util.logging.Level getLoggingLevel()
Returns the logging level specified for SensorShells.

Returns:
The logging level.

isMultiShellEnabled

public boolean isMultiShellEnabled()
Returns true if multishell processing is enabled.

Returns:
True if multishell processing.

getMultiShellNumShells

public int getMultiShellNumShells()
Returns the number of shells to instantiate if multishell processing is enabled.

Returns:
The number of shells to instantiate.

getMultiShellBatchSize

public int getMultiShellBatchSize()
Returns the number of instances to send to one shell in a row if multishell processing.

Returns:
The number of instances to send to one shell in a row.

getMultiShellMaxBuffer

public int getMultiShellMaxBuffer()
Returns the maximum number of instances to buffer before a blocking send is invoked in multishell mode.

Returns:
The maximum number of instances to buffer.

getMultiShellAutoSendTimeInterval

public double getMultiShellAutoSendTimeInterval()
Returns the MultiShell AutoSend time interval, such as 0.10.

Returns:
The multishell autosend interval.

isOfflineCacheEnabled

public boolean isOfflineCacheEnabled()
Returns true if offline cache data saving is enabled.

Returns:
True if offline caching enabled.

isOfflineRecoveryEnabled

public boolean isOfflineRecoveryEnabled()
Returns true if offline data recovery is enabled.

Returns:
True if offline data recovery enabled.

toString

public java.lang.String toString()
Returns the set of SensorProperties as a multi-line string. Does not print out the value associated with SENSORSHELL_PASSWORD_KEY.

Overrides:
toString in class java.lang.Object
Returns:
The Sensor property keys and values.

switchToMultiShellMode

public void switchToMultiShellMode()
Sets the autosend time interval and autosend max buffer size to the multishell versions. Invoked by the multishell just before instantiating its child SingleSensorShells so that they are set up with the appropriate multishell time interval.


getOfflineMode

public static SensorShellProperties getOfflineMode(SensorShellProperties properties)
                                            throws SensorShellException
Returns a new SensorShellProperties instance customized for offline data recovery. This means that multishell, autosend, and offline recovery/caching are all disabled.

Parameters:
properties - The original properties.
Returns:
The new SensorShellProperties instance.
Throws:
SensorShellException - If something goes wrong.