-=Binding=\r
-Binding is a mechanism for mapping a Java Class to a Datatype.\r
-For example, take a java.lang.Double. The instance is a container (<code>private final double value;</code>) for the data and its Binding (DoubleBinding) is a way to access the data (<code>.valueOf()</code>, <code>.getDouble()</code>). \r
- Java Object + Binding = Databoard Value\r
-\r
-Bindings have the exact same composition tree structure as its respective <code>Datatype</code> - structural types have structural Bindings, and primitive types a single binding. To acquire a binding, the developer can use a utility that creates one using Java reflection functions.\r
-<pre class="code">\r
- Binding binding = Binding.getBinding( Double.class );\r
-</pre>\r
-\r
-Sometimes classes cannot bound using automatic tool, for instance when using 3rd party classes which cannot be modified. The developer must then write binding self by sub-classing on of the 13 base binding classes (There is a base binding class for each Datatype). \r
-<pre class="code">\r
- Binding binding = new RecordBinding() { ... };\r
-</pre>\r
-\r
-'''[../javadoc/org/simantics/databoard/binding|org.simantics.databoard.binding]'''.\r
-{| style="background-color: #f9f9f9; border: 1px solid #aaaaaa; "\r
-|- style="background-color: #e9e9e9; " |\r
-| '''Class''' || '''Description'''\r
-|- \r
-| [../javadoc/org/simantics/databoard/binding/DataBinding.html|DataBinding]\r
-| Base class for all data Bindings\r
-|- \r
-| [../javadoc/org/simantics/databoard/binding/RecordBinding.html|RecordBinding]\r
-| Record \r
-|- \r
-| [../javadoc/org/simantics/databoard/binding/ArrayBinding.html|ArrayBinding]\r
-| Array - an ordered sequence of elements of one value.\r
-|- \r
-| [../javadoc/org/simantics/databoard/binding/MapBinding.html|MapBinding]\r
-| Map - an ''ordered'' map of keys to values. \r
-|- \r
-| [../javadoc/org/simantics/databoard/binding/UnionBinding.html|UnionBinding]\r
-| Union\r
-|- \r
-| [../javadoc/org/simantics/databoard/binding/BooleanBinding.html|BooleanBinding],[../javadoc/org/simantics/databoard/binding/IntBinding.html|IntBinding],[../javadoc/org/simantics/databoard/binding/LongBinding.html|LongBinding],[../javadoc/org/simantics/databoard/binding/FloatBinding.html|FloatBinding],[../javadoc/org/simantics/databoard/binding/DoubleBinding.html|DoubleBinding]\r
-| Primitive and numeric Bindings\r
-|- \r
-| [../javadoc/org/simantics/databoard/binding/StringBinding.html|StringBinding]\r
-| String \r
-|- \r
-| [../javadoc/org/simantics/databoard/binding/OptionalBinding.html|OptionalBinding]\r
-| Optional value\r
-|- \r
-| [../javadoc/org/simantics/databoard/binding/VariantBinding.html|VariantBinding]\r
-| Variant value\r
-|}\r
-\r
-\r
-Binding can be acquired or created using one of the following methods:\r
-* Constructor \r
-* Constant\r
-* Reflection-Read from a Class \r
-* Created using [../javadoc/org/simantics/databoard/bindingscheme/BindingScheme.html|BindingScheme]\r
-<pre class="code">\r
- Binding binding = new DoubleBinding( doubleType );\r
- Binding binding = new RecordBinding() { ... };\r
- Binding binding = Bindings.DOUBLE;\r
- Binding binding = Binding.getBinding( Double.class );\r
- Binding binding = Binding.getBinding( Datatypes.DOUBLE );\r
-</pre>\r
-\r
-==Reflection==\r
-'''Data Type and Binding can be read automatically from a Class by utility.'''\r
-<pre class="code">\r
- Datatype type = Datatypes.getDatatype( Foo.class );\r
- Binding binding = Bindings.getBinding( Foo.class );\r
-</pre>\r
-\r
-Bindings for generics classes can be created by passing arguments.\r
-<pre class="code">\r
- Binding e = Bindings.getBinding(List.class, String.class);\r
- List<String> list = (List<String>) e.createRandom(5);\r
-\r
- Binding binding = Bindings.getBinding( Map.class, Integer.class, Integer.class );\r
- Map<Integer, Integer> value = (Map<Integer, Integer>) binding.createDefault();\r
-</pre>\r
-\r
-Even cascading generics...\r
-<pre class="code">\r
- Binding e = Bindings.getBinding(List.class, List.class, String.class);\r
- List<List<String>> listList = (List<List<String>>) e.createRandom(5);\r
-</pre>\r
-\r
-'''Classes are RecordTypes'''\r
-<pre class="code">\r
- class Foo {\r
- public int x, y, z;\r
- }\r
-</pre>\r
-Is a binding to the following Datatype\r
-<pre class="code">\r
- type Foo = { x : Integer, y : Integer, z : Integer }\r
-</pre>\r
-\r
-'''There are three types of classes supported, and therefore three ways how objects are constructed.'''\r
-If you create binding for your class with Bindings#getBinding( clazz ), the class must adhere one of these format. You may have to add annotations such as @Recursive, @Optional, @Arguments. \r
-\r
-''Record-like classes:''\r
-<pre class="code">\r
- class Foo {\r
- public String name;\r
- public Object value;\r
- }\r
-</pre>\r
-\r
-''Immutable classes:''\r
-<pre class="code">\r
- class Foo {\r
- private String name;\r
- private Object value;\r
- \r
- public Foo(String name, Object value) {\r
- this.name = name;\r
- this.value = value;\r
- }\r
- \r
- public String getName() {\r
- return name;\r
- }\r
- \r
- public Object getValue() {\r
- return value;\r
- }\r
- \r
- }\r
-</pre>\r
-\r
-''Bean-like classes:''\r
-<pre class="code">\r
- class Foo {\r
- private String name;\r
- private Object value;\r
- \r
- public void setName(String name) {\r
- this.name = name;\r
- }\r
- \r
- public void setValue(Object value) {\r
- this.value = value;\r
- }\r
- \r
- public String getName() {\r
- return name;\r
- }\r
- \r
- public Object getValue() {\r
- return value;\r
- }\r
- \r
- }\r
-</pre<\r
-\r
-'''Static and transient fields are omited:'''\r
-<pre class="code">\r
- static final long serialVersionUID = -3387516993124229943L;\r
- transient int hashCode;\r
-</pre>\r
-\r
-'''Enumerations are Union Types'''\r
-<pre class="code">\r
- enum Cars { Ferrari, Porche, Lamborghini, Jaguar }\r
-</pre> \r
-is interpreted as union type\r
- type Cars = | Ferrari | Porche | Lamborghini | Jaguar\r
-\r
-If you cannot modify the class, you have to create binding for it by subclassing base binding classes, eg. RecordBinding.\r
-\r
-'''Other exceptions:'''\r
-*<code>java.lang.Object</code> is <tt>Variant</tt>.\r
-*<code>java.lang.Set<T></code> is <tt>Map(T, {})</tt>.\r
-*<code>java.lang.TreeSet<T></code> is <tt>Map(T, {})</tt>.\r
-*<code>java.lang.HashSet<T></code> is <tt>Map(T, {})</tt>. (Note HashSet binding has very low performance.)\r
-*<code>java.lang.Map<K, V></code> is <tt>Map(K, V)</tt>.\r
-*<code>java.lang.TreeMap<K, V></code> is <tt>Map(K, V)</tt>.\r
-*<code>java.lang.HashMap<K, V></code> is <tt>Map(K, V)</tt>. (Note HashMap binding has very low performance.)\r
-*<code>java.lang.List<T></code> is <tt>Array(T)</tt>.\r
-*<code>java.lang.ArrayList<T></code> is <tt>Array(T)</tt>.\r
-*<code>java.lang.LinkedList<T></code> is <tt>Array(T)</tt>.\r
-*<code>void</code> is <tt>{}</tt>.\r
-*The stacktrace of <code>Exception.class</code> is omited.\r
-\r
-===Annotations===\r
-Java Classes / Fields can be annotated with the following annotations ('''[../javadoc/org/simantics/databoard/annotations/|org.simantics.databoard.annotations]]''').\r
-\r
-\r
-'''UnionTypes are abstract classes or interfaces with <code>@Union</code> annotation.'''\r
-<pre class="code">\r
- @Union({A.class, B.class}) interface Union1 { \r
- }\r
- \r
- class A implements Union1 {\r
- public int value;\r
- }\r
- \r
- class B implements Union1 {\r
- public String name;\r
- }\r
-</pre>\r
-\r
-'''<code>@Referable</code> denotes that the class has recursion and is a referable record.'''\r
-<pre class="code">\r
- public @Referable class Node {\r
- public Node[] children;\r
- }\r
-</pre>\r
-\r
-'''Fields that can have <tt>null</tt> value have <code>@Optional</code> annotation.'''\r
-<pre class="code">\r
- @Optional String name;\r
-</pre>\r
-\r
-'''String valid values are set with <code>@Pattern</code> as regular expression. ([http://en.wikipedia.org/wiki/Regular_expression])'''\r
-<pre class="code">\r
- String @Pattern("(19|20)\\d\\d[- /.](0[1-9]|1[012])[- /.](0[1-9]|[12][0-9]|3[01])") date;\r
- \r
- type Date = String( Pattern = "(19|20)\d\d[- /.](0[1-9]|1[012])[- /.](0[1-9]|[12][0-9]|3[01])" )\r
-</pre>\r
-\r
-'''String content type is set with a <code>@MIMEType</code>. ([http://en.wikipedia.org/wiki/Mime_type MIME Type])'''\r
-<pre class="code">\r
- @MIMEType("text/xml") String document;\r
-</pre>\r
-\r
-'''Array size restricted with @Length.'''\r
-<pre class="code">\r
- @Length("[0..10]") int[] array;\r
- @Length({"[320]", "[240]"}) int[][] image;\r
-</pre>\r
-\r
-'''Valid numeric range is set with @Range.'''\r
-<pre class="code">\r
- @Range("[0..100]") double alpha;\r
- @Range("[0..]" double length;\r
-</pre>\r
-\r
-'''<tt>Range</tt> and <tt>Length</tt> notation:'''\r
-*Exact Value "0"\r
-*Exclude all "()"\r
-*Unlimited "[..]"\r
-*Inclusive range "[0..100]"\r
-*Exclusive range "(0..100)"\r
-*Inclusive lower bound and exclusive upper bound "[0..100)"\r
-\r
-\r
-'''Engineering unit type is given with @Unit.'''\r
-<pre class="code">\r
- @Unit("km/h") double maxVelocity;\r
-</pre>\r
-\r
-'''The serializer generated with reflection can be overriden with @SpecializedSerializer'''\r
-<pre class="code">\r
- @SpecializedSerializer(MySerializer.class) \r
- public class MyRecord {\r
- ...\r
- }\r
-</pre>\r
-\r
-== Mapping Scheme ==\r
-A ''binding scheme'' associates some data types with a unique binding. The mapping of types to bindings is bijective, there is one binding for each type and vice-versa.\r
-\r
-<code>DefaultBindingScheme</code> is a scheme that converts any datatype to a binding. It prefers java.lang.X primitives.\r
-The Class mapping for each type is listed below.\r
-{| style="background-color: #f9f9f9; border: 1px solid #aaaaaa; "\r
-|- style="background-color: #e9e9e9;\r
-| '''Type''' || '''Class'''\r
-|- \r
-| <code>BooleanType</code> || <code>Boolean.class</code>\r
-|- \r
-| <code>ByteType</code> || <code>Byte.class</code>\r
-|- \r
-| <code>FloatType</code> || <code>Float.class</code>\r
-|- \r
-| <code>DoubleType</code> || <code>eDouble.class</code>\r
-|- \r
-| <code>IntegerType</code> || <code>Integer.class</code>\r
-|- \r
-| <code>LongType</code> || <code>Long.class</code>\r
-|- \r
-| <code>StringType</code> || <code>String.class</code>\r
-|- \r
-| <code>UnionType</code> || <code>TaggedObject.class</code>\r
-|- \r
-| <code>OptionType</code> || <code>ValueContainer.class</code>\r
-|- \r
-| <code>RecordType</code> || <code>Object[].class</code>\r
-|- \r
-| <code>ArrayType</code> || <code>ArrayList.class</code>\r
-|- \r
-| <code>Array(Byte)</code> || <code>byte[].class</code>\r
-|- \r
-| <code>MapType</code> || <code>TreeMap.class</code>\r
-|- \r
-| <code>VariantType</code> || <code>Variant.class</code>\r
-|}\r
-\r
-<code>MutableBindingScheme</code> is a scheme that provides a fully implementing mutable binding for all data types. \r
-The Class mapping for each type is listed below.\r
-\r
-{| style="background-color: #f9f9f9; border: 1px solid #aaaaaa; "\r
-|- style="background-color: #e9e9e9; " |\r
-| '''Type''' || '''Class'''\r
-|- \r
-| <code>BooleanType</code> || <code>MutableBoolean.class</code>\r
-|- \r
-| <code>ByteType</code> || <code>MutableByte.class</code>\r
-|- \r
-| <code>FloatType</code> || <code>MutableFloat.class</code>\r
-|- \r
-| <code>DoubleType</code> || <code>MutableDouble.class</code>\r
-|- \r
-| <code>IntegerType</code> || <code>MutableInt.class</code>\r
-|- \r
-| <code>LongType</code> || <code>MutableLong.class</code>\r
-|- \r
-| <code>StringType</code> || <code>MutableString.class</code>\r
-|- \r
-| <code>UnionType</code> || <code>TaggedObject.class</code>\r
-|- \r
-| <code>OptionType</code> || <code>ValueContainer.class</code>\r
-|- \r
-| <code>RecordType</code> || <code>Object[].class</code>\r
-|- \r
-| <code>ArrayType</code> || <code>ArrayList.class</code>\r
-|- \r
-| <code>MapType</code> || <code>TreeMap.class</code>\r
-|- \r
-| <code>VariantType</code> || <code>Variant.class</code>\r
-|}\r
-\r
-\r
-===Serialization===\r
-[../javadoc/org/simantics/databoard/serialization/binary/Serializer.html|Serializer] is a class that serializes Values into and from binary serialization format. It follows the Databoard [Databoard_Specification#Binary_File_Format|Binary File Format].\r
-<pre class="code">\r
- Binding binding = Bindings.DOUBLE;\r
- Serializer serializer = Bindings.getSerializer( binding );\r
- byte[] data = serializer.serialize( new Double( 100.0 ) );\r
- \r
- Double value = (Double) serializer.deserialize( data );\r
-</pre>\r
-\r
-Files can be partially accessed using BinaryAccessor, see [accessor|Accessors]. This is useful when handling larger than memory files.\r
-\r
-===Validation===\r
-'''Value''' can be ''well-formed'' or ''valid''. \r
-The domain of valid values are defined with restrictions in data types, and <code>@Length</code>, <code>@Range</code>, <code>@Pattern</code> and <code>@MIMEType</code> Annotations in Classes\r
-\r
-Validation mechanism in Binding asserts that the instance is a valid value of the respective Data Type.\r
-<pre class="code">\r
- try {\r
- Binding.assertInstaceIsValid( object );\r
- } catch( BindingException e ) {\r
- // In-valid object\r
- }\r
-</pre>\r
-\r
-===Other Notes===\r
-*<tt>Binding</tt> is a <tt>Comparator</tt>, all data values are comparable, the order is defined in [[Databoard_Specification#Comparison|Specification]].\r
-*<tt>Binding#createDefault()</tt> creates a valid instance of the Datatype.\r
-*<tt>Binding#createRandom(int)</tt> creates a valid instance with random values. Useful for unit tests.\r
-*<tt>Binding#clone(Object)</tt> creates a new instance with same content.\r
-*<tt>Binding#readFrom(Object, Binding, Binding)</tt> copies contents from another object of same type.\r
-\r
-===Parsing & Printing===\r
-\r
-Data values are printed and parsed of the [[Databoard_Specification|Text notation]] with the following <code>Binding</code> methods:\r
-<pre class="code">\r
- String text = binding.printValue( value, true );\r
- \r
- Object value = binding.parseValue( text );\r
-</pre>\r
-And also to value definitions <tt>''name : type = value''</tt>\r
-\r
-<pre class="code">\r
- StringBuilder sb = new StringBuilder();\r
- DataValueRepository repo = new DataValueRepository();\r
- repo.put( "temp", binding, value );\r
- binding.printValue( value, sb, repo, true );\r
- String text = sb.toString();\r
- \r
- Object value = binding.parseValueDefinition( text );\r
+=Binding=
+Binding is a mechanism for mapping a Java Class to a Datatype.
+For example, take a java.lang.Double. The instance is a container (<code>private final double value;</code>) for the data and its Binding (DoubleBinding) is a way to access the data (<code>.valueOf()</code>, <code>.getDouble()</code>).
+ Java Object + Binding = Databoard Value
+
+Bindings have the exact same composition tree structure as its respective <code>Datatype</code> - structural types have structural Bindings, and primitive types a single binding. To acquire a binding, the developer can use a utility that creates one using Java reflection functions.
+<pre class="code">
+ Binding binding = Binding.getBinding( Double.class );
+</pre>
+
+Sometimes classes cannot bound using automatic tool, for instance when using 3rd party classes which cannot be modified. The developer must then write binding self by sub-classing on of the 13 base binding classes (There is a base binding class for each Datatype).
+<pre class="code">
+ Binding binding = new RecordBinding() { ... };
+</pre>
+
+'''[../javadoc/org/simantics/databoard/binding|org.simantics.databoard.binding]'''.
+{| style="background-color: #f9f9f9; border: 1px solid #aaaaaa; "
+|- style="background-color: #e9e9e9; " |
+| '''Class''' || '''Description'''
+|-
+| [../javadoc/org/simantics/databoard/binding/DataBinding.html|DataBinding]
+| Base class for all data Bindings
+|-
+| [../javadoc/org/simantics/databoard/binding/RecordBinding.html|RecordBinding]
+| Record
+|-
+| [../javadoc/org/simantics/databoard/binding/ArrayBinding.html|ArrayBinding]
+| Array - an ordered sequence of elements of one value.
+|-
+| [../javadoc/org/simantics/databoard/binding/MapBinding.html|MapBinding]
+| Map - an ''ordered'' map of keys to values.
+|-
+| [../javadoc/org/simantics/databoard/binding/UnionBinding.html|UnionBinding]
+| Union
+|-
+| [../javadoc/org/simantics/databoard/binding/BooleanBinding.html|BooleanBinding],[../javadoc/org/simantics/databoard/binding/IntBinding.html|IntBinding],[../javadoc/org/simantics/databoard/binding/LongBinding.html|LongBinding],[../javadoc/org/simantics/databoard/binding/FloatBinding.html|FloatBinding],[../javadoc/org/simantics/databoard/binding/DoubleBinding.html|DoubleBinding]
+| Primitive and numeric Bindings
+|-
+| [../javadoc/org/simantics/databoard/binding/StringBinding.html|StringBinding]
+| String
+|-
+| [../javadoc/org/simantics/databoard/binding/OptionalBinding.html|OptionalBinding]
+| Optional value
+|-
+| [../javadoc/org/simantics/databoard/binding/VariantBinding.html|VariantBinding]
+| Variant value
+|}
+
+
+Binding can be acquired or created using one of the following methods:
+* Constructor
+* Constant
+* Reflection-Read from a Class
+* Created using [../javadoc/org/simantics/databoard/bindingscheme/BindingScheme.html|BindingScheme]
+<pre class="code">
+ Binding binding = new DoubleBinding( doubleType );
+ Binding binding = new RecordBinding() { ... };
+ Binding binding = Bindings.DOUBLE;
+ Binding binding = Binding.getBinding( Double.class );
+ Binding binding = Binding.getBinding( Datatypes.DOUBLE );
+</pre>
+
+==Reflection==
+'''Data Type and Binding can be read automatically from a Class by utility.'''
+<pre class="code">
+ Datatype type = Datatypes.getDatatype( Foo.class );
+ Binding binding = Bindings.getBinding( Foo.class );
+</pre>
+
+Bindings for generics classes can be created by passing arguments.
+<pre class="code">
+ Binding e = Bindings.getBinding(List.class, String.class);
+ List<String> list = (List<String>) e.createRandom(5);
+
+ Binding binding = Bindings.getBinding( Map.class, Integer.class, Integer.class );
+ Map<Integer, Integer> value = (Map<Integer, Integer>) binding.createDefault();
+</pre>
+
+Even cascading generics...
+<pre class="code">
+ Binding e = Bindings.getBinding(List.class, List.class, String.class);
+ List<List<String>> listList = (List<List<String>>) e.createRandom(5);
+</pre>
+
+'''Classes are RecordTypes'''
+<pre class="code">
+ class Foo {
+ public int x, y, z;
+ }
+</pre>
+Is a binding to the following Datatype
+<pre class="code">
+ type Foo = { x : Integer, y : Integer, z : Integer }
+</pre>
+
+'''There are three types of classes supported, and therefore three ways how objects are constructed.'''
+If you create binding for your class with Bindings#getBinding( clazz ), the class must adhere one of these format. You may have to add annotations such as @Recursive, @Optional, @Arguments.
+
+''Record-like classes:''
+<pre class="code">
+ class Foo {
+ public String name;
+ public Object value;
+ }
+</pre>
+
+''Immutable classes:''
+<pre class="code">
+ class Foo {
+ private String name;
+ private Object value;
+
+ public Foo(String name, Object value) {
+ this.name = name;
+ this.value = value;
+ }
+
+ public String getName() {
+ return name;
+ }
+
+ public Object getValue() {
+ return value;
+ }
+
+ }
+</pre>
+
+''Bean-like classes:''
+<pre class="code">
+ class Foo {
+ private String name;
+ private Object value;
+
+ public void setName(String name) {
+ this.name = name;
+ }
+
+ public void setValue(Object value) {
+ this.value = value;
+ }
+
+ public String getName() {
+ return name;
+ }
+
+ public Object getValue() {
+ return value;
+ }
+
+ }
+</pre<
+
+'''Static and transient fields are omited:'''
+<pre class="code">
+ static final long serialVersionUID = -3387516993124229943L;
+ transient int hashCode;
+</pre>
+
+'''Enumerations are Union Types'''
+<pre class="code">
+ enum Cars { Ferrari, Porche, Lamborghini, Jaguar }
+</pre>
+is interpreted as union type
+ type Cars = | Ferrari | Porche | Lamborghini | Jaguar
+
+If you cannot modify the class, you have to create binding for it by subclassing base binding classes, eg. RecordBinding.
+
+'''Other exceptions:'''
+*<code>java.lang.Object</code> is <tt>Variant</tt>.
+*<code>java.lang.Set<T></code> is <tt>Map(T, {})</tt>.
+*<code>java.lang.TreeSet<T></code> is <tt>Map(T, {})</tt>.
+*<code>java.lang.HashSet<T></code> is <tt>Map(T, {})</tt>. (Note HashSet binding has very low performance.)
+*<code>java.lang.Map<K, V></code> is <tt>Map(K, V)</tt>.
+*<code>java.lang.TreeMap<K, V></code> is <tt>Map(K, V)</tt>.
+*<code>java.lang.HashMap<K, V></code> is <tt>Map(K, V)</tt>. (Note HashMap binding has very low performance.)
+*<code>java.lang.List<T></code> is <tt>Array(T)</tt>.
+*<code>java.lang.ArrayList<T></code> is <tt>Array(T)</tt>.
+*<code>java.lang.LinkedList<T></code> is <tt>Array(T)</tt>.
+*<code>void</code> is <tt>{}</tt>.
+*The stacktrace of <code>Exception.class</code> is omited.
+
+===Annotations===
+Java Classes / Fields can be annotated with the following annotations ('''[../javadoc/org/simantics/databoard/annotations/|org.simantics.databoard.annotations]]''').
+
+
+'''UnionTypes are abstract classes or interfaces with <code>@Union</code> annotation.'''
+<pre class="code">
+ @Union({A.class, B.class}) interface Union1 {
+ }
+
+ class A implements Union1 {
+ public int value;
+ }
+
+ class B implements Union1 {
+ public String name;
+ }
+</pre>
+
+'''<code>@Referable</code> denotes that the class has recursion and is a referable record.'''
+<pre class="code">
+ public @Referable class Node {
+ public Node[] children;
+ }
+</pre>
+
+'''Fields that can have <tt>null</tt> value have <code>@Optional</code> annotation.'''
+<pre class="code">
+ @Optional String name;
+</pre>
+
+'''String valid values are set with <code>@Pattern</code> as regular expression. ([http://en.wikipedia.org/wiki/Regular_expression])'''
+<pre class="code">
+ String @Pattern("(19|20)\\d\\d[- /.](0[1-9]|1[012])[- /.](0[1-9]|[12][0-9]|3[01])") date;
+
+ type Date = String( Pattern = "(19|20)\d\d[- /.](0[1-9]|1[012])[- /.](0[1-9]|[12][0-9]|3[01])" )
+</pre>
+
+'''String content type is set with a <code>@MIMEType</code>. ([http://en.wikipedia.org/wiki/Mime_type MIME Type])'''
+<pre class="code">
+ @MIMEType("text/xml") String document;
+</pre>
+
+'''Array size restricted with @Length.'''
+<pre class="code">
+ @Length("[0..10]") int[] array;
+ @Length({"[320]", "[240]"}) int[][] image;
+</pre>
+
+'''Valid numeric range is set with @Range.'''
+<pre class="code">
+ @Range("[0..100]") double alpha;
+ @Range("[0..]" double length;
+</pre>
+
+'''<tt>Range</tt> and <tt>Length</tt> notation:'''
+*Exact Value "0"
+*Exclude all "()"
+*Unlimited "[..]"
+*Inclusive range "[0..100]"
+*Exclusive range "(0..100)"
+*Inclusive lower bound and exclusive upper bound "[0..100)"
+
+
+'''Engineering unit type is given with @Unit.'''
+<pre class="code">
+ @Unit("km/h") double maxVelocity;
+</pre>
+
+'''The serializer generated with reflection can be overriden with @SpecializedSerializer'''
+<pre class="code">
+ @SpecializedSerializer(MySerializer.class)
+ public class MyRecord {
+ ...
+ }
+</pre>
+
+== Mapping Scheme ==
+A ''binding scheme'' associates some data types with a unique binding. The mapping of types to bindings is bijective, there is one binding for each type and vice-versa.
+
+<code>DefaultBindingScheme</code> is a scheme that converts any datatype to a binding. It prefers java.lang.X primitives.
+The Class mapping for each type is listed below.
+{| style="background-color: #f9f9f9; border: 1px solid #aaaaaa; "
+|- style="background-color: #e9e9e9;
+| '''Type''' || '''Class'''
+|-
+| <code>BooleanType</code> || <code>Boolean.class</code>
+|-
+| <code>ByteType</code> || <code>Byte.class</code>
+|-
+| <code>FloatType</code> || <code>Float.class</code>
+|-
+| <code>DoubleType</code> || <code>eDouble.class</code>
+|-
+| <code>IntegerType</code> || <code>Integer.class</code>
+|-
+| <code>LongType</code> || <code>Long.class</code>
+|-
+| <code>StringType</code> || <code>String.class</code>
+|-
+| <code>UnionType</code> || <code>TaggedObject.class</code>
+|-
+| <code>OptionType</code> || <code>ValueContainer.class</code>
+|-
+| <code>RecordType</code> || <code>Object[].class</code>
+|-
+| <code>ArrayType</code> || <code>ArrayList.class</code>
+|-
+| <code>Array(Byte)</code> || <code>byte[].class</code>
+|-
+| <code>MapType</code> || <code>TreeMap.class</code>
+|-
+| <code>VariantType</code> || <code>Variant.class</code>
+|}
+
+<code>MutableBindingScheme</code> is a scheme that provides a fully implementing mutable binding for all data types.
+The Class mapping for each type is listed below.
+
+{| style="background-color: #f9f9f9; border: 1px solid #aaaaaa; "
+|- style="background-color: #e9e9e9; " |
+| '''Type''' || '''Class'''
+|-
+| <code>BooleanType</code> || <code>MutableBoolean.class</code>
+|-
+| <code>ByteType</code> || <code>MutableByte.class</code>
+|-
+| <code>FloatType</code> || <code>MutableFloat.class</code>
+|-
+| <code>DoubleType</code> || <code>MutableDouble.class</code>
+|-
+| <code>IntegerType</code> || <code>MutableInt.class</code>
+|-
+| <code>LongType</code> || <code>MutableLong.class</code>
+|-
+| <code>StringType</code> || <code>MutableString.class</code>
+|-
+| <code>UnionType</code> || <code>TaggedObject.class</code>
+|-
+| <code>OptionType</code> || <code>ValueContainer.class</code>
+|-
+| <code>RecordType</code> || <code>Object[].class</code>
+|-
+| <code>ArrayType</code> || <code>ArrayList.class</code>
+|-
+| <code>MapType</code> || <code>TreeMap.class</code>
+|-
+| <code>VariantType</code> || <code>Variant.class</code>
+|}
+
+
+===Serialization===
+[../javadoc/org/simantics/databoard/serialization/binary/Serializer.html|Serializer] is a class that serializes Values into and from binary serialization format. It follows the Databoard [Databoard_Specification#Binary_File_Format|Binary File Format].
+<pre class="code">
+ Binding binding = Bindings.DOUBLE;
+ Serializer serializer = Bindings.getSerializer( binding );
+ byte[] data = serializer.serialize( new Double( 100.0 ) );
+
+ Double value = (Double) serializer.deserialize( data );
+</pre>
+
+Files can be partially accessed using BinaryAccessor, see [accessor|Accessors]. This is useful when handling larger than memory files.
+
+===Validation===
+'''Value''' can be ''well-formed'' or ''valid''.
+The domain of valid values are defined with restrictions in data types, and <code>@Length</code>, <code>@Range</code>, <code>@Pattern</code> and <code>@MIMEType</code> Annotations in Classes
+
+Validation mechanism in Binding asserts that the instance is a valid value of the respective Data Type.
+<pre class="code">
+ try {
+ Binding.assertInstaceIsValid( object );
+ } catch( BindingException e ) {
+ // In-valid object
+ }
+</pre>
+
+===Other Notes===
+*<tt>Binding</tt> is a <tt>Comparator</tt>, all data values are comparable, the order is defined in [[Databoard_Specification#Comparison|Specification]].
+*<tt>Binding#createDefault()</tt> creates a valid instance of the Datatype.
+*<tt>Binding#createRandom(int)</tt> creates a valid instance with random values. Useful for unit tests.
+*<tt>Binding#clone(Object)</tt> creates a new instance with same content.
+*<tt>Binding#readFrom(Object, Binding, Binding)</tt> copies contents from another object of same type.
+
+===Parsing & Printing===
+
+Data values are printed and parsed of the [[Databoard_Specification|Text notation]] with the following <code>Binding</code> methods:
+<pre class="code">
+ String text = binding.printValue( value, true );
+
+ Object value = binding.parseValue( text );
+</pre>
+And also to value definitions <tt>''name : type = value''</tt>
+
+<pre class="code">
+ StringBuilder sb = new StringBuilder();
+ DataValueRepository repo = new DataValueRepository();
+ repo.put( "temp", binding, value );
+ binding.printValue( value, sb, repo, true );
+ String text = sb.toString();
+
+ Object value = binding.parseValueDefinition( text );
</pre>
\ No newline at end of file
Code Review / simantics / platform.git / blobdiff