// File: ddr-simpleapi.idl


/* This document is a re-expression in IDL of the Java definition for a Simple API
to access Device Description Repositories. The Device Description Repository Simple
 API document is publicly available at:

http://www.w3.org/2005/MWI/DDWG/drafts/api/080331.html

All the elements in the IDL definition are related to elements in the Java normative
definition of the DDR Simple API. Significant parts of the IDL are preceded by a 
comment offering the link to the corresponding Java definition.

The author of the re-expression of the Java API in IDL is:

- Rodrigo Garcia (Fundación CTIC)

Copyright  © 2008 W3C®  (MIT, ERCIM, Keio), All Rights Reserved.
W3C liability, trademark and document use rules apply */


#ifndef _DDRSIMPLEAPI_IDL_
#define _DDRSIMPLEAPI_IDL_

#pragma prefix "ddr.w3c.org"

module simple
{
	//Forward declarations
	interface PropertyRef;
	interface PropertyValue;

	//Array typedefs
	typedef sequence<PropertyRef> PropertyRefArray;
	typedef sequence<PropertyValue> PropertyValueArray;
	typedef sequence<string> StringArray;
	
	
	// See the definition for all the exceptions in the Java normative specification
	// of the DDR API at: 
	// http://www.w3.org/2005/MWI/DDWG/drafts/api/080331.html#sec-exceptions

	/** Note that DDRException is missing, as exception inheritance is not allowed in IDL       
	  * Also, implementations should be ready to catch run-time exceptions (system exceptions). 
	  * Clients must be prepared to handle these exceptions even though they are not declared   
	  * in a raises clause. These exceptions cannot appear in IDL in a raises clause.
	  * Details about SystemExceptions in the Java normative specification at:
	    http://www.w3.org/2005/MWI/DDWG/drafts/api/080331.html#sec-SystemException */

	exception NameException {

		long code;
		
		string message;
	};

	exception ValueException {

		long code;		

		string message;
	};

	exception InitializationException {

		long code;

		string message;
	};

	/** Exception codes */

	/* System Exception codes appearing in the Java normative specification
	 * do not appear here as they are implementation- (and language-) specific.
	 * Read the two possible codes in the Java specification to take them into 
	 * account at: 
	 * http://www.w3.org/2005/MWI/DDWG/drafts/api/080331.html#sec-SystemException-codes */

	/* DDRException code appearing in the Java normative specification
	 * does not appear here as it cannot be raised because of the lack of exception inheritance.
	 * Read more on this including its only exception code in the Java specification to take this into 
	 * account at: 
	 * http://www.w3.org/2005/MWI/DDWG/drafts/api/080331#sec-DDRException */
	 
	/** Codes used for Name Exceptions. Same values as in the Java specification suggested. */

	const long PROPERTY_NOT_RECOGNIZED = 100;

	const long VOCABULARY_NOT_RECOGNIZED = 200;

	const long ASPECT_NOT_RECOGNIZED = 800;
		
	/** Codes used in Value Exceptions */

	const long INCOMPATIBLE_TYPES = 600;

	const long NOT_KNOWN = 900;

	const long MULTIPLE_VALUES = 10000;

	/** Codes used in Initialization Exceptions */
	
	const long INITIALIZATION_ERROR = 300;

	// Constant used for properties whose underlying source does
	// not have a (known) aspect.

	const string NULL_ASPECT = "__NULL";
	
	/** Representation of a Map structure */
	struct Pair {
		string key;
		string value;
	};

	typedef sequence<Pair> Map;
	

	// See the definition for interface Evidence in the Java normative specification
	// of the DDR API at: 
	// http://www.w3.org/2005/MWI/DDWG/drafts/api/080331.html#java-Evidence

	interface Evidence {

		void put(in string key, in string value);	

		boolean exists(in string key);
	
		string get(in string key);
	};	
	

	// See the definition for interface PropertyName in the Java normative specification
	// of the DDR API at: 
	// http://www.w3.org/2005/MWI/DDWG/drafts/api/080331.html#java-PropertyName

	interface PropertyName {

		string getLocalPropertyName();

		string getNamespace();
	};
	

	// See the definition for interface PropertyRef in the Java normative specification
	// of the DDR API at: 
	// http://www.w3.org/2005/MWI/DDWG/drafts/api/080331.html#java-PropertyRef

	interface PropertyRef {

		string getLocalPropertyName();

		string getAspectName();

		string getNamespace();	
	};
	

	// See the definition for interface PropertyValue in the Java normative specification
	// of the DDR API at: 
	// http://www.w3.org/2005/MWI/DDWG/drafts/api/080331.html#java-PropertyValue

	interface PropertyValue {

		double getDouble()
			raises (ValueException);

		long long getLong()
			raises (ValueException);

		string getString()
			raises (ValueException);

		boolean getBoolean()
			raises (ValueException);
		
	 	long getInteger()
			raises (ValueException);
		
		StringArray getEnumeration()
			raises (ValueException);
		
		float getFloat()
			raises (ValueException);

		boolean exists();

		PropertyRef getPropertyRef();

	};
	

	// See the definition for interface PropertyValues in the Java normative specification
	// of the DDR API at: 
	// http://www.w3.org/2005/MWI/DDWG/drafts/api/080331.html#java-PropertyValues

	interface PropertyValues {

		PropertyValueArray getAll();

		PropertyValue getValue(in PropertyRef prop)
			raises (NameException);
	};
	
	// See the definition for interface Service in the Java normative specification
	// of the DDR API at: 
	// http://www.w3.org/2005/MWI/DDWG/drafts/api/080331.html#java-Service

	interface Service {

		void initialize(in string defaultVocabularyIRI, in Map props)
			raises (NameException, InitiazalitionException);
	
		string getAPIVersion();
		
		string getDataVersion();
		
		PropertyRefArray listPropertyRefs();
			
		PropertyValue getPropertyValue(in Evidence evidence, in PropertyRef propertyRef) 
			raises(NameException);	
			
		PropertyValue getPropertyValue(in Evidence evidence, in PropertyName propertyName)
			raises(NameException);	
			
		PropertyValue getPropertyValue(in Evidence evidence, in string localPropertyName) 
			raises (NameException);
			
		PropertyValue getPropertyValue(in Evidence evidence, in string localPropertyName, in string localAspectName, in string vocabularyIRI) 
			raises (NameException);	 	
	 	
		PropertyValues getPropertyValues(in Evidence evidence)
			raises (NameException);	
		
		PropertyValues getPropertyValues(in Evidence evidence, in string localAspectName) 
			raises (NameException);
		
		PropertyValues getPropertyValues(in Evidence evidence, in string localAspectName, in string vocabularyIRI) 
			raises (NameException);
			
		PropertyValues getPropertyValues(in Evidence evidence, in PropertyRefArray propertyRefs) 
			raises (NameException);
			
		PropertyName newPropertyName(in string localPropertyName)
			raises (NameException);
			
		PropertyName newPropertyName(in string localPropertyName, in string vocabularyIRI)
			raises (NameException);
			
		PropertyRef newPropertyRef(in string localPropertyName)
			raises (NameException);

	 	PropertyRef newPropertyRef(in PropertyName propertyName)
			raises (NameException);
	
		PropertyRef newPropertyRef(in PropertyName propertyName, in string localAspectName)
			raises (NameException);
			
		Evidence newHTTPEvidence();	
			
		Evidence newHTTPEvidence(in Map map);
	};
};

#endif _DDRSIMPLEAPI_IDL_