edu.isi.pegasus.common.util

## Class CommonProperties

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

All Implemented Interfaces:
  java.lang.Cloneable

    public class CommonProperties
    extends java.lang.Object
    implements java.lang.Cloneable

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$
Author:
  Jens-S. Vöckler, Yong Zhao, Karan Vahi, Mats Rynge

### Field Summary

Fields
`private java.io.File` `m_binDir` The bin dir of the Pegasus install
`private static CommonProperties` `m_instance` implements the singleton access via class variable.
`private java.util.Properties` `m_props` internal set of properties.
`private java.io.File` `m_schemaDir` Location of our schemas
`private java.io.File` `m_sharedStateDir` GNU: modifiable architecture-independent data in DIR [PREFIX/share/pegasus].
`private java.io.File` `m_sysConfDir` GNU: read-only single-machine data in DIR [PREFIX/etc].
`static java.lang.String` `PROPERTY_FILENAME` Basename of the file to read to obtain system properties
`static java.lang.String` `USER_PROPERTY_FILENAME` Basename of the (new) file to read for user properties.

### Constructor Summary

Constructors
`protected` `CommonProperties(java.lang.String confProperties)` ctor.

### Method Summary

All Methods Static Methods Instance Methods Concrete Methods
`protected static java.util.Properties` `addProperties(java.util.Properties a, java.util.Properties b)` Adds new properties to an existing set of properties while substituting variables.
`java.lang.Object` `clone()` Returns the clone of the object.
`private static java.util.Properties` `defaultProps()` Set some defaults, should values be missing in the dataset.
`java.io.File` `getBinDir()` Accessor pegasus bin directory
`java.lang.String` `getProperty(java.lang.String key)` Accessor: access to the internal properties as read from file.
`java.lang.String` `getProperty(java.lang.String key, java.lang.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.
`java.io.File` `getSchemaDir()` Accessor to schema directory
`java.io.File` `getSharedStateDir()` Accessor to $PEGASUS_HOME/com.
`java.io.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(java.io.PrintStream out)` Print out the property list onto the specified stream.
`static void` `main(java.lang.String[] args)`
`static java.util.Properties` `matchingSubset(java.util.Properties properties, java.lang.String prefix, boolean keepPrefix)` Extracts a specific property key subset from the properties passed.
`java.util.Properties` `matchingSubset(java.lang.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(java.lang.String confProperties)` Create a temporary property that is not attached to the Singleton.
`private java.io.File` `pickPath(java.lang.String p1, java.lang.String p2)`
`java.util.Enumeration` `propertyNames()` Accessor: enumerate all keys known to this property collection
`java.lang.Object` `setProperty(java.lang.String key, java.lang.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

`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 java.util.Properties m_props

internal set of properties. Direct access is expressly forbidden.

#### m_binDir

    private java.io.File m_binDir

The bin dir of the Pegasus install

#### m_sysConfDir

    private java.io.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 java.io.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 java.io.File m_schemaDir

Location of our schemas

#### PROPERTY_FILENAME

    public static final java.lang.String PROPERTY_FILENAME

Basename of the file to read to obtain system properties

See Also:
  Constant Field Values

#### USER_PROPERTY_FILENAME

    public static final java.lang.String USER_PROPERTY_FILENAME

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

See Also:
  Constant Field Values

### Constructor Detail

#### CommonProperties

    protected CommonProperties(java.lang.String confProperties)
                        throws java.io.IOException,
                               java.util.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:
  `java.io.IOException` - will be thrown if reading the property file goes awry.
  `java.util.MissingResourceException` - will be thrown if not all required properties are set

### Method Detail

#### addProperties

    protected static java.util.Properties addProperties(java.util.Properties a,
                                                        java.util.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 java.util.Properties defaultProps()

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

Returns:
  the properties.

#### pickPath

    private java.io.File pickPath(java.lang.String p1,
                                  java.lang.String p2)

#### instance

    public static CommonProperties instance()
                                     throws java.io.IOException,
                                            java.util.MissingResourceException

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

Returns:
  a reference to the properties.
Throws:
  `java.io.IOException` - will be thrown if reading the property file goes awry.
  `java.util.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(java.lang.String confProperties)
                                                 throws java.io.IOException,
                                                        java.util.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:
  `java.io.IOException` - will be thrown if reading the property file goes awry.
  `java.util.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 java.io.File getBinDir()

Accessor pegasus bin directory

Returns:
  the "bin" directory of the Pegasus runtime system.

#### getSysConfDir

    public java.io.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 java.io.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 java.io.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 java.lang.String getProperty(java.lang.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 java.lang.String getProperty(java.lang.String key,
                                        java.lang.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 java.lang.Object setProperty(java.lang.String key,
                                        java.lang.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 java.util.Enumeration propertyNames()

Accessor: enumerate all keys known to this property collection

Returns:
  an enumerator for the keys of the properties.

#### matchingSubset

    public java.util.Properties matchingSubset(java.lang.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 java.util.Properties matchingSubset(java.util.Properties properties,
                                                      java.lang.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(java.io.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:
  `java.lang.ClassCastException` - if any key is not a string.
See Also:
  `Properties.list( PrintStream )`

#### main

    public static void main(java.lang.String[] args)
                     throws java.io.IOException

Throws:
  `java.io.IOException`

#### clone

    public java.lang.Object clone()

Returns the clone of the object.

Overrides:
  `clone` in class `java.lang.Object`
Returns:
  the clone