org.griphyn.common.util
Class VDSProperties

java.lang.Object
  org.griphyn.common.util.VDSProperties

public class VDSProperties
extends Object

This class creates a common interface to handle package properties. The package properties are meant as read-only (so far, until requirements crop up for write access). The class is implemented as a Singleton pattern.

Version:

$Revision: 70 $

Author:

Jens-S. V??ckler, Yong Zhao, Karan Vahi

Field Summary

private File	m_dataDir GNU: read-only architecture-independent data in DIR [PREFIX/share].
private String	m_home internal copy of a system property.
private static VDSProperties	m_instance implements the singleton access via class variable.
private File	m_localStateDir GNU: modifiable single-machine data in DIR [PREFIX/var].
private Properties	m_props internal set of properties.
private File	m_sharedStateDir GNU: modifiable architecture-independent data in DIR [PREFIX/com].
private File	m_sysConfDir GNU: read-only single-machine data in DIR [PREFIX/etc].
static String	OLD_USER_PROPERTY_FILENAME Basename of the (old) file to read for user properties.
static String	PROPERTY_FILENAME Basename of the file to read to obtain system properties
static String	USER_PROPERTY_FILENAME Basename of the (new) file to read for user properties.

Constructor Summary

protected

VDSProperties(String propFilename) ctor.

Method Summary

protected static Properties	addProperties(Properties a, Properties b) Adds new properties to an existing set of properties while substituting variables.
private static Properties	defaultProps() Set some defaults, should values be missing in the dataset.
File	getDataDir() Accessor to $PEGASUS_HOME/share.
File	getLocalStateDir() Accessor to $PEGASUS_HOME/var.
String	getPegasusHome() Accessor: Obtains the root directory of the Pegasus runtime system.
String	getProperty(String key) Accessor: access to the internal properties as read from file.
String	getProperty(String key, String defValue) Accessor: access to the internal properties as read from file An existing system property of the same key will have precedence over any project property.
File	getSharedStateDir() Accessor to $PEGASUS_HOME/com.
File	getSysConfDir() Accessor to $PEGASUS_HOME/etc.
String	getVDSHome() Accessor: Obtains the root directory of the VDS runtime system.
static VDSProperties	instance() Singleton threading: Creates the one and only instance of the properties in the current application.
static Properties	matchingSubset(Properties properties, String prefix, boolean keepPrefix) Extracts a specific property key subset from the properties passed.
Properties	matchingSubset(String prefix, boolean keepPrefix) Extracts a specific property key subset from the known properties.
static VDSProperties	noHassleInstance() Singleton interface: Creates the one and only instance of the properties in the current application, and does not bother the programmer with exceptions.
static VDSProperties	nonSingletonInstance(String propFilename) Create a temporary property that is not attached to the Singleton.
Enumeration	propertyNames() Accessor: enumerate all keys known to this property collection
Object	setProperty(String key, String value) Accessor: Overwrite any properties from within the program.
int	size() Accessor: Obtains the number of properties known to the project.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

m_instance

private static VDSProperties m_instance

implements the singleton access via class variable.

m_props

private Properties m_props

internal set of properties. Direct access is expressly forbidden.

m_home

private String m_home

internal copy of a system property. There is read-only access.

m_dataDir

private File m_dataDir

GNU: read-only architecture-independent data in DIR [PREFIX/share]. The files in this directory have a low change frequency, are effectively read-only, can be shared via a networked FS, and they are usually valid for multiple users.

m_sysConfDir

private File m_sysConfDir

GNU: read-only single-machine data in DIR [PREFIX/etc]. The files in this directory have a low change frequency, are effectively read-only, they reside on a per-machine basis, and they are usually valid for a single user.

m_sharedStateDir

private File m_sharedStateDir

GNU: modifiable architecture-independent data in DIR [PREFIX/com]. The files in this directory have a high change frequency, are effectively read-write, can be shared via a networked FS, and they are usually valid for multiple users.

m_localStateDir

private File m_localStateDir

GNU: modifiable single-machine data in DIR [PREFIX/var]. The files in this directory have a high change frequency, are effectively read-write, they reside on a per-machine basis, and they are usually valid for a single user.

PROPERTY_FILENAME

public static final String PROPERTY_FILENAME

Basename of the file to read to obtain system properties

See Also:

Constant Field Values

OLD_USER_PROPERTY_FILENAME

public static final String OLD_USER_PROPERTY_FILENAME

Basename of the (old) file to read for user properties. Warning, the old name will eventually fall prey to bit rot.

See Also:

Constant Field Values

USER_PROPERTY_FILENAME

public static final String USER_PROPERTY_FILENAME

Basename of the (new) file to read for user properties.

See Also:

Constant Field Values

Constructor Detail

VDSProperties

protected VDSProperties(String propFilename)
                 throws IOException,
                        MissingResourceException

ctor. This initializes the local instance of properties from a central file.

Parameters:

propFilename - is the basename of the file to read. This file will be looked for in the $PEGASUS_HOME/etc directory. Usually, the name will be set from the PROPERTY_FILENAME constant above. Alternatively, the name will be ignored, if an alternative properties location is specified via -Dpegasus.properties.

Throws:

IOException - will be thrown if reading the property file goes awry.

MissingResourceException - will be thrown if you forgot to specify the -Dpegasus.home=$PEGASUS_HOME to the runtime environment.

Method Detail

addProperties

protected static Properties addProperties(Properties a,
                                          Properties b)

Adds new properties to an existing set of properties while substituting variables. This function will allow value substitutions based on other property values. Value substitutions may not be nested. A value substitution will be ${property.key}, where the dollar-brace and close-brace are being stripped before looking up the value to replace it with. Note that the ${..} combination must be escaped from the shell.

