org.locomotive.server
Class MultiConfig

java.lang.Object
  |
  +--org.locomotive.server.MultiConfig

public abstract class MultiConfig
extends java.lang.Object

A handy config file that allows the specification of multiple values per name and the reading of data either from the method call data passed in or from a file path specified. After parsing the config data you can then get them with the traditional getString and getInt methods found in org.locomotive.server.Config or you can ask for specific indexes. You should extend this class and override the setupDefaults function to make your own configs. This version does not use string constraints. Nor does it have any command line stuff. Nor does it print to standard out. As such, errors are reported (as they kind of are in the old Config) with exceptions and the like, so watch those ConfigInitializationException's and ConfigNotFoundException's. It does some constraining based on type. The strings that represent integers have to be Integer.parseInt'able, the strings have to be non-null and non-emptystring. Right now the email constraints are the same as strings, though we may put in a x@x constraint for it... It also allows you to turn off the name-checking... that is, you can have "unknown" config variables be read in and set. Override enforceConfigTypes to do this (see it for more info.) Override getDefaultConfigTypes to tell this parser what to expect on this unfamiliar lines (it won't try to guess for you...)


Field Summary
static int EMAIL
           
static int INTEGER
           
static int[] ONE_EMAIL_TYPE
           
static int[] ONE_INT_TYPE
           
static int[] ONE_STRING_TYPE
          These three members are the type arrays, provided for convenience only. I.e.
static int STRING
          These three members STRING, INTEGER, and EMAIL are type values you can use when specifying an array of types for the addConfig method.
static int[] TWO_EMAIL_TYPE
           
static int[] TWO_INT_TYPE
           
static int[] TWO_STRING_TYPE
          Same as above, only containing two-in-a-row, just in case it's handy.
 
Constructor Summary
MultiConfig(java.lang.String string_data, boolean isFile)
          Make the config object with the file path or the string data as specified.
 
