--- /dev/null
+=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
+</pre>
\ No newline at end of file
Code Review / simantics / platform.git / blobdiff