edu.duke.cs.banjo.data.settings
Class Settings

java.lang.Object
  extended byedu.duke.cs.banjo.data.settings.Settings

public class Settings
extends java.lang.Object

Manages the initial, validated, and dynamically updated parameters that are used by the various search algorithms.

Details:
Contains the data shared by different objects involved in the search process. This includes the initial parameters (i.e., loaded via settings file, in raw, unvalidated form), their validated counterparts, and the dynamic parameters (the ones that are changing over the life of a search).

By keeping this data outside of the core Searcher/Proposer/Evaluator/Decider objects, we simplify communication between our core objects, without sacrificing performance.

Change History:
Created on May 17, 2004

9/14/2005 (v1.0.4) hjs Changes to properly handle discretization of multiple observation files

10/19/2005 (v2.0) hjs Large-scale refactoring of the settings processing New features: - support for default settings - use of SettingsItem class (hierarchy)

(v2.1) hjs Pulled observation processing and file I/O inside for support of multi-threading. Extensive refactoring.

3/24/2008 (v2.2) hjs Add wrapper functions for accessing random sequences.

Author:
Jurgen Sladeczek (hjs)
For the latest info, please visit www.cs.duke.edu.

Field Summary
protected  BanjoRandomNumber banjoRandomNumber
           
protected static long baseRandomSeed
           
protected  java.util.Set collectedErrors
           
protected  java.util.Set collectedWarnings
           
protected  java.lang.String[] commandLineParameters
           
protected  java.util.Properties defaultProcessParameters
           
protected  java.util.Properties dynamicProcessParameters
           
protected  FileUtil fileUtil
           
protected  java.util.Set generalProcessDataStorage
           
protected  java.util.TreeSet highScoreStructureSet
           
protected  java.util.Properties initialProcessParametersAsLoaded
           
protected  java.util.Properties initialProcessParametersLowercase
           
protected  java.util.Properties loadedSettings
           
protected static ObservationsI observations
           
protected  java.util.Properties passedInParameters
           
protected  java.util.Set processedSettings
           
protected  java.util.Set registeredSettings
           
protected  java.util.Properties validatedSettings
           
 
Constructor Summary
Settings()
          Basic constructor that simply sets up the internal data for the settings object.
Settings(Settings _settings)
          Constructor based on an existing settings.
Settings(Settings _settings, int _threadIndex)
          Constructor based on an existing settings.
 
Method Summary
 void addToErrors(BanjoError _errorItem)
          Add a single error to the collectedErrors set.
 void addToErrors(BanjoError _errorItem, java.lang.Exception e)
          Add a single error to the collectedErrors set.
 void addToErrors(java.util.Set _errorItems)
          Adds a set of errors to the collectedErrors set.
 void addToGeneralProcessDataStorage(java.lang.Object objectToAdd)
           
protected  void addToProcessedSettings(SettingItem _settingItem)
           
 void addToWarnings(BanjoError _warningItem)
          Add a single warning to the collectedWarnings set.
 void addToWarnings(java.util.Set _warningItems)
          Adds a set of warnings to the collectedWarnings set.
protected  java.util.Properties assignProperties(java.util.Properties _propertiesToAssign)
          Helper function to make a copy of a Properties object.
protected  java.util.Set assignSet(java.util.Set _setToAssign)
          Helper function to make a copy of a set of objects (of types SettingItem, String, or BanjoError)
protected  void checkForDeprecatedSettings(java.lang.String _settingName)
           
protected  void checkForUnregisteredSettings(java.lang.String _settingName)
           