Method Summary
protected  boolean addConfig(java.lang.String name, java.lang.String[] vals, int[] types, java.lang.String desc)
          Create and add a config entry to the cache we're maintaining.
 boolean enforceConfigTypes()
          Override this function to simply return true or false.
 java.lang.String getConfigFilePath()
          Gives us the file path this config file was constructed with (null if it was actually constructed with string config data passed in...)
 java.util.Enumeration getConfigNamesEnumeration()
          Returns the enumeration of all the config entry names (i.e.
 java.lang.String getConfigStringData()
          Gives us the string config data given to the config object when it was created (null if it was actually created with a file path.)
 int[] getDefaultConfigTypes()
          If the enforceConfigNames method you implement returns false, then when the parser encoutners a strange line it will use the types specified in this method as the default form of the line.
 int getInt(java.lang.String name)
          Gets the first element of the array of integers that come from the config entry that matches the key (i.e.
 int[] getIntArray(java.lang.String name)
          Returns the array of integer values for the config entry matching the supplied name (i.e.
 int getIntByIndex(java.lang.String name, int index)
          Gets the array of integers matching the key passed in in "name" and returns the value found at the index specified - will throw an exception if the index specified is invalid for this config entry or "name" is null or "" or if the config entry found is the null object.
 java.lang.String getString(java.lang.String name)
          Gets the first element of the array of strings that come from the config entry that matches the key (i.e.
 java.lang.String[] getStringArray(java.lang.String name)
          Returns the array of string objects for the config entry matching the supplied name (i.e.
 java.lang.String getStringByIndex(java.lang.String name, int index)
          Gets the array of strings matching the key passed in in "name" and returns the string found at the index specified - will throw an exception if the index specified is invalid for this config entry or "name" is null or "" or the config entry found is the null object.
 boolean isFromFile()
          Tells us if this config file came from a file path that we loaded.
 boolean isFromString()
          Tells us if this config file came from string information given to it in the constructor method call.
protected  java.lang.String[] oneString(java.lang.String instring)
          Give a string array of one element as provided.
abstract  boolean setupDefaults()
          Override this method as shown below to set up your own configs.
 java.lang.String toString()
          Calls the other toString with false.
 java.lang.String toString(boolean verbose)
          Standard toString with a twist - the boolean determines if the descriptive text comes out as well.
protected  java.lang.String[] twoString(java.lang.String instringone, java.lang.String instringtwo)
          Give a string array of two elements as provided.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

STRING

public static final int STRING
These three members STRING, INTEGER, and EMAIL are type values you can use when specifying an array of types for the addConfig method.

INTEGER

public static final int INTEGER

EMAIL

public static final int EMAIL

ONE_STRING_TYPE

public static final int[] ONE_STRING_TYPE
These three members are the type arrays, provided for convenience only. I.e. instead of "new int[] {INTEGER}" you can just use one of these (in the case of that example, just use "INTEGER").

ONE_INT_TYPE

public static final int[] ONE_INT_TYPE

ONE_EMAIL_TYPE

public static final int[] ONE_EMAIL_TYPE

TWO_STRING_TYPE

public static final int[] TWO_STRING_TYPE
Same as above, only containing two-in-a-row, just in case it's handy. I.e. "TWO_STRING_TYPE" is equivalent to "new int[] {STRING, STRING}".

TWO_INT_TYPE

public static final int[] TWO_INT_TYPE

TWO_EMAIL_TYPE

public static final int[] TWO_EMAIL_TYPE
Constructor Detail

MultiConfig

public MultiConfig(java.lang.String string_data,
                   boolean isFile)
            throws ConfigInitializationException
Make the config object with the file path or the string data as specified. If isFile is true, it will interperet the string as a file path and try to load it. If isFile is false it will use the string passed in as the config file itself. I.e. this string should then contain all the newlines and formatting and everything that the actual config file would were it an external file. Throws an ConfigInitializationException if it sees errors loading a file or checking the supplied strings against their type constraints. Use within a program with no file access might look like this: StringBuffer sb = new StringBuffer(123); sb.append("OTHER_EXAMPLE stringone stringtwo\n"); sb.append("YET_ANOTHER_EXAMPLE stringone stringtwo 323 stringthree\n"); sb.append("AND_ANOTHER_EXAMPLE stringone 457\n"); MultiConfigExtension mc = new MultiConfigExtension(sb.toString(), false); Config files and the strings of the same content are pretty felxible. White space is ignored. Newlines signify a new data item, the first item on the line is the name and following items (seperated by whitespace) are its associated values.
Parameters:
string_data - a filepath or a buffer of data in the config format
isFile - true if string_data is a file
Throws:
ConfigInitializationException - if the string data is bogus or if there was trouble loading from the file
Method Detail

setupDefaults

public abstract boolean setupDefaults()
Override this method as shown below to set up your own configs. Historical Note: some example configs are from the original MAS. boolean setupDefaults() { boolean b = true; b &= addConfig ("MAS_EXAMPLE", new String[] {"1.0b3"}, new int[] {STRING}, "MAS System Version String"); b &= addConfig ("LOCO_EXAMPLE", new String[] {"5420"}, new int[] {INTEGER}, "TCP Port for Application Server"); b &= addConfig ("AND_ANOTHER_EXAMPLE", new String[] {"stringone", "457"}, new int[] {STRING, INTEGER}, "another example"); b &= addConfig ("MAS_VERSION", oneString("1.0b3"), ONE_STRING_TYPE, "MAS System Version String"); b &= addConfig ("LOCO_PORT", oneString("5420"), ONE_INT_TYPE, "TCP Port for Application Server"); b &= addConfig ("OTHER_EXAMPLE", twoString("stringone", "stringtwo"), TWO_STRING_TYPE, "another example"); b &= addConfig ("YET_ANOTHER_EXAMPLE", new String[] {"stringone", "stringtwo"}, TWO_STRING_TYPE, "another example"); b &= addConfig ("AND_THE_LAST_ONE", twoString("stringone", "hi"), new int[] {STRING, STRING}, "descriptive text"); return(b); }

enforceConfigTypes

public boolean enforceConfigTypes()
Override this function to simply return true or false. If it returns true then the config object will expect that it knows the form of any line it encounters. If it returns false then it will look to getDefaultConfigTypes() for the form and try to make the line fit that. This implementation (i.e. the default) returns true.

getDefaultConfigTypes

public int[] getDefaultConfigTypes()
If the enforceConfigNames method you implement returns false, then when the parser encoutners a strange line it will use the types specified in this method as the default form of the line. Lines that don't match this form will be rejected with errors. If the enforceConfigNames method you implement returns true, this will never be called. You can override this method to specify what form the parser should assume when it encounters unfmailiar lines and the enforceConfigTypes function returns false. This implementation (i.e. the default) returns ONE_STRING_TYPE.

isFromFile

public boolean isFromFile()
Tells us if this config file came from a file path that we loaded.

isFromString

public boolean isFromString()
Tells us if this config file came from string information given to it in the constructor method call.

getConfigFilePath

public java.lang.String getConfigFilePath()
Gives us the file path this config file was constructed with (null if it was actually constructed with string config data passed in...)

getConfigStringData

public java.lang.String getConfigStringData()
Gives us the string config data given to the config object when it was created (null if it was actually created with a file path.)

addConfig

protected boolean addConfig(java.lang.String name,
                            java.lang.String[] vals,
                            int[] types,
                            java.lang.String desc)
Create and add a config entry to the cache we're maintaining.
Parameters:
name - the name, or key, of the entry you wish to create
vals - the array of strings that represent the values you wish to add
types - the array of types that describe the values you are adding (see INTEGER, STRING, EMAIL, et. al. above for info about types). Each type value in this array should correspond to the string value in the same position of the array.
desc - the string description of the config entry, perhaps containing info about each value in the array, perhaps not.

getStringArray

public java.lang.String[] getStringArray(java.lang.String name)
                                  throws ConfigNotFoundException
Returns the array of string objects for the config entry matching the supplied name (i.e. key) - will throw an exception if "name" is null or "" or the config entry found is the null object.
Parameters:
name - the name of the config
Throws:
if - a config of the mentioned name is not available

getIntArray

public int[] getIntArray(java.lang.String name)
                  throws ConfigNotFoundException
Returns the array of integer values for the config entry matching the supplied name (i.e. key) - will throw an exception if "name" is null or "" or the config entry found is the null object.
Parameters:
name - the name of the config
Throws:
if - a config of the mentioned name is not available

getStringByIndex

public java.lang.String getStringByIndex(java.lang.String name,
                                         int index)
                                  throws ConfigNotFoundException
Gets the array of strings matching the key passed in in "name" and returns the string found at the index specified - will throw an exception if the index specified is invalid for this config entry or "name" is null or "" or the config entry found is the null object.
Parameters:
name - the name of the config
index - - the position of the requested data in the string array
Throws:
if - a config of the mentioned name is not available

getIntByIndex

public int getIntByIndex(java.lang.String name,
                         int index)
                  throws ConfigNotFoundException
Gets the array of integers matching the key passed in in "name" and returns the value found at the index specified - will throw an exception if the index specified is invalid for this config entry or "name" is null or "" or if the config entry found is the null object.
Parameters:
name - the name of the config
index - - the position of the requested data in the int array
Throws:
if - a config of the mentioned name is not available

getString

public java.lang.String getString(java.lang.String name)
                           throws ConfigNotFoundException
Gets the first element of the array of strings that come from the config entry that matches the key (i.e. "name") specified.
Parameters:
name - the name of the configuration value
Throws:
if - a config of the mentioned name is not available
See Also:
getStringByIndex

getInt

public int getInt(java.lang.String name)
           throws ConfigNotFoundException
Gets the first element of the array of integers that come from the config entry that matches the key (i.e. "name") specified.
Parameters:
name - the name of the configuration value
Throws:
if - a config of the mentioned name is not available
See Also:
getIntByIndex

toString

public java.lang.String toString(boolean verbose)
Standard toString with a twist - the boolean determines if the descriptive text comes out as well.

toString

public java.lang.String toString()
Calls the other toString with false.
Overrides:
toString in class java.lang.Object

getConfigNamesEnumeration

public java.util.Enumeration getConfigNamesEnumeration()
Returns the enumeration of all the config entry names (i.e. an enumeration of all the keys).

oneString

protected java.lang.String[] oneString(java.lang.String instring)
Give a string array of one element as provided. For use with addConfig.

twoString

protected java.lang.String[] twoString(java.lang.String instringone,
                                       java.lang.String instringtwo)
Give a string array of two elements as provided. For use with addConfig.