Re: NSProperties order of priority (app/framework/command line)?

com.webobjects.foundation
Class NSProperties

This class extends Java's properties mechanism to merges various properties from the application properties with the standard system properties so that they are all available using the java.lang.System.getProperties method. The application properties can come from four sources: argument parameters from the command line, the file WebObjects.properties in the user's home directory the application's Properties file, and the Properties files of any frameworks the application includes, in that order of precedence.and the file WebObjects.properties in the user's home directory

This class has only static methods and cannot be instantiated.

This class would have benefitted from inheriting key-value-coding for 'getProperty'.

The Properties File

The application and any framework can include a file named Properties in its Resources. The Properties file must be in the format specified by java.io.Properties.

Boolean values, NSArrays, and NSDictionaries must be specified using the property list representation. See the NSPropertyListSerialization class description for more information on property lists.

Command Line Properties

The setPropertiesFromArgv method parses the cFor command line arguments and recognizes to be recognized as properties, they must fit the property formats listed in the table below.

Properties specified in these formats will be available as System properties after you invoke setPropertiesFromArgv.

Accessing the Properties

To access the application properties you first need to merge the application and command line properties with the System properties. AThe application properties are automatically merged with the System properties when a WebObjects application starts up. automatically performs this step for you. You can then access the property as a string, and convert the string to the property's actual data type.

To obtain the application properties and merge them with the System properties you have to invoke setPropertiesFromArgv.

Every property is a key-value pair. For example, on Mac OS X, the property value for the key "java.vendor" is "Apple Computer, Inc.". To access a property corresponding to a particular key, use the java.lang.System.getProperty method. This method which returns the property as a string.

If the property string represents a value other than java.lang.String, for example, "TRUE" for a boolean value, the String value, "("San Francisco", "New York", "Seoul", "London", "Seattle", "Shanghai")" for an NSArray, or the String value, "{ user = wshakesp; birth = 1564; death = 1616; }" for an NSDictionary, you can convert it to the appropriate data type using the NSPropertyListSerialization's booleanForString, arrayForString, or dictionaryForString method, respectively. NSPropertyListSerialization also provides an intForString method to simplify converting a property string to an integer.

More on the representation of non-String properties as strings can be found in the document: "Property List Programming Guide for Cocoa".

NSProperties

public NSProperties()

arrayForKey

public static NSArray arrayForKey(String aKey)

Deprecated. Instead, find the System property using System.getProperty and convert the property to a string using NSPropertyListSerialization.arrayForString.

Parameters:

aKey - input key whose property will be converted to NSArray

Returns:

System property specified by aKey or null if no System property with that name exists

Throws:

NullPointerException - aKey is null

See Also:

System.getProperty(java.lang.String), NSPropertyListSerialization.arrayForString(java.lang.String)

booleanForKey

public static boolean booleanForKey(String aKey)

Deprecated. Instead, find the System property using System.getProperty and convert it to a boolean using NSPropertyListSerialization.booleanForString.

Parameters:

aKey - input key whose property will be converted to boolean

Returns:

System property specified by aKey or false if no System property with that name exists

Throws:

NullPointerException - aKey is null

See Also:

System.getProperty(java.lang.String), NSPropertyListSerialization.booleanForString(java.lang.String)

dataForKey

public static NSData dataForKey(String aKey)

Deprecated. Instead, find the System property using System.getProperty, convert the property to a property list using NSPropertyListSerialization.propertyListFromString, and convert the property list to an NSData object using NSPropertyListSerialization.dataFromPropertyList.

Parameters:

aKey - input key whose property will be converted to NSData

Returns:

System property value or NSData.EmptyData if no System property with that name exists

Throws:

NullPointerException - aKey is null

See Also:

System.getProperty(java.lang.String), NSPropertyListSerialization.propertyListFromString(java.lang.String), NSPropertyListSerialization.dataFromPropertyList(java.lang.Object)

dictionaryForKey

public static NSDictionary dictionaryForKey(String aKey)

Deprecated. Instead, find the System property using System.getProperty and convert the property to an NSDictionary using NSPropertyListSerialization.dictionaryForString

Parameters:

aKey - input key whose property will be converted to NSDictionary

Returns:

System property value or NSDictionary.EmptyDictionary if no System property with that name exists

Throws:

NullPointerException - aKey is null

See Also:

System.getProperty(java.lang.String), NSPropertyListSerialization.dictionaryForString(java.lang.String)

doubleForKey

public static double doubleForKey(String aKey)

Deprecated. Instead, find the System property using System.getProperty and convert the property to a double.

Parameters:

aKey - input key whose property will be converted to a double

Returns:

System property value or 0 if no System property with that name exists

Throws:

NullPointerException - aKey is null

See Also:

System.getProperty(java.lang.String)

floatForKey

public static float floatForKey(String aKey)

Deprecated. Instead, find the System property using System.getProperty and and convert the property to a float.

Parameters:

aKey - input key whose property will be converted to a float

Returns:

System property value or 0 if the System property indicated by aKey does not exist

Throws:

NullPointerException - aKey is null

See Also:

System.getProperty(java.lang.String)

getProperty

public static String getProperty(String name)

getProperty

public static String getProperty(String name,
                                 String defaultValue)

integerForKey

public static int integerForKey(String aKey)

Deprecated. Instead, find the System property using System.getProperty and convert it to an integer using NSPropertyListSerialization.intForString.

Parameters:

aKey - input key whose property will be converted to an integer

Returns:

System property specified by aKey or 0 if no System property with that name exists

Throws:

NullPointerException - aKey is null

See Also:

System.getProperty(java.lang.String), NSPropertyListSerialization.intForString(java.lang.String)

longForKey

public static long longForKey(String aKey)

Deprecated. Instead, find the System property using System.getProperty and and convert the property to a long.

Parameters:

aKey - input key whose property will be converted to a long

Returns:

System property value or 0 if the property indicated by aKey does not exist

Throws:

NullPointerException - aKey is null

See Also:

System.getProperty(java.lang.String)

setPropertiesFromArgv

public static void setPropertiesFromArgv(String[] argv)

Loads all of the application's properties from all the four three sources described in the class description and merges them with the Java System properties.

This method obtains the properties for every bundle in the application including the application and all of the frameworks it includes. It also merges any properties specified by the string array argv into the System properties.

This method is called by WOApplication, so by the time the application is running usefully all the various application properties have been merged with the System properties.

This method is of very little value for the application programmer -- the actual command line arguments are not available, and this method cannnot be over-ridden. It can add properties from a general String array to the System properties.

Parameters:

argv - a String array representing extra properties to be merged into System properties

See Also:

Properties

stringForKey

public static String stringForKey(String aKey)

Deprecated. Use System.getProperty(java.lang.String).

This method will be replaced by finding the System property using System.getProperty(key).

Equivalent to System.getProperty(key).

Parameters:

aKey - System property being inquired

Returns:

value of the property specified by aKey

valuesFromArgv

public static NSDictionary valuesFromArgv(String[] argv)

Parses a String array of properties. Usually, this String array comes from the command line and its format is described in the class description.

This method is of very little value for the application programmer -- the actual command line arguments are not available, and this method cannnot be over-ridden. There are much easier ways to create an NSDictionary of key/value pairs.

Parameters:

argv - a String array of properties to be parsed

Returns:

the parsed properties in an NSDictionary format

See Also:

NSDictionary