protected  void combineParameters()
           
 java.lang.StringBuffer compileErrorMessages()
           
 java.util.Set compileRegisteredSettings()
          Utility function that compiles a list of the settings that are known to be valid within the current version of Banjo (as provided by the BANJO class.
 java.lang.StringBuffer compileWarningMessages()
           
protected  java.lang.String formatForDisplay(java.lang.String _textToFormat)
          Applies formatting to the supplied string.
 long getBanjoSeed()
           
 java.util.Set getCollectedErrors()
          Get the set of collected errors.
 java.util.Set getCollectedWarnings()
          Get the set of collected warnings.
 java.lang.String getDynamicProcessParameter(java.lang.String _parameterName)
          Gets the value of the specified dynamic process parameter.
 java.util.Properties getDynamicProcessParameters()
           
 java.util.Set getGeneralProcessDataStorage()
           
 java.util.TreeSet getHighScoreStructureSet()
           
 java.lang.String getInitialProcessParameterLowercase(java.lang.String _settingName)
           
 ObservationsI getObservations()
           
 java.lang.StringBuffer getOptionalThreadInfo()
           
 java.util.Set getProcessedSettings()
           
 java.util.Random getRandomSequence()
           
 java.lang.String getSettingItemValueAsLoaded(java.lang.String _settingName)
           
 java.lang.String getSettingItemValueAsValidated(java.lang.String _settingName)
           
 int getStorageSize()
           
 java.lang.String getValidatedProcessParameter(java.lang.String _settingName)
           
 boolean isSettingValueValid(java.lang.String _settingName)
           
protected  java.util.Properties loadFileBasedParameters()
           
 void loadObservations()
           
protected  java.util.Properties loadPassedInParameters(java.lang.String[] _applicationParameters)
           
 void loadSettings(Settings _settings)
          Loads the settings based on the parameters from an existing settings object.
protected  void loadSettings(java.lang.String[] _applicationParameters)
          Loads the settings based on the (typically: commandline) parameters provided by the user.
protected  java.lang.String parseForTokens(java.lang.String _stringToParse)
           
 java.lang.String parseForTokensAfterValidation(java.lang.String _stringToParse)
           
 void prepareFileOutput()
           
 void prepareXMLOutput()
           
 void processCommandLine(java.lang.String[] _applicationParameters)
          Method to superseed the constructor with command line arguments.
 SettingItem processSetting(java.lang.String _settingNameCanonical, java.lang.String _settingNameDescriptive, java.lang.String _settingNameForDisplay, java.lang.String _settingDataType, int _validationType, java.lang.Object _additionalInfo, java.lang.Object _defaultValue)
          Processes the supplied setting.
 void recordError(java.lang.String _strErrorMessage)
           
 void setBanjoSeed(long _randomSeed)
           
 void setDynamicProcessParameter(java.lang.String _parameterName, java.lang.String _parameterValue)
          Sets the dynamic process parameter to the supplied value.
 void setHighScoreStructureSet(java.util.TreeSet highScoreStructureSet)
           
 void setObservations(ObservationsI _observations)
           
 void setValidatedProcessParameter(java.lang.String _settingName, java.lang.String _settingValue)
          Sets the validated process parameter (setting) to the supplied value.
 java.lang.String toString()
           
protected  boolean validateReportFiles()
           
 boolean validateRequiredData()
           
 java.lang.String[] validateXMLresultFiles()
           
 boolean wereThereProblems()
          Checks if the process encountered any (fatal) problems.
 void writeStringToFile(java.lang.String _fileName, java.lang.String _dataToWrite, boolean _traceToConsole)
           
 void writeToFile(java.util.Collection _outputFileFlags, java.lang.StringBuffer _stringBufferToWrite)
           
 void writeTraceToFile(java.lang.String _dataToWrite, boolean _traceToConsole, int _traceFileID)
           
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

baseRandomSeed

protected static final long baseRandomSeed

commandLineParameters

protected java.lang.String[] commandLineParameters

initialProcessParametersAsLoaded

protected final java.util.Properties initialProcessParametersAsLoaded

initialProcessParametersLowercase

protected final java.util.Properties initialProcessParametersLowercase

passedInParameters

protected java.util.Properties passedInParameters

loadedSettings

protected java.util.Properties loadedSettings

defaultProcessParameters

protected java.util.Properties defaultProcessParameters

dynamicProcessParameters

protected java.util.Properties dynamicProcessParameters

highScoreStructureSet

protected java.util.TreeSet highScoreStructureSet

generalProcessDataStorage

protected java.util.Set generalProcessDataStorage

registeredSettings

protected java.util.Set registeredSettings

processedSettings

protected java.util.Set processedSettings

collectedErrors

protected java.util.Set collectedErrors

collectedWarnings

protected java.util.Set collectedWarnings

validatedSettings

protected java.util.Properties validatedSettings

observations

protected static ObservationsI observations

fileUtil

protected FileUtil fileUtil

banjoRandomNumber

protected BanjoRandomNumber banjoRandomNumber
Constructor Detail

Settings

public Settings()
         throws java.lang.Exception
Basic constructor that simply sets up the internal data for the settings object.


Settings

public Settings(Settings _settings)
         throws java.lang.Exception
Constructor based on an existing settings. Note that this constructor does a "deep" copy.

Parameters:
_settings - The settings that we want to use as basis for the new object.

Settings

public Settings(Settings _settings,
                int _threadIndex)
         throws java.lang.Exception
Constructor based on an existing settings. Note that this constructor does a "deep" copy.

Parameters:
_settings - The settings that we want to use as basis for the new object.
Method Detail

processCommandLine

public void processCommandLine(java.lang.String[] _applicationParameters)
                        throws java.lang.Exception
Method to superseed the constructor with command line arguments. Note: Due to the expanded role of the settings class ("processData"), it is really important that we have a valid settings object immediately from the very start. This is not guaranteed when we use the original constructor that included the processing of the command line arguments.

Parameters:
_applicationParameters - The list of parameters provided.
Throws:
java.lang.Exception

loadSettings

public void loadSettings(Settings _settings)
                  throws java.lang.Exception
Loads the settings based on the parameters from an existing settings object.

Parameters:
_settings - The existing settings object to be used as basis for loading.
Throws:
java.lang.Exception

loadSettings

protected void loadSettings(java.lang.String[] _applicationParameters)
                     throws java.lang.Exception
Loads the settings based on the (typically: commandline) parameters provided by the user.

Parameters:
_applicationParameters - The list of parameters provided by the user to the Banjo application
Throws:
java.lang.Exception

assignProperties

protected java.util.Properties assignProperties(java.util.Properties _propertiesToAssign)
Helper function to make a copy of a Properties object.

Parameters:
_propertiesToAssign - The properties to use as the basis of the assignment.

assignSet

protected java.util.Set assignSet(java.util.Set _setToAssign)
Helper function to make a copy of a set of objects (of types SettingItem, String, or BanjoError)

Parameters:
_setToAssign - The set to assign to.

combineParameters

protected void combineParameters()
                          throws java.lang.Exception
Throws:
java.lang.Exception

compileRegisteredSettings

public java.util.Set compileRegisteredSettings()
Utility function that compiles a list of the settings that are known to be valid within the current version of Banjo (as provided by the BANJO class.


checkForUnregisteredSettings

protected void checkForUnregisteredSettings(java.lang.String _settingName)

checkForDeprecatedSettings

protected void checkForDeprecatedSettings(java.lang.String _settingName)

parseForTokens

protected java.lang.String parseForTokens(java.lang.String _stringToParse)

parseForTokensAfterValidation

public java.lang.String parseForTokensAfterValidation(java.lang.String _stringToParse)

loadFileBasedParameters

protected java.util.Properties loadFileBasedParameters()
                                                throws java.lang.Exception
Throws:
java.lang.Exception

loadPassedInParameters

protected java.util.Properties loadPassedInParameters(java.lang.String[] _applicationParameters)
                                               throws java.lang.Exception
Throws:
java.lang.Exception

validateReportFiles

protected boolean validateReportFiles()
                               throws java.lang.Exception
Throws:
java.lang.Exception

validateRequiredData

public boolean validateRequiredData()
                             throws java.lang.Exception
Throws:
java.lang.Exception

validateXMLresultFiles

public java.lang.String[] validateXMLresultFiles()
                                          throws java.lang.Exception
Throws:
java.lang.Exception

compileErrorMessages

public java.lang.StringBuffer compileErrorMessages()

compileWarningMessages

public java.lang.StringBuffer compileWarningMessages()

addToProcessedSettings

protected void addToProcessedSettings(SettingItem _settingItem)

getProcessedSettings

public java.util.Set getProcessedSettings()

getSettingItemValueAsValidated

public java.lang.String getSettingItemValueAsValidated(java.lang.String _settingName)

getSettingItemValueAsLoaded

public java.lang.String getSettingItemValueAsLoaded(java.lang.String _settingName)

isSettingValueValid

public boolean isSettingValueValid(java.lang.String _settingName)

addToErrors

public void addToErrors(java.util.Set _errorItems)
Adds a set of errors to the collectedErrors set.


addToErrors

public void addToErrors(BanjoError _errorItem)
Add a single error to the collectedErrors set.


addToErrors

public void addToErrors(BanjoError _errorItem,
                        java.lang.Exception e)
Add a single error to the collectedErrors set.


getCollectedErrors

public java.util.Set getCollectedErrors()
Get the set of collected errors.


addToWarnings

public void addToWarnings(java.util.Set _warningItems)
Adds a set of warnings to the collectedWarnings set.


addToWarnings

public void addToWarnings(BanjoError _warningItem)
Add a single warning to the collectedWarnings set.


getCollectedWarnings

public java.util.Set getCollectedWarnings()
Get the set of collected warnings.


wereThereProblems

public boolean wereThereProblems()
                          throws java.lang.Exception
Checks if the process encountered any (fatal) problems.

Throws:
java.lang.Exception

processSetting

public SettingItem processSetting(java.lang.String _settingNameCanonical,
                                  java.lang.String _settingNameDescriptive,
                                  java.lang.String _settingNameForDisplay,
                                  java.lang.String _settingDataType,
                                  int _validationType,
                                  java.lang.Object _additionalInfo,
                                  java.lang.Object _defaultValue)
                           throws java.lang.Exception
Processes the supplied setting.

Throws:
java.lang.Exception

formatForDisplay

protected java.lang.String formatForDisplay(java.lang.String _textToFormat)
Applies formatting to the supplied string.


getInitialProcessParameterLowercase

public java.lang.String getInitialProcessParameterLowercase(java.lang.String _settingName)
Returns:
Returns the initialProcessParametersLowercase.

getValidatedProcessParameter

public java.lang.String getValidatedProcessParameter(java.lang.String _settingName)
Returns:
Returns the value of the specified validated setting.

setValidatedProcessParameter

public void setValidatedProcessParameter(java.lang.String _settingName,
                                         java.lang.String _settingValue)
                                  throws java.lang.Exception
Sets the validated process parameter (setting) to the supplied value.

Throws:
java.lang.Exception

getDynamicProcessParameter

public java.lang.String getDynamicProcessParameter(java.lang.String _parameterName)
Gets the value of the specified dynamic process parameter.


setDynamicProcessParameter

public void setDynamicProcessParameter(java.lang.String _parameterName,
                                       java.lang.String _parameterValue)
Sets the dynamic process parameter to the supplied value.


getDynamicProcessParameters

public java.util.Properties getDynamicProcessParameters()
Returns:
Returns the dynamicProcessParameters.

addToGeneralProcessDataStorage

public void addToGeneralProcessDataStorage(java.lang.Object objectToAdd)
Parameters:
objectToAdd - The object to add to the generalProcessDataStorage set.

getGeneralProcessDataStorage

public java.util.Set getGeneralProcessDataStorage()
Returns:
Returns the generalProcessDataStorage.

getStorageSize

public int getStorageSize()
Returns:
Returns the size of the generalProcessDataStorage.

getHighScoreStructureSet

public java.util.TreeSet getHighScoreStructureSet()
Returns:
Returns the highScoreStructureSet.

setHighScoreStructureSet

public void setHighScoreStructureSet(java.util.TreeSet highScoreStructureSet)
Parameters:
highScoreStructureSet - The highScoreStructureSet to set.

toString

public java.lang.String toString()
Returns:
Convenient display of the current sets of parameters (validated and passed-in). Lists items within sets in alphabetic order.

getOptionalThreadInfo

public java.lang.StringBuffer getOptionalThreadInfo()
                                             throws java.lang.Exception
Throws:
java.lang.Exception

getObservations

public ObservationsI getObservations()
Returns:
Returns the observations.

setObservations

public void setObservations(ObservationsI _observations)
Parameters:
_observations - The observations to set.

loadObservations

public void loadObservations()
                      throws java.lang.Exception
Throws:
java.lang.Exception

writeToFile

public void writeToFile(java.util.Collection _outputFileFlags,
                        java.lang.StringBuffer _stringBufferToWrite)
                 throws java.lang.Exception
Throws:
java.lang.Exception

writeStringToFile

public void writeStringToFile(java.lang.String _fileName,
                              java.lang.String _dataToWrite,
                              boolean _traceToConsole)
                       throws java.lang.Exception
Throws:
java.lang.Exception

writeTraceToFile

public void writeTraceToFile(java.lang.String _dataToWrite,
                             boolean _traceToConsole,
                             int _traceFileID)
                      throws java.lang.Exception
Throws:
java.lang.Exception

recordError

public void recordError(java.lang.String _strErrorMessage)
                 throws java.lang.Exception
Throws:
java.lang.Exception

prepareFileOutput

public void prepareFileOutput()
                       throws java.lang.Exception
Throws:
java.lang.Exception

prepareXMLOutput

public void prepareXMLOutput()
                      throws java.lang.Exception
Throws:
java.lang.Exception

getRandomSequence

public java.util.Random getRandomSequence()

getBanjoSeed

public long getBanjoSeed()

setBanjoSeed

public void setBanjoSeed(long _randomSeed)