=History Manager=
HistoryManager is an interface for managing time-series streams (called ''items'') of sample data. There are two implementations FileHistory and MemoryHistory. The data is based on files and in-memory arrays.
<pre>
	// Create History Manager
	HistoryManager history = History.createMemoryHistory();
</pre>

Items can be created, modified, opened, deleted. 
An item is a description, that carries related meta-data aswell. The file history persists the configuration data on disc.

To create a history item you must provide an item description for each stream.
The description is a class inherited from Bean-class. 
Two fields are mandatory id:String, and format:Datatype. 
Other fields are meta-data that are stored along with the history. 

Therefore it is suggested to use one of the following classes:
{| border="1" cellpadding="3" cellspacing="0" align="center" style="background-color: #f9f9f9;"
|'''Class''' || '''Description'''
|- style="background-color: #fff;"
|HistoryItem || Simplest format of HistoryManager Item { id:String, format:Datatype }
|- style="background-color: #fff;"
|HistoryAndCollectorItem || Item format for both HistoryManager and Collector.
|- style="background-color: #fff;"
|SubscriptionItem || Item format for HistoryManager, Collector, and meta-data for Simantics subscription configurations. 
|}

To create create an item in the history, specify a format, id, and an item format.
<pre>
	// Create a sample format ( simple though )
	RecordType sampleFormat = new RecordType();
	sampleFormat.addComponent("time", Datatypes.DOUBLE );
	sampleFormat.addComponent("value", Datatypes.DOUBLE );
	sampleFormat.addComponent("quality", Datatypes.BYTE );
	
	// Create History Item configuration
	String id = UUID.randomUUID().toString();
	HistoryItem hi = new HistoryItem(id, sampleFormat);
	
	// Create the item in the history
	history.create( hi );
</pre>

The data can be written by using a collector, or by adding samples directly to a array (stream) accessor.
<pre>
	// Open item for writing
	StreamAccessor sa = history.openStream(id, "rw");
	// Read sample type
	RecordType sampleFormat = (RecordType) sa.type().componentType;
	// Create bean based binding for the sample
	RecordBinding sampleBinding = (RecordBinding) Bindings.getBeanBinding( sampleFormat );
	// Create sample object
	Bean sample = (Bean) sampleBinding.createPartial();
		
	try {
		
		// Set quality
		sample.setField(2, Bindings.BYTE, (byte)0);
		
		// Write 10 samples
		for (int i=0; i<10; i++) {
			
			// Set time
			sample.setField(0, Bindings.DOUBLE, 1.0*i );
			// Set Value
			sample.setField(1, Bindings.DOUBLE, 100.0*i );
			
			sa.add(sampleBinding, sample);				
		}
		
	} finally {
		sa.flush();
		sa.close();
	}
</pre>

The data is read in a similiar fashion; by opening an accessor and reading samples.
<pre> 
	// Open stream from history
	StreamAccessor sa = history.openStream(id, "r");
	// Read sample type
	RecordType sampleFormat = (RecordType) sa.type().componentType;
	// Create bean binding
	RecordBinding sampleBinding = (RecordBinding) Bindings.getBeanBinding( sampleFormat );
	// Create sample object
	Bean sample = (Bean) sampleBinding.createPartial();
	
	try {
		for (int i=0; i<sa.size(); i++) {
			sa.get(i, sampleBinding, sample);
			System.out.println(i+": "+sample);
		}
	} finally {
		sa.close();
	}
</pre>


=File History=
FileHistory is a file and directory based history manager. 
<pre>
	// Create History Manager in a workarea (directory)
	HistoryManager history = History.openFileHistory( workarea );
</pre>


A history item is uses 2 - 3 files. All the files are located in a directory called workarea.
The file is named by escaping the id using URI encoding, and appending three file name extensions.

{| border="1" cellpadding="3" cellspacing="0" align="center"
|- style="background-color: #f9f9f9;" 
|'''File''' || '''Description''' 
|- 
|<id>.txt || The item's meta-data written as serialization of the variant. The file format is no longer ascii text, but binary data.
|-
|<id>.data || A series of samples serialized with no header.
|-
|<id>.index || Index file that contains <tt>long</tt> offsets for each sample. Index file is used for variable sized samples only, such as strings and variable-lengthed arrays.
|}

=Item Manager=
Item descriptions are aquired with HistoryManager#getItems(). Each item is an record containing the fields
the item was initialized with, and/or possible added later. For instance, if data was written to the item
with a Collector, the collecting parameters and collectin state data is written to a field called "collectorState".
<pre>
	Bean[] items = history.getItems();
</pre>
The record is expressed with an instance of a sub-class of a bean. Known fields can be copied to user
specified class.
<pre>
	HistoryItem i0 = new HistoryItem();
	i0.readAvailableFields( items[0] );
</pre>	
ItemManager is an utility that aids in creating, modifying and reading item arrays.
<pre>
	ItemManager im = new ItemManager( items );
</pre>
Item id's can be extracted conveniently.
<pre>
	System.out.println("Items Identifiers:");
	for ( String itemId : im.toIdArray() )
	{
		System.out.println( itemId );
	}
</pre>
The items can be selected using one or multiple fields as patterns. 
<pre>	
	// To search an item by id, use
	List<Bean> result = im.search("id", id);
	
	// To search items of specific parameter, say file format, use
	im.search("format", sampleFormat);
	
	// Or interval
	im.search("interval", 0.1);
</pre>