com.marringtons.string
Class Properties

java.lang.Object
  com.marringtons.string.Properties

public class Properties

extends Object

This class extends and simplified the application propertie file interface provided by java.util.Properties. It will also search the data path for a properties file to load. All the setters return the string value being set. This can be useful for additional recording (as in logs). It is possible to flag a property so that code can be informed if the property changes.

 
  
   Properties myCodes = new Properties( "myCodes"); // find and load myCodes.properties.txt
  
   String p1 = myCodes.get( "p1key");
   String p2 = myCodes.get( "p2key", "defaultP2");	// return default if key not found
   int p3 = myCodes.check( "p3key", 3);	// throw an exception if p3 is not an integer
   int p4 = myCodes.get( "p4key", 4);		// will return default if p4 is not an integer
   int p5 = myCodes.check( "p5key", true);	// throw an exception if p3 is not a known boolean
   int p6 = myCodes.get( "p6key", false);		// will return default if p4 is not a known boolean
  
   myCodes.set( "p7key = p7value");
   myCodes.set( "p8key", "p8value");
   myCodes.set( "p8key", 8);
   myCodes.set( "p9key", true);
  
   if (! myCodes.load( "myCodes")) Application.error( "Could not find 'myCodes.properties.txt'");
  
   // Iterate through the properties
   for (String key = properties.first();  key != null;  key = properties.next())
     Log.message( key + "=" + properties.get( key));
  
   // Use properties to store messages with variable parameters
   catch (Exception exception)
     {
       String message = "Can't scrape field "+baseEntry.className+"."+key;
       String stamp = Log.error( message, exception);
       problems.set( key, "{0} (see log reference {1})", new String[] { message, stamp});
     }
  
   // Properties can be dumped in human readable form in key: value format, 1 per line):
   System.out( myCodes.toString);
   
  
 

Author:

Paul Marrington

Nested Class Summary

static interface

Properties.Change Give this interface to the rare class that needs to be informed of when a property or properties change.

Field Summary

Map	map map stores properties - and exposed for direct access.

Constructor Summary

Properties()
Initialiser Properties.

Properties(Properties preload)
Initialiser Properties.

Properties(String fileName)
Initialiser - Properties.

Method Summary

boolean	check(String key, boolean defaultValue) Retrieve a boolean property, with default.
int	check(String key, int defaultValue) test numeric and retrieve an integer property, with default.
void	deregister(String key, Properties.Change with) Remove registration of a class with a variable change.
String	first() Used to iterate through all the properties.
String	get(String key) Method get - retrieve a string property.
boolean	get(String key, boolean defaultValue) retrieve a boolean property, with default.
int	get(String key, int defaultValue) retrieve an integer property, with default.
int[]	get(String key, int[] defaultValues) Retrieve a comma separated array of integers.
long	get(String key, long defaultValue) retrieve an integer property, with default.
Set	get(String key, Set set) Retrieve a comma separated array of strings.
String	get(String key, String defaultValue) retrieve a string property, with default.
String[]	get(String key, String[] defaultValues) Retrieve a comma separated array of strings.
String[]	getList(String key) Properties with the same key are maintained in a list.
boolean	load(InputStream stream, String name) Load properties from a stream.
void	load(Properties other) Load properties from another properties object.
boolean	load(String file) Load properties from a file.
String	next() Used to iterate through all the properties.
void	preload(Map preLoadedMap) If you have a name/value pair string map from another source (say an MVC), it can be laoded here.
void	register(String key, Properties.Change with) Call to register an instance to be told if a property changes.
void	save(String userConfigurationFileName) Save a changed configuration to disk.
String	set(String property) Set a string property from a name/value pair.
String	set(String key, boolean value) Set a boolean property.
String	set(String key, long value) Set an integer property.
String	set(String key, String value) Set a string property.
int	size() Return the number of property entries that currently exist.
String	toString() Override toString to provide a better representation.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

map

public Map map

map stores properties - and exposed for direct access.

Constructor Detail

Properties

public Properties()

Initialiser Properties.

 Properties config = new Properties();
 

See Also:

Object

Properties

public Properties(String fileName)

Initialiser - Properties.

 Properties properties = new Properties( propertiesFileName);
 

Parameters:

fileName - look for and load properties from file fileName.properties.txt on data path

Properties

public Properties(Properties preload)

Initialiser Properties.

 Properties properties = new Properties( System.getProperties());
 

Parameters:

preload - properties to preload with.

Method Detail

get

public String get(String key)

Method get - retrieve a string property.

 String fileSep = properties.get( "file.separator");
 

Parameters:

key - property key to look for

Returns:

property (returns null if property not found)

getList

public String[] getList(String key)

Properties with the same key are maintained in a list. In most cases get() retrieving the most recent is correct. For some, all entries have importance.

Parameters:

key - property name

Returns:

array of related properties.

get

public String get(String key,
                  String defaultValue)

retrieve a string property, with default.

 String path = properties.get( "mypath", "/temp");
 

Parameters:

key - property key to look for

defaultValue - default to use if property does not exist

