Package com.randomnoun.common

Class PropertyParser

java.lang.Object
com.randomnoun.common.PropertyParser
public class PropertyParser extends Object
The PropertyParser class parses a property definition text file into a Properties object.

This parser differs from the standard Properties parser in that sections can be marked off for particular regions (e.g. properties that only take effect in development, or when run on certain machines). The current region is specified by the com.randomnoun.common.mode system property set on the VM commandline. If this system property is not set, the region defaults to the value "localhost-dev-unknown". An alternate constructor exists if you wish to specify the region manually.

Environments are specified in 'machine-release-subsystem' format, with each segment set as follows:

  • machine - the hostname of the system (in lowercase)
  • release - the development phase of the system (either set to dev, xpt, prd for development, acceptance or production
  • subsystem - the subsystem that this VM represents.

Properties are specified in the standard "propertyName=propertyValue" method. Whitespace is removed from either side of the '=' character. New-lines can be specified in the property value by using the escape sequence '\n'. Lines can be continued over a single line by placing the character '\' at at the end of the line to be continued; e.g. 

   property1=value1
   property2=this is a very long value for property2, which spans \
             over a single line.

Properties that are specific to a particular region should be surrounded by the lines "STARTENVIRONMENT environmentMask" and "ENDENVIRONMENT environmentMask". Individual properties can be defined for a region by prefixing the line with "ENV environmentMask"; e.g. 

   property1=all regions

   STARTENVIRONMENT *-xpt-*
     property2=this property only set in acceptance region
     property3=same for this property
   ENDENVIRONMENT

   STARTENVIRONMENT dtp11523-dev-*
     property2=these properties only set in the development region
     property3=running on the host dtp11523
   ENDENVIRONMENT

   ENV *-prd-* property4=this property only visible in production

As shown above, the '*' character can be used to specify a property across multiple regions. The keywords 'STARTENVIRONMENT', 'ENDENVIRONMENT' and 'ENV' are case-insensitive

You can now also specify environments based on the values of previously-defined properties; this allows a simple #ifdef style facility. There are two types of syntax, which use regex matching or simple string matching; e.g. 

   enable.fileAct=true
   compound.property=123-456-789
 
   STARTENVIRONMENT enable.fileAct = true
     # these properties are only set when enable.fileAct is set to true
   ENDENVIRONMENT
   STARTENVIRONMENT compound.property =~ *-789
     # these properties are only set when compound.property ends with -789
   ENDENVIRONMENT

Property files can contain any number of blank lines, or comments (lines starting with the '#' character), which will be ignored by the parser.

Any occurences of the string "\n" in a property value will be replaced by a newline character.

A property make also contain a List, rather than a string, by including the index of the list item in square brackets in the property key; e.g. 

   listname[1]=first element
   listname[3]=third element

This implementation returns an ArrayList of Strings for these types of declarations. Undeclared array elements that appear before the last index will return null.

If you want to create a list, but the index of the elements is unknown (they are dependant on other properties, for example), then you can use a "*" to denote the next available list index, or leave it empty to denote the last used list index; e.g. 

 testList[0].a=a-value 0
 testList[0].b=b-value 0
 testList[0].c=a-value 0
  
 testList[1].a=a-value 1
 testList[1].b=b-value 1
 testList[1].c=a-value 1
  
 testList[*].a=a-value 2
 testList[].b=b-value 2
 testList[].c=a-value 2
will generate a three-element list, each of which contains a map with three key/value pairs.

Properties that appear multiple times will take the value of the last-specified value.

Author:
knoxg

  • Field Details

    • logger

      public static final org.apache.log4j.Logger logger
      Logger instance for this class

  • Constructor Details

    • PropertyParser

      public PropertyParser(Reader reader, String environmentID)
      Create a new Parser object. Note that parsing does not begin until the Parse method is called on this object.
      Parameters:
      reader - The source of the site definition text.
      environmentID - The environment ID in which to parse this text.

    • PropertyParser

      public PropertyParser(Reader reader)
      Create a new Parser object. Note that parsing does not begin until the Parse method is called on this object. Assumes a DEV environment
      Parameters:
      reader - The source of the site definition text.

  • Method Details

    • parse

      public PropertyParser.PropertiesWithComments parse() throws ParseException, IOException
      Generates a Properties object from the input stream.
      Returns:
      A valid Properties object.
      Throws:
      IOException
      ParseException

    • restrict

      public static Map<? extends Object,? extends Object> restrict(Map<Object,Object> properties, String prefix, boolean removePrefix)
      Returns a subset of a Properties object. The subset is determined by only returning those key/value pairs whose keys begin with a set prefix. e.g. if 'a' contains the properties 
         customer.1.name=fish
   customer.1.description=Patagonian toothfish
   customer.2.name=hunter
   customer.2.description=Patagonian toothfish hunter
   customer.11.name=spear
   customer.11.description=Patagonian toothfish hunter's spear

      then calling restrict(a, "customer.1", false) will return: 

         customer.1.name=fish
   customer.1.description=Patagonian toothfish

      setting the 'removePrefix' to true will remove the initial prefix from the returned property list; restrict(a, "customer.1", true) in this case will then return: 

         name=fish
   description=Patagonian toothfish

      Note that the prefix passed in to this method has no trailing period, but each property must contain that period (to prevent customer.11 from being returned in the example above).

      If 'properties' is set to null, then this method will return null. If 'prefix' is set to null, then this method will return the entire property list.

      Parameters:
      properties - The initial property list that we wish to restrict
      prefix - The prefix used to restrict the property list
      removePrefix - If set to true, the result keys will be stripped of the initial prefix text
      Returns:
      A restricted property list.

    • main

      public static void main(String[] args) throws IOException, ParseException
      Method used to test the parser from the command line. The file to parse is specified on the command line; if missing, then it uses 'test.properties' as the default.
      Parameters:
      args -
      Throws:
      IOException
      ParseException