=Collector=
Collector is an utility that writes to history the data that is read from a data source.
Collector is instantiated to write to a specific history. 
<pre>
	Collector collector = History.createCollector(history, FlushPolicy.NoFlush);
</pre>

Collector reads its configuration from collector items. 
As convenience, due to overlapping fields, the collector item configuration is often passed with same instance as with history item. There are two classes that are suitable for configuring both history and collector: HistoryAndCollectorItem and SubscriptionItem. User provided classes can also be used as long as they contain the minimum set of fields (See HistoryAndCollectorItem).

<pre>
	// Create collector item
	HistoryAndCollectorItem ci = new HistoryAndCollectorItem();
	ci.id = "history-item-0";
	ci.format = sampleFormat;
	ci.interval = 0.2;
	ci.deadband = 1;
	ci.enabled = true;
	ci.gain = 10.0;
	ci.variableId = "MyDatasourceVariable";
	
	// Initialize Collector (Item)
	collector.addItem( ci );
</pre>

The data is written in steps. If flush policy was FlushOnEveryStep then disc buffers are flushed
at endStep().
<pre>
	try {
		// Simulate 100 steps
		for ( int i = 0; i<100; i++ ) {
			
			// Our "simulation" results 
			double time = i * 0.1;
			double myDatasourceVariable = -20 + i*0.1;
			
			// Begin collector writing step
			collector.beginStep(Bindings.DOUBLE, time);
			
			// Enter values 
			collector.setValue("MyDatasourceVariable", Bindings.DOUBLE, myDatasourceVariable);
			
			// End collector step
			collector.endStep();
		}
		
	} finally {
		// Flush values
		collector.flush();
		collector.close();
	}
</pre>

When collector is closed, the initial parameters and state data are written to and persisted in the history.
A field called "collectorState" is created, if did not exist before-hand.

==Banded mode==
If there is interval or deadband in the collector, the collector records the data in banded mode (start and end time).
But in case the sample format doesn't support banded mode, then the collector writes the data in a way where it puts a sample at the start of a band, and another at the end of the band.

For example if datasource produces value every 0.1 second and interval value was 1.0 seconds; then there would be sample
at 0.0, 0.9 (to represent a band), and then a new sample at 1.0 to represent a start of a new band.

==How to collect with multiple subscription parameters==
The collector is often used for recording one variable to multiple history items with different collecting parameters; such as interval and deadband. As the user passes collector items to the collector, the user gives and "id" and "variableId" values. "id" determines history item where the data is written to, and "variableId" where associated from in the Collector#setValue() method.

<pre>
	
	/// Configure items for the history and collector
	// Create a sample format
	RecordType sampleFormat = new RecordType();
	sampleFormat.addComponent("time", Datatypes.DOUBLE );
	sampleFormat.addComponent("value", Datatypes.DOUBLE );
	sampleFormat.addComponent("quality", Datatypes.BYTE );
	
	// Create two item configurations for the history and the collector
	HistoryAndCollectorItem i1 = new HistoryAndCollectorItem();
	i1.id = "MyVariable-interval=0.5";
	i1.format = sampleFormat;
	i1.interval = 0.5;
	i1.variableId = "MyVariable";
	
	HistoryAndCollectorItem i2 = new HistoryAndCollectorItem();
	i2.id = "MyVariable-deadband=5";
	i2.format = sampleFormat;
	i2.deadband = 5.0;
	i2.variableId = "MyVariable";

	/// Create History Manager and add Items
	HistoryManager history = History.createMemoryHistory();
	history.create( i1 );
	history.create( i2 );

	/// Create Collector and initialize items
	Collector collector = History.createCollector(history, FlushPolicy.NoFlush);
	collector.addItem( i1 );
	collector.addItem( i2 );
	
	/// Collect some data
	try {
		// Simulate 100 steps
		for ( int i = 0; i<100; i++ ) {
			
			// Our "simulation" results 
			double time = i * 0.1;
			double myItemValue = -20 + i*0.1;
			
			// Begin collector writing step
			collector.beginStep(Bindings.DOUBLE, time);
			
			// Enter values for one variable. 
			collector.setValue("MyVariable", Bindings.DOUBLE, myItemValue);
			
			// End collector step - MyVariable is written to two HistoryItems
			collector.endStep();
		}
		
	} finally {
		// Flush last values
		collector.flush();
		// Write the collector state back to the history
		collector.close();
	}
</pre>