2 Binding is a mechanism for mapping a Java Class to a Datatype.
\r
3 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
4 Java Object + Binding = Databoard Value
\r
6 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
8 Binding binding = Binding.getBinding( Double.class );
\r
11 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
13 Binding binding = new RecordBinding() { ... };
\r
16 '''[../javadoc/org/simantics/databoard/binding|org.simantics.databoard.binding]'''.
\r
17 {| style="background-color: #f9f9f9; border: 1px solid #aaaaaa; "
\r
18 |- style="background-color: #e9e9e9; " |
\r
19 | '''Class''' || '''Description'''
\r
21 | [../javadoc/org/simantics/databoard/binding/DataBinding.html|DataBinding]
\r
22 | Base class for all data Bindings
\r
24 | [../javadoc/org/simantics/databoard/binding/RecordBinding.html|RecordBinding]
\r
27 | [../javadoc/org/simantics/databoard/binding/ArrayBinding.html|ArrayBinding]
\r
28 | Array - an ordered sequence of elements of one value.
\r
30 | [../javadoc/org/simantics/databoard/binding/MapBinding.html|MapBinding]
\r
31 | Map - an ''ordered'' map of keys to values.
\r
33 | [../javadoc/org/simantics/databoard/binding/UnionBinding.html|UnionBinding]
\r
36 | [../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
37 | Primitive and numeric Bindings
\r
39 | [../javadoc/org/simantics/databoard/binding/StringBinding.html|StringBinding]
\r
42 | [../javadoc/org/simantics/databoard/binding/OptionalBinding.html|OptionalBinding]
\r
45 | [../javadoc/org/simantics/databoard/binding/VariantBinding.html|VariantBinding]
\r
50 Binding can be acquired or created using one of the following methods:
\r
53 * Reflection-Read from a Class
\r
54 * Created using [../javadoc/org/simantics/databoard/bindingscheme/BindingScheme.html|BindingScheme]
\r
56 Binding binding = new DoubleBinding( doubleType );
\r
57 Binding binding = new RecordBinding() { ... };
\r
58 Binding binding = Bindings.DOUBLE;
\r
59 Binding binding = Binding.getBinding( Double.class );
\r
60 Binding binding = Binding.getBinding( Datatypes.DOUBLE );
\r
64 '''Data Type and Binding can be read automatically from a Class by utility.'''
\r
66 Datatype type = Datatypes.getDatatype( Foo.class );
\r
67 Binding binding = Bindings.getBinding( Foo.class );
\r
70 Bindings for generics classes can be created by passing arguments.
\r
72 Binding e = Bindings.getBinding(List.class, String.class);
\r
73 List<String> list = (List<String>) e.createRandom(5);
\r
75 Binding binding = Bindings.getBinding( Map.class, Integer.class, Integer.class );
\r
76 Map<Integer, Integer> value = (Map<Integer, Integer>) binding.createDefault();
\r
79 Even cascading generics...
\r
81 Binding e = Bindings.getBinding(List.class, List.class, String.class);
\r
82 List<List<String>> listList = (List<List<String>>) e.createRandom(5);
\r
85 '''Classes are RecordTypes'''
\r
91 Is a binding to the following Datatype
\r
93 type Foo = { x : Integer, y : Integer, z : Integer }
\r
96 '''There are three types of classes supported, and therefore three ways how objects are constructed.'''
\r
97 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
99 ''Record-like classes:''
\r
102 public String name;
\r
103 public Object value;
\r
107 ''Immutable classes:''
\r
110 private String name;
\r
111 private Object value;
\r
113 public Foo(String name, Object value) {
\r
115 this.value = value;
\r
118 public String getName() {
\r
122 public Object getValue() {
\r
129 ''Bean-like classes:''
\r
132 private String name;
\r
133 private Object value;
\r
135 public void setName(String name) {
\r
139 public void setValue(Object value) {
\r
140 this.value = value;
\r
143 public String getName() {
\r
147 public Object getValue() {
\r
154 '''Static and transient fields are omited:'''
\r
156 static final long serialVersionUID = -3387516993124229943L;
\r
157 transient int hashCode;
\r
160 '''Enumerations are Union Types'''
\r
162 enum Cars { Ferrari, Porche, Lamborghini, Jaguar }
\r
164 is interpreted as union type
\r
165 type Cars = | Ferrari | Porche | Lamborghini | Jaguar
\r
167 If you cannot modify the class, you have to create binding for it by subclassing base binding classes, eg. RecordBinding.
\r
169 '''Other exceptions:'''
\r
170 *<code>java.lang.Object</code> is <tt>Variant</tt>.
\r
171 *<code>java.lang.Set<T></code> is <tt>Map(T, {})</tt>.
\r
172 *<code>java.lang.TreeSet<T></code> is <tt>Map(T, {})</tt>.
\r
173 *<code>java.lang.HashSet<T></code> is <tt>Map(T, {})</tt>. (Note HashSet binding has very low performance.)
\r
174 *<code>java.lang.Map<K, V></code> is <tt>Map(K, V)</tt>.
\r
175 *<code>java.lang.TreeMap<K, V></code> is <tt>Map(K, V)</tt>.
\r
176 *<code>java.lang.HashMap<K, V></code> is <tt>Map(K, V)</tt>. (Note HashMap binding has very low performance.)
\r
177 *<code>java.lang.List<T></code> is <tt>Array(T)</tt>.
\r
178 *<code>java.lang.ArrayList<T></code> is <tt>Array(T)</tt>.
\r
179 *<code>java.lang.LinkedList<T></code> is <tt>Array(T)</tt>.
\r
180 *<code>void</code> is <tt>{}</tt>.
\r
181 *The stacktrace of <code>Exception.class</code> is omited.
\r
184 Java Classes / Fields can be annotated with the following annotations ('''[../javadoc/org/simantics/databoard/annotations/|org.simantics.databoard.annotations]]''').
\r
187 '''UnionTypes are abstract classes or interfaces with <code>@Union</code> annotation.'''
\r
189 @Union({A.class, B.class}) interface Union1 {
\r
192 class A implements Union1 {
\r
196 class B implements Union1 {
\r
197 public String name;
\r
201 '''<code>@Referable</code> denotes that the class has recursion and is a referable record.'''
\r
203 public @Referable class Node {
\r
204 public Node[] children;
\r
208 '''Fields that can have <tt>null</tt> value have <code>@Optional</code> annotation.'''
\r
210 @Optional String name;
\r
213 '''String valid values are set with <code>@Pattern</code> as regular expression. ([http://en.wikipedia.org/wiki/Regular_expression])'''
\r
215 String @Pattern("(19|20)\\d\\d[- /.](0[1-9]|1[012])[- /.](0[1-9]|[12][0-9]|3[01])") date;
\r
217 type Date = String( Pattern = "(19|20)\d\d[- /.](0[1-9]|1[012])[- /.](0[1-9]|[12][0-9]|3[01])" )
\r
220 '''String content type is set with a <code>@MIMEType</code>. ([http://en.wikipedia.org/wiki/Mime_type MIME Type])'''
\r
222 @MIMEType("text/xml") String document;
\r
225 '''Array size restricted with @Length.'''
\r
227 @Length("[0..10]") int[] array;
\r
228 @Length({"[320]", "[240]"}) int[][] image;
\r
231 '''Valid numeric range is set with @Range.'''
\r
233 @Range("[0..100]") double alpha;
\r
234 @Range("[0..]" double length;
\r
237 '''<tt>Range</tt> and <tt>Length</tt> notation:'''
\r
241 *Inclusive range "[0..100]"
\r
242 *Exclusive range "(0..100)"
\r
243 *Inclusive lower bound and exclusive upper bound "[0..100)"
\r
246 '''Engineering unit type is given with @Unit.'''
\r
248 @Unit("km/h") double maxVelocity;
\r
251 '''The serializer generated with reflection can be overriden with @SpecializedSerializer'''
\r
253 @SpecializedSerializer(MySerializer.class)
\r
254 public class MyRecord {
\r
259 == Mapping Scheme ==
\r
260 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
262 <code>DefaultBindingScheme</code> is a scheme that converts any datatype to a binding. It prefers java.lang.X primitives.
\r
263 The Class mapping for each type is listed below.
\r
264 {| style="background-color: #f9f9f9; border: 1px solid #aaaaaa; "
\r
265 |- style="background-color: #e9e9e9;
\r
266 | '''Type''' || '''Class'''
\r
268 | <code>BooleanType</code> || <code>Boolean.class</code>
\r
270 | <code>ByteType</code> || <code>Byte.class</code>
\r
272 | <code>FloatType</code> || <code>Float.class</code>
\r
274 | <code>DoubleType</code> || <code>eDouble.class</code>
\r
276 | <code>IntegerType</code> || <code>Integer.class</code>
\r
278 | <code>LongType</code> || <code>Long.class</code>
\r
280 | <code>StringType</code> || <code>String.class</code>
\r
282 | <code>UnionType</code> || <code>TaggedObject.class</code>
\r
284 | <code>OptionType</code> || <code>ValueContainer.class</code>
\r
286 | <code>RecordType</code> || <code>Object[].class</code>
\r
288 | <code>ArrayType</code> || <code>ArrayList.class</code>
\r
290 | <code>Array(Byte)</code> || <code>byte[].class</code>
\r
292 | <code>MapType</code> || <code>TreeMap.class</code>
\r
294 | <code>VariantType</code> || <code>Variant.class</code>
\r
297 <code>MutableBindingScheme</code> is a scheme that provides a fully implementing mutable binding for all data types.
\r
298 The Class mapping for each type is listed below.
\r
300 {| style="background-color: #f9f9f9; border: 1px solid #aaaaaa; "
\r
301 |- style="background-color: #e9e9e9; " |
\r
302 | '''Type''' || '''Class'''
\r
304 | <code>BooleanType</code> || <code>MutableBoolean.class</code>
\r
306 | <code>ByteType</code> || <code>MutableByte.class</code>
\r
308 | <code>FloatType</code> || <code>MutableFloat.class</code>
\r
310 | <code>DoubleType</code> || <code>MutableDouble.class</code>
\r
312 | <code>IntegerType</code> || <code>MutableInt.class</code>
\r
314 | <code>LongType</code> || <code>MutableLong.class</code>
\r
316 | <code>StringType</code> || <code>MutableString.class</code>
\r
318 | <code>UnionType</code> || <code>TaggedObject.class</code>
\r
320 | <code>OptionType</code> || <code>ValueContainer.class</code>
\r
322 | <code>RecordType</code> || <code>Object[].class</code>
\r
324 | <code>ArrayType</code> || <code>ArrayList.class</code>
\r
326 | <code>MapType</code> || <code>TreeMap.class</code>
\r
328 | <code>VariantType</code> || <code>Variant.class</code>
\r
332 ===Serialization===
\r
333 [../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
335 Binding binding = Bindings.DOUBLE;
\r
336 Serializer serializer = Bindings.getSerializer( binding );
\r
337 byte[] data = serializer.serialize( new Double( 100.0 ) );
\r
339 Double value = (Double) serializer.deserialize( data );
\r
342 Files can be partially accessed using BinaryAccessor, see [accessor|Accessors]. This is useful when handling larger than memory files.
\r
345 '''Value''' can be ''well-formed'' or ''valid''.
\r
346 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
348 Validation mechanism in Binding asserts that the instance is a valid value of the respective Data Type.
\r
351 Binding.assertInstaceIsValid( object );
\r
352 } catch( BindingException e ) {
\r
358 *<tt>Binding</tt> is a <tt>Comparator</tt>, all data values are comparable, the order is defined in [[Databoard_Specification#Comparison|Specification]].
\r
359 *<tt>Binding#createDefault()</tt> creates a valid instance of the Datatype.
\r
360 *<tt>Binding#createRandom(int)</tt> creates a valid instance with random values. Useful for unit tests.
\r
361 *<tt>Binding#clone(Object)</tt> creates a new instance with same content.
\r
362 *<tt>Binding#readFrom(Object, Binding, Binding)</tt> copies contents from another object of same type.
\r
364 ===Parsing & Printing===
\r
366 Data values are printed and parsed of the [[Databoard_Specification|Text notation]] with the following <code>Binding</code> methods:
\r
368 String text = binding.printValue( value, true );
\r
370 Object value = binding.parseValue( text );
\r
372 And also to value definitions <tt>''name : type = value''</tt>
\r
375 StringBuilder sb = new StringBuilder();
\r
376 DataValueRepository repo = new DataValueRepository();
\r
377 repo.put( "temp", binding, value );
\r
378 binding.printValue( value, sb, repo, true );
\r
379 String text = sb.toString();
\r
381 Object value = binding.parseValueDefinition( text );
\r