--- /dev/null
+=Sample Format=\r
+The sample format is a record that contains fields that describe what and how data is stored from source. Its fields are defined by the user, their datatype, and possibly unit type too.\r
+At minimum requirement there must be two fields: "time" and "value". \r
+The data type can be anything numerical; but typically is a double or an integer type.\r
+\r
+If there is the optional field "quality", then it is used for expressing discontinuation regions (value -1). Discontinuation can be passed to the collector with a NaN or null value.\r
+ \r
+An example of a simple '''Sample Format'''\r
+{| border="1" cellpadding="3" cellspacing="0" align="center"\r
+|- style="background-color: #f9f9f9;"\r
+|'''Field Name''' ||'''Required'''|| '''Description'''\r
+|- \r
+|time || yes || Time, the time of the 1st sample included into the band. \r
+|- \r
+|value || yes || First value in the band.\r
+|- \r
+|quality || no || 0 = Good, -1 = No value (Byte)\r
+|}\r
+\r
+If collector is given interval or deadband settings, some input samples may need to be dropped. \r
+If the sample format is in ''banded'' mode, then some information about dropped steps are \r
+preserved as count, avg, min, max and median values. \r
+In a banded sample there are (start)time and endTime fields - henge the name value band.\r
+\r
+An example of a '''Banded Sample Format''': \r
+{| border="1" cellpadding="3" cellspacing="0" align="center"\r
+|- style="background-color: #f9f9f9;"\r
+|'''Field Name''' ||'''Required'''|| '''Description'''\r
+|- \r
+|time || yes || Region start time, the time of the 1st sample included into the band. \r
+|- \r
+|endTime || no || Region end time, the time of the last sample included into the band. \r
+|- \r
+| ||\r
+|- \r
+|value || yes || First value in the band.\r
+|- \r
+|lastValue || no || Last value in the band. \r
+|- \r
+|avg || no || Average value from all the steps that were included. \r
+|- \r
+|median || no || Median value from all the steps that were included into the band.\r
+|- \r
+|min || no || Lowest value in the band.\r
+|- \r
+|max || no || Highest value in the band.\r
+|- \r
+| ||\r
+|- \r
+|quality || no || 0 = Good, -1 = No value (Byte)\r
+|- \r
+|count || no || The number of included samples in the band (Integer)\r
+|}\r
+\r
+To create a sample format, instantiate RecordType and add fields.\r
+<pre>\r
+ // Create a sample format ( simple though )\r
+ RecordType sampleFormat = new RecordType();\r
+ sampleFormat.addComponent("time", Datatypes.DOUBLE );\r
+ sampleFormat.addComponent("value", Datatypes.DOUBLE );\r
+ sampleFormat.addComponent("quality", Datatypes.BYTE );\r
+</pre>\r
+\r
+Optionally, get sample format from a user defined class.\r
+<pre>\r
+ class Sample {\r
+ public double time;\r
+ public double value; \r
+ }\r
+ \r
+ // Get sample binding from a class\r
+ Binding sampleBinding = Bindings.getBinding( Sample.class );\r
+ // Get sample type from the binding\r
+ Datatype sampleFormat = sampleBinding.type();\r
+</pre>\r
+\r