Parameters:

a - is the initial set of known properties (besides System ones)

b - is the set of properties to add to a

Returns:

the combined set of properties from a and b.

defaultProps

private static Properties defaultProps()

Set some defaults, should values be missing in the dataset.

Returns:

the properties.

instance

public static VDSProperties instance()
                              throws IOException,
                                     MissingResourceException

Singleton threading: Creates the one and only instance of the properties in the current application.

Returns:

a reference to the properties.

Throws:

IOException - will be thrown if reading the property file goes awry.

MissingResourceException - will be thrown if you forgot to specify the -Dpegasus.home=$PEGASUS_HOME to the runtime environment.

See Also:

noHassleInstance()

nonSingletonInstance

public static VDSProperties nonSingletonInstance(String propFilename)
                                          throws IOException,
                                                 MissingResourceException

Create a temporary property that is not attached to the Singleton. This may be helpful with portal, which do magic things during the lifetime of a process.

Parameters:

propFilename - is the full path name to the location of the properties file to read. In case of null, the default location will be taken

Returns:

a reference to the parsed properties.

Throws:

IOException - will be thrown if reading the property file goes awry.

MissingResourceException - will be thrown if you forgot to specify the -Dpegasus.home=$PEGASUS_HOME to the runtime environment.

See Also:

instance()

noHassleInstance

public static VDSProperties noHassleInstance()

Singleton interface: Creates the one and only instance of the properties in the current application, and does not bother the programmer with exceptions. Rather, exceptions from the underlying instance() call are caught, converted to an error message on stderr, and the program is exited.

Returns:

a reference to the properties.

See Also:

instance()

getVDSHome

public String getVDSHome()

Accessor: Obtains the root directory of the VDS runtime system. Kept to make ChimeraProperties.java to compile for time being

Returns:

the root directory of the Pegasus runtime system, as initially set from the system properties.

getPegasusHome

public String getPegasusHome()

Accessor: Obtains the root directory of the Pegasus runtime system.

Returns:

the root directory of the Pegasus runtime system, as initially set from the system properties.

getDataDir

public File getDataDir()

Accessor to $PEGASUS_HOME/share. The files in this directory have a low change frequency, are effectively read-only, can be shared via a networked FS, and they are valid for multiple users.

Returns:

the "share" directory of the VDS runtime system.

getSysConfDir

public File getSysConfDir()

Accessor to $PEGASUS_HOME/etc. The files in this directory have a low change frequency, are effectively read-only, they reside on a per-machine basis, and they are valid usually for a single user.

Returns:

the "etc" directory of the VDS runtime system.

getSharedStateDir

public File getSharedStateDir()

Accessor to $PEGASUS_HOME/com. The files in this directory have a high change frequency, are effectively read-write, they reside on a per-machine basis, and they are valid usually for a single user.

Returns:

the "com" directory of the VDS runtime system.

getLocalStateDir

public File getLocalStateDir()

Accessor to $PEGASUS_HOME/var. The files in this directory have a high change frequency, are effectively read-write, they reside on a per-machine basis, and they are valid usually for a single user.

Returns:

the "var" directory of the VDS runtime system.

size

public int size()

Accessor: Obtains the number of properties known to the project.

Returns:

number of properties in the project property space.

getProperty

public String getProperty(String key)

Accessor: access to the internal properties as read from file. An existing system property of the same key will have precedence over any project property. This method will remove leading and trailing ASCII control characters and whitespaces.

Parameters:

key - is the key to look up

Returns:

the value for the key, or null, if not found.

getProperty

public String getProperty(String key,
                          String defValue)

Accessor: access to the internal properties as read from file An existing system property of the same key will have precedence over any project property. This method will remove leading and trailing ASCII control characters and whitespaces.

Parameters:

key - is the key to look up

defValue - is a default to use, if no value can be found for the key.

Returns:

the value for the key, or the default value, if not found.

setProperty

public Object setProperty(String key,
                          String value)

Accessor: Overwrite any properties from within the program.

Parameters:

key - is the key to look up

value - is the new property value to place in the system.

Returns:

the old value, or null if it didn't exist before.

propertyNames

public Enumeration propertyNames()

Accessor: enumerate all keys known to this property collection

Returns:

an enumerator for the keys of the properties.

matchingSubset

public Properties matchingSubset(String prefix,
                                 boolean keepPrefix)

Extracts a specific property key subset from the known properties. The prefix may be removed from the keys in the resulting dictionary, or it may be kept. In the latter case, exact matches on the prefix will also be copied into the resulting dictionary.

Parameters:

prefix - is the key prefix to filter the properties by.

keepPrefix - if true, the key prefix is kept in the resulting dictionary. As side-effect, a key that matches the prefix exactly will also be copied. If false, the resulting dictionary's keys are shortened by the prefix. An exact prefix match will not be copied, as it would result in an empty string key.

Returns:

a property dictionary matching the filter key. May be an empty dictionary, if no prefix matches were found.

See Also:

is used to assemble matches

matchingSubset

public static Properties matchingSubset(Properties properties,
                                        String prefix,
                                        boolean keepPrefix)

Extracts a specific property key subset from the properties passed. The prefix may be removed from the keys in the resulting dictionary, or it may be kept. In the latter case, exact matches on the prefix will also be copied into the resulting dictionary.

Parameters:

prefix - is the key prefix to filter the properties by.

keepPrefix - if true, the key prefix is kept in the resulting dictionary. As side-effect, a key that matches the prefix exactly will also be copied. If false, the resulting dictionary's keys are shortened by the prefix. An exact prefix match will not be copied, as it would result in an empty string key.

Returns:

a property dictionary matching the filter key. May be an empty dictionary, if no prefix matches were found.

See Also:

is used to assemble matches