edu.isi.pegasus.common.util
Class CommonProperties

java.lang.Object
  edu.isi.pegasus.common.util.CommonProperties

public class CommonProperties
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: 4651 $

Author:

Jens-S. Vöckler, Yong Zhao, Karan Vahi, Mats Rynge

Field Summary

private File	m_binDir The bin dir of the Pegasus install
private static CommonProperties	m_instance implements the singleton access via class variable.
private Properties	m_props internal set of properties.
private File	m_schemaDir Location of our schemas
private File	m_sharedStateDir GNU: modifiable architecture-independent data in DIR [PREFIX/share/pegasus].
private File	m_sysConfDir GNU: read-only single-machine data in DIR [PREFIX/etc].
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

CommonProperties(String confProperties) 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	getBinDir() Accessor pegasus bin directory
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	getSchemaDir() Accessor to schema directory
File	getSharedStateDir() Accessor to $PEGASUS_HOME/com.
File	getSysConfDir() Accessor to $PEGASUS_HOME/etc.
static CommonProperties	instance() Singleton threading: Creates the one and only instance of the properties in the current application.
void	list(PrintStream out) Print out the property list onto the specified stream.
static void	main(String[] args)
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 CommonProperties	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 CommonProperties	nonSingletonInstance(String confProperties) Create a temporary property that is not attached to the Singleton.
private File	pickPath(String p1, String p2)
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 CommonProperties 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_binDir

private File m_binDir

The bin dir of the Pegasus install

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/share/pegasus]. 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_schemaDir

private File m_schemaDir

Location of our schemas

PROPERTY_FILENAME

public static final String PROPERTY_FILENAME

Basename of the file to read to obtain system properties

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

CommonProperties

protected CommonProperties(String confProperties)
                    throws IOException,
                           MissingResourceException

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

Parameters:

confProperties - the path to conf properties, that supersede the loading of properties from $PEGASUS_HOME/.pegasusrc

Throws:

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

MissingResourceException - will be thrown if not all required properties are set

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.

pickPath

private File pickPath(String p1,
                      String p2)

instance

public static CommonProperties 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 CommonProperties nonSingletonInstance(String confProperties)
                                             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:

confProperties - the path to conf properties, that supersede the loading of properties from $PEGASUS_HOME/.pegasusrc

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 CommonProperties 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()

getBinDir

public File getBinDir()

Accessor pegasus bin directory

Returns:

the "bin" directory of the Pegasus 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.

getSchemaDir

public File getSchemaDir()

Accessor to schema directory

Returns:

the schema directoru

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

list

public void list(PrintStream out)

Print out the property list onto the specified stream. This method is useful for debugging, and meant for debugging.

Parameters:

out - an output stream

Throws:

ClassCastException - if any key is not a string.

See Also:

Properties.list( PrintStream )

main

public static void main(String[] args)
                 throws IOException

Throws:

IOException