package edu.vt.marian.search;

import java.util.*;
import java.io.*;

import edu.vt.marian.common.*;


/** 
   A WtdObjSetEnumeration is a very light object, many of which can be generated
		for each WtdObjSet and all of which can execute concurrently in 
		different threads.  Provides the java.util.Enumeration functionality 
		and then some.
    <P>
	<B>Synchronization Note:</B> As with all Enumerations in MARIAN, the nextElement()
		method in classes implementing this interface should be synchronized,
		as should skip(), sample() and sampleToWt().  This prevents concurrency
		problems if callers in two different threads are both stepping
		through the Enumeration.  Now, two callers shouldn't really
		be sharing a single Enumeration, but it does happen, and a lack of
		synchronization in that circumstance could be terrible.  On the other
		hand, it does no good to synchronize hasMoreElements(), since in the
		moment between calling hasMoreElements() and nextElement() anything
		can happen.  So for full threadability, one should always use:
		<BR>&nbsp;&nbsp;	try
		<BR>&nbsp;&nbsp;	{ while(TRUE) ... nextElement() ... }
		<BR>&nbsp;&nbsp;	catch( NoSuchElementException e ) {}
		<BR>	rather than:
		<BR>&nbsp;&nbsp;	while( hasMoreElements() )
		<BR>&nbsp;&nbsp;	{ ... nextElement() ... }
    @author	Robert France
    @author	Priyamvadha Lakshminarayanan
    @author	Prajakta Joshi
    <p> JDK Version  : 1.1.5
	@see	java.util.Enumeration
	@see	WtdObjSet
 */

public interface WtdObjSetEnumeration extends Enumeration
{
	/**
		Skip forward a certain number of elements.
		@param	k	How many elements to skip.
		@exception	NoSuchElementException
	*/      
	public void skip(int k);


	/**
		Copy a certain number of elements into a bag.
		@param	num	How many elements to copy.
		@param	sampleBag	The WtdObjBag to add elements to.
		@return	OK -- There were Num elements left, and they all were copied well.
		<BR>	anything else -- Problems.
		@exception	NoSuchElementException
	*/      
  	public int sample(int num, WtdObjBag sampleBag);


	/**
		Copy into a bag all the members of this set with weights >= some weight.
		@param	minWt	The lowest weight to copy.
		@param	sampleBag	The WtdObjBag to add elements to.
		@return	OK -- There were Num elements left, and they all were copied well.
		<BR>	anything else -- Problems.
		@exception	NoSuchElementException
	*/      
  	public int sampleToWt(Weight minWt, WtdObjBag sampleBag);


	/**
		Return exact number of elements remaining in the parent set.
		@return	The exact number of elements still to be enumerated.
	*/      
	public int exactNumRemaining();


	/**
		Return approximate number of elements left.
		@return	The approximate number of elements still to be enumerated.
	*/      
	public int approxNumRemaining();

	/**
		Return maximum number of elements left.
		@return	The maximum number of elements still to be enumerated.
	*/      
	public int maxNumRemaining();
}