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

Wed, 30 Nov 2005 09:49:44 -0800 

At 10:57 AM +1100 11/29/05, Lachlan Deck wrote:
My reading of the NSProperties API leads me to believe that the order of priority for preferences are as follows (but it's not explicitly stated)... 


... what a coincidence!!  I just re-documented NSProperties (manually 
edited Javadoc enclosed) as an example of how far off target a lot of 
the WO Javadoc is.  The portion in question here says: "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."


    That is, in your numbering: 1, 4, 2, 3


Attachment:
%NSProperties.html

Description: application/applefile











  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.




	

		
			Format
		
		
		
		
			Example
		
	

	

		
			-Dkey=value
		
		
			 
		
		
			-DWOPort=4321
		
	

	

		
			-key value
		
		
			 
		
		
			-WOAutoOpenInBrowser NO
		
	





	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".









	

	 


	

		
			 Constructor Summary
		
	

	

		
			NSProperties() 
			

			           
				
	



  



 


	

		
			 Method Summary
		
	

	

		
			 static NSArray
		
		
			arrayForKey(String aKey) 
			

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

	

		
			 static boolean
		
		
			booleanForKey(String aKey) 
			

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

	

		
			 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.
				
	

	

		
			 static NSDictionary
		
		
			dictionaryForKey(String aKey) 
			

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

	

		
			 static double
		
		
			doubleForKey(String aKey) 
			

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

	

		
			 static float
		
		
			floatForKey(String aKey) 
			

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

	

		
			 static String
		
		
			getProperty(String name) 
			

			           
				
	

	

		
			 static String
		
		
			getProperty(String name, String defaultValue) 
			

			           
				
	

	

		
			 static int
		
		
			integerForKey(String aKey) 
			

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

	

		
			 static long
		
		
			longForKey(String aKey) 
			

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

	

		
			 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 is called for you -- calling it again
    does no good!
				
	

	

		
			 static String
		
		
			stringForKey(String aKey) 
			

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

	

		
			 static NSDictionary
		
		
			valuesFromArgv(String[] argv) 
			

               Parses
    a String array of properties. Also not very
    useful.
				
	



 

 


	

		
			Methods inherited from class java.lang.Object
		
	

	

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



  




	

	 


	

		
			 Constructor Detail
		
	






 NSProperties
 
public NSProperties()
 







 


	

		
			 Method Detail
		
	






 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
		

	






Copyright © 2005 Apple Computer, Inc. 



 _______________________________________________
Do not post admin requests to the list. They will be ignored.
Webobjects-dev mailing list      ([email protected])
Help/Unsubscribe/Update your Subscription:
http://lists.apple.com/mailman/options/webobjects-dev/archive%40mail-archive.com

This email sent to [email protected]





















					Reply via email to