#include "api1/Cipres.idl"

module CipresIDL_api1
{
	/*
		Each user will be running his own properties service.  There is a system property
		file/store of properties that affect all users and a per user property store.  Values
		in the user property store override those in the system store.

		Errors:
			All the methods in this interface can fail due to a file I/O error.  In general,
			when a method impl can throw a native exception (e.g a java exception) due to 
			an unrecoverable error (e.g. the installation is corrupted, a file is missing, the
			disk is bad, the programmer really blew it) - we'll throw the exception from the impl 
			so that a corba system exception (UNKNOWN) is generated.  
	*/
	interface Properties: Scriptable, LifeCycle 
	{
		typedef string  NameValuePair[2];
		typedef sequence<NameValuePair> NameValuePairSeq;

		/*
			Getters return true if property exists, false otherwise.  A value that has only
			whitespace is treated the same as property doesn't exist (i.e. false is returned). 
			If property exists but can't be converted to the requested type a BadArgException 
			will be thrown.   
		*/
		boolean getProperty(in string name, out string value);
		boolean getBoolProperty(in string name, out boolean value) raises(BadArgException);
		boolean getFloatProperty(in string name, out double value) raises(BadArgException);
		boolean getIntProperty(in string name, out long value) raises(BadArgException);

		/* Todo: do we need this method? Or just want a way to dump properties for debug output ? */ 
		NameValuePairSeq getProperties();


		/*
			Setters: 
				if system = true, the property will be stored in the appropriate
				file in CIPRES_ROOT/share/system resources and will therefore affect all users.
				A InsufficientPrivelege error will be thrown if the properties service is running
				w/o admin rights.

				if system = false, the property will be stored in the user's (i.e. the uid under
				which the property service is running) property file.  

				A BadArgException is thrown if the value can't be converted to the specified type or
				if the property is one that the properties service knows about and the value
				specified doesn't conform to the rules for that property.
		*/
		void setProperty( in boolean system, in string name, in string value)
			raises (InsufficientPrivilegeException);
		void setBoolProperty(in boolean system, in string name, in boolean value)
			raises (BadArgException, InsufficientPrivilegeException);
		void setFloatProperty(in boolean system, in string name, in double  value)
			raises (BadArgException, InsufficientPrivilegeException);
		void setIntProperty(in boolean system, in string name, in long value)
			raises (BadArgException, InsufficientPrivilegeException);
	};
};