uses data.String

/* {"description" : "A description of a required interface."} */
data ReqIntf {
	/* {"@description" : "The required interface (including package)."} */
	char intf[]
	/* {"@description" : "Whether or not this required interface should resolve to a native library."} */
	bool isNative
}

/* {"description" : "A description of an implementation component selected for an interface."} */
data InterfaceActual {
	/* {"@description" : "The interface (including package)."} */
	char intf[]
	/* {"@description" : "The path to the selected implementation component."} */
	char comp[]
	/* {"@description" : "If comp is a proxy, what tag was it given (which would be passed to a delegated loader)."} */
	char proxyTag[]
	/* {"@description" : "If comp is a proxy, what params was it given (which would be passed to a delegated loader)."} */
	char proxyParams[]
	/* {"@description" : "The list of required interfaces of this implementation component."} */
	ReqIntf req[]
}

/* {"description" : "One unique composition of components, represented as an implementing component for each interface."} */
data Composition {
	InterfaceActual options[]
}

/* {"description" : "This data type describes the set of compositional changes implied by updating a component."} */
data CompositionUpdate {
	/* {"@description" : "Status flag indicating whether or not the component update procedure succeeded."} */
	bool ok
	/* {"@description" : "The set of composition options which should be removed as a consequence of the component update."} */
	Composition remOptions[]
	/* {"@description" : "The set of composition options which should be added as a consequence of the component update."} */
	Composition addOptions[]
}

/* {"description" : "Utility API to perform whole-composition search for viable entire compositions of components, from a given starting-point component."} */
interface OptionBuilder {
	
	/* { "@description" : "Instantiate a new OptionBuilder, triggering a search for complete compositional options from the given starting component.",	
			"path" : "The component from which to start the search (often an implementation of the App interface, but not necessarily so).",
			"searchPaths" : "A list of specific search paths to include in the search process.",
			"interfaceExcludeList" : "Interfaces to exclude from the search process (no component implementations will be found for these interfaces).",
			"componentExcludeList" : "Components to exclude from the search process (no compositions will feature these components)."
		}
	*/
	OptionBuilder(char path[], opt store String searchPaths[], store String interfaceExcludeList[], store String componentExcludeList[])
	
	/* { "@description" : "Retrieve the list of compositions that has been found." } */
	Composition[] getCompositions()
	
	/* { "@description" : "Add a new component permutation to the composition search, returning the additional compositions which this new option implies." } */
	Composition[] addComponent(char path[])
	/* { "@description" : "Update the given component to a new version across the given compositions. This returns a CompositionUpdate, which indicates both compositions that should be removed and those which should be added as a result of the update." } */
	CompositionUpdate updComponent(Composition compositions[], char path[])
	/* { "@description" : "Remove a selected component from the composition set, returning the set of compositions which should correspondingly be removed." } */
	Composition[] remComponent(Composition compositions[], char path[])
	
	/* { "@description" : "Add a proxy component for the given interface, causing that proxy to act as a novel implementation of that interface, returning the additional compositions which this new option implies. The set of parameters given to this function represents a unique implementation; each additional call which provides the same proxy path and interface, with a different tag or parameters value, is treated as a further novel implementation." } */
	Composition[] addProxy(char forInterface[], char proxyComponent[], char tag[], char parameters[])
	/* { "@description" : "Remove a proxy component for the given interface, returning the set of compositions which should correspondingly be removed." } */
	Composition[] remProxy(Composition compositions[], char forInterface[], char proxyComponent[], char tag[], char parameters[])
	}