Returns:

property (always returns property or default)

get

public String[] get(String key,
                    String[] defaultValues)

Retrieve a comma separated array of strings.

 String defaults[] = {"one","two","three"};
 defaults = properties.get( "list", defaults);
 

Parameters:

key - property key to look for

defaultValues - default to use if property does not exist

Returns:

array of csv values related to a property.

get

public int[] get(String key,
                 int[] defaultValues)

Retrieve a comma separated array of integers.

 int defaults[] = {1,10,100};
 defaults = properties.get( "list", defaults);
 

Parameters:

key - property key to look for

defaultValues - default to use if property does not exist

Returns:

array of csv values related to a property.

Throws:

NumberFormatException

get

public Set get(String key,
               Set set)

Retrieve a comma separated array of strings.

 Set defaults = new HashSet();
 defaults = properties.get( "list", defaults);
 

Parameters:

key - property key to look for

set - default to use if property does not exist

Returns:

array of csv values related to a property.

check

public int check(String key,
                 int defaultValue)
          throws Convert.Exception

test numeric and retrieve an integer property, with default.

 try { int days = properties.check( "backup.removal", 28); }
 

Parameters:

key - property key to look for

defaultValue - default to use if property does not exist

Returns:

property (always returns property or default)

Throws:

Convert.Exception

get

public int get(String key,
               int defaultValue)

retrieve an integer property, with default.

 int days = properties.get( "backup.removal", 28);
 

Parameters:

key - property key to look for

defaultValue - default to use if property does not exist

Returns:

int property (always returns property or default)

get

public long get(String key,
                long defaultValue)

retrieve an integer property, with default.

 int days = properties.get( "backup.removal", 28);
 

Parameters:

key - property key to look for

defaultValue - default to use if property does not exist

Returns:

int property (always returns property or default)

check

public boolean check(String key,
                     boolean defaultValue)
              throws Convert.Exception

Retrieve a boolean property, with default.

 try { boolean	 allowed = properties.check( "edit_permission", false); }
 

Parameters:

key - property key to look for

defaultValue - default to use if property does not exist

Returns:

boolean property (always returns property or default)

Throws:

Convert.Exception

See Also:

Convert.toBoolean(String)

get

public boolean get(String key,
                   boolean defaultValue)

retrieve a boolean property, with default.

 boolean allowed = properties.check( "edit_permission", false);
 

Parameters:

key - property key to look for

defaultValue - default to use if property does not exist

Returns:

property (always returns property or default)

See Also:

Convert.toBoolean(String)

set

public String set(String property)

Set a string property from a name/value pair.

Parameters:

property - as in key=value

Returns:

the formatted value set

set

public String set(String key,
                  String value)

Set a string property.

Parameters:

key - of property to set

value - of property to set

Returns:

the formatted value set

set

public String set(String key,
                  long value)

Set an integer property.

Parameters:

key - of property to set

value - of property to set

Returns:

the formatted value set

set

public String set(String key,
                  boolean value)

Set a boolean property.

Parameters:

key - of property to set

value - of property to set

Returns:

the formatted value set

load

public boolean load(String file)

Load properties from a file.

 load( "myfile") || load( "default");
 

Parameters:

file - path and name of file to open

Returns:

true if property file exists and was loaded correctly

load

public boolean load(InputStream stream,
                    String name)

Load properties from a stream.

 load( reader.getInputStream());
 

Parameters:

stream - input stream to read properties from

name - path and name of open stream - used for display only

Returns:

boolean true if loaded correctly

load

public void load(Properties other)

Load properties from another properties object. Used to load properties from separate configuration file.

Parameters:

other - properties file to copy in.

preload

public void preload(Map preLoadedMap)

If you have a name/value pair string map from another source (say an MVC), it can be laoded here.

Parameters:

preLoadedMap - Map of String name/value pairs.

size

public int size()

Return the number of property entries that currently exist.

Returns:

the number of property entries set.

save

public void save(String userConfigurationFileName)
          throws FileNotFoundException

Save a changed configuration to disk.

Parameters:

userConfigurationFileName - being the name of the user configuration file.

Throws:

FileNotFoundException

first

public String first()

Used to iterate through all the properties.

Returns:

The first key (or null of none).

See Also:

next()

next

public String next()

Used to iterate through all the properties.

Returns:

The next key (or null of no more).

See Also:

first()

toString

public String toString()

Override toString to provide a better representation.

Returns:

a human readable list of problems - sorted by key (key: value).

register

public void register(String key,
                     Properties.Change with)

Call to register an instance to be told if a property changes. Normally, calling get() is more than adequate - but in rare high frequently used code it is better to register here and be able to read a primative and know it is being kept up-to-date.

Parameters:

key - Key to register to be informed if it is changed.

with - Class with Change interface to inform.

deregister

public void deregister(String key,
                       Properties.Change with)

Remove registration of a class with a variable change. Call this before your instance goes out of scope or it will live in memory forever.

Parameters:

key - Key registered for Change that we want to remove.

with - Class with Change interface to deregister.