#include "api1/Cipres.idl"
module CipresIDL_api1
{
	/* Some tree suppliers may not be able to provide random access to the i-th 
		tree.  Instead they can only provide another tree (or group of trees).
		These limited tree suppliers can implement SequentialTreeSupplier.
	*/
	interface SequentialTreeSupplier : Scriptable, LifeCycle
	{
			/* 	OutOfRangeBehavior is passed as argument to getTree methods
					to indicate how the supplier should behave if the requested 
					tree index >= numTrees.
				Tree suppliers that do not "grow" should raise an exception
					if OutOfRangeBehavior.waitForTree is requested and the tree
					is out of range.
			*/
		enum OutOfRangeBehavior { 
			error, 			/* raise an Exception if index >= numTrees */
			waitForTree,		/* block until all of the requested trees can be returned */
			padWithNullTree /* return nil for all indices that are out of range */
			};

			/* Returns the number of trees in that can be obtained until the supply is exhausted.
				-1 indicates the size of the tree source is unknown.
				-2 indicates an infinite supply
			*/
		long getNumTrees();
			/*@mth comment:
					I don't know if we need a richer system (richer return type for getNumTrees
					or a new method) to convey concepts like: "a tree supplier that is never 
					exhausted, but loops over the same n trees forever."
					I doubt it.
				@end mth comment
			*/

			/* Returns the current tree index (tells you how many trees into the sequence you are)*/
		long getCurrentTreeIndex(); 

			/* Returns the next "n" trees and increases the current tree index by n */
		TreeSeq getNextTrees(in long n, in OutOfRangeBehavior oorb) raises(ApplicationException);

			/*  Returns the next tree and increments the current tree index.
				A convenience function that is the same as calling:
					getNextTrees(1, oorb)[0] 
			*/
		Tree getNextTree(in OutOfRangeBehavior oorb) raises(ApplicationException);
		
	};
	
	/* If a client can request trees in any order, the service is a "complete" TreeSupplier: */
	interface TreeSupplier : SequentialTreeSupplier
	{
			/* Returns a sequence trees ["fromIndex", "fromIndex" + 1, ...  "toIndex"] */
		TreeSeq getTrees(in long fromIndex, in long toIndex, in OutOfRangeBehavior oorb) raises(ApplicationException);

			 /* Returns the tree with index "treeIndex".
 				A convenience function that is the same as calling:
					getTrees(treeIndex, treeIndex, oorb)[0] 
			*/
		Tree getTree(in long treeIndex, in OutOfRangeBehavior oorb) raises(ApplicationException);


			/* Sets the current tree index to "treeIndex". 
				This is mainly useful for clients that prefer to use the supplier
				in a "stream like" context, by repeatedly calling getNextTree (this mode may be
				more efficient too).
				
				Maintaining support for this style of invocation may be unnecessary.  
				WPM mentioned that Mesquite suppliers were designed to impelment both
				getNextObject() and getObject(i) methods, but, in practice, only 
				the random-access style functions get used much.
			*/
		void jumpToTreeIndex(in long treeIndex, in OutOfRangeBehavior oorb) raises(ApplicationException);
	};
};

/* version 3 */