]> gerrit.simantics Code Review - simantics/platform.git/blob - bundles/org.simantics.databoard/src-isv/old/old_manual.mediawiki
(refs #7595) Started SCL/Reflection module
[simantics/platform.git] / bundles / org.simantics.databoard / src-isv / old / old_manual.mediawiki
1 center>'''Databoard 0.6.1 Developer Manual'''</center>
2
3 =Datatype=
4 In Databoard all values have a type representation, [[svn:foundation/databoard/trunk/org.simantics.databoard/src/org/simantics/databoard/type/Datatype.java|Datatype.java]]. 
5 It is the base abstract class for all concrete type classes (See table below). 
6 There is a facade class utility ([[svn:foundation/databoard/trunk/org.simantics.databoard/src/org/simantics/databoard/Datatypes.java|Datatypes]]) that provides functions to most of the Datatype library's features.
7
8 '''[[svn:foundation/databoard/trunk/org.simantics.databoard/src/org/simantics/databoard/type|org.simantics.databoard.type]]'''.
9 {| style="background-color: #e9e9e9; border: 1px solid #aaaaaa; "
10 | '''Class'''
11 | '''Description'''
12 |- style="background-color: #f9f9f9; " |
13 | [[svn:foundation/databoard/trunk/org.simantics.databoard/src/org/simantics/databoard/type/Datatype.java|Datatype]]
14 | Base class for all data types
15 |- style="background-color: #f9f9f9; " |
16 | [[svn:foundation/databoard/trunk/org.simantics.databoard/src/org/simantics/databoard/type/RecordType.java|RecordType]]
17 | Record 
18 |- style="background-color: #f9f9f9; " |
19 | [[svn:foundation/databoard/trunk/org.simantics.databoard/src/org/simantics/databoard/type/ArrayType.java|ArrayType]]
20 | Array - an ordered sequence of elements of one type.
21 |- style="background-color: #f9f9f9; " |
22 | [[svn:foundation/databoard/trunk/org.simantics.databoard/src/org/simantics/databoard/type/MapType.java|MapType]]
23 | Map - an ordered map of keys to values. 
24 |- style="background-color: #f9f9f9; " |
25 | [[svn:foundation/databoard/trunk/org.simantics.databoard/src/org/simantics/databoard/type/UnionType.java|UnionType]]
26 | Union
27 |- style="background-color: #f9f9f9; " |
28 | [[svn:foundation/databoard/trunk/org.simantics.databoard/src/org/simantics/databoard/type/BooleanType.java|BooleanType]],[[svn:foundation/databoard/trunk/org.simantics.databoard/src/org/simantics/databoard/type/IntType.java|IntType]],[[svn:foundation/databoard/trunk/org.simantics.databoard/src/org/simantics/databoard/type/LongType.java|LongType]],[[svn:foundation/databoard/trunk/org.simantics.databoard/src/org/simantics/databoard/type/FloatType.java|FloatType]],[[svn:foundation/databoard/trunk/org.simantics.databoard/src/org/simantics/databoard/type/DoubleType.java|DoubleType]]
29 | Primitive and numeric types
30 |- style="background-color: #f9f9f9; " |
31 | [[svn:foundation/databoard/trunk/org.simantics.databoard/src/org/simantics/databoard/type/StringType.java|StringType]]
32 | String 
33 |- style="background-color: #f9f9f9; " |
34 | [[svn:foundation/databoard/trunk/org.simantics.databoard/src/org/simantics/databoard/type/OptionalType.java|OptionalType]]
35 | Optional value
36 |- style="background-color: #f9f9f9; " |
37 | [[svn:foundation/databoard/trunk/org.simantics.databoard/src/org/simantics/databoard/type/VariantType.java|VariantType]]
38 | Variant value
39 |}
40
41
42 Datatype can be acquired or created using one of the following methods:
43 * Construct new
44 * Constant 
45 * [[#Reflection|Reflection]]-Read from a Class
46 * Read from string of [[Databoard_Specification|the text notation]].
47     Datatype type = new DoubleType();
48     Datatype type = Datatypes.DOUBLE;
49     Datatype type = Datatypes.getDatatype( Double.class );
50     
51     Datatypes.addDefinition("type Node = { id : String; children : Node[] }");
52     Datatype type = Datatypes.getDatatype("Node");
53
54
55 ==Parsing==
56 Datatypes are parsed using <code>Datatypes.DatatypeRepository</code>. 
57     Datatypes.addDefinition("type Node = { id : String; children : Node[] }");
58     Datatype type = Datatypes.getDatatype("Node");
59
60 Types are printed to types and definitions with 
61     String type = type.toString();
62     
63     DatatypeRepository repo = new DatatypeRepository();
64     repo.add("temp1", type);
65     String typeDef = repo.toString();
66
67 ==Structure Example==
68 A node is a recursive type. With databoard typesystem it could be stated as
69   type Node = {
70          id : String;
71          displayNames : LocalizedTexts;
72          children : Node[];
73          value : Optional(Variant);
74        }
75
76 [[Image:NodeType.png|Type presented as tree]]
77
78
79 A couple of instances with Databoard value notation:
80   root : Node = {
81            id = \93PI_01\94
82            displayNames = map{ \93en\94 = \93Instrument \93 }
83            children = 
84             [ 
85               {id=\94Child\94
86                displayNames = map{ \93en\94 = \93Child\94} },
87                value = 5 : Integer
88               }
89             ]
90            value = \93<root>\94 : String
91          }
92
93 [[Image:NodeInstance.png|Node values preseted as tree]]
94
95 =Binding=
96 There is a [[Databoard_Specification#Datatypes|type system]], and when developing with java, platform neutral data values can be read from and written to objects. This is the role of a binding, a map from a Java Class to a Datatype. 
97
98 For instance, take a java.lang.Double. Its instance is the container (<code>private final double value;</code>) of the data and its Binding (DoubleBinding) is the access (<code>.valueOf()</code>, <code>.getDouble()</code>) to the data. 
99     Java Object + Binding = Databoard Value
100
101 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. 
102     Binding binding = Binding.getBinding( Double.class );
103
104 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). 
105     Binding binding = new RecordBinding() { ... };
106
107
108 '''[[svn:foundation/databoard/trunk/org.simantics.databoard/src/org/simantics/databoard/binding|org.simantics.databoard.binding]]'''.
109 {| style="background-color: #e9e9e9; border: 1px solid #aaaaaa; "
110 | '''Class'''
111 | '''Description'''
112 |- style="background-color: #f9f9f9; " |
113 | [[svn:foundation/databoard/trunk/org.simantics.databoard/src/org/simantics/databoard/binding/DataBinding.java|DataBinding]]
114 | Base class for all data Bindings
115 |- style="background-color: #f9f9f9; " |
116 | [[svn:foundation/databoard/trunk/org.simantics.databoard/src/org/simantics/databoard/binding/RecordBinding.java|RecordBinding]]
117 | Record 
118 |- style="background-color: #f9f9f9; " |
119 | [[svn:foundation/databoard/trunk/org.simantics.databoard/src/org/simantics/databoard/binding/ArrayBinding.java|ArrayBinding]]
120 | Array - an ordered sequence of elements of one value.
121 |- style="background-color: #f9f9f9; " |
122 | [[svn:foundation/databoard/trunk/org.simantics.databoard/src/org/simantics/databoard/binding/MapBinding.java|MapBinding]]
123 | Map - an ''ordered'' map of keys to values. 
124 |- style="background-color: #f9f9f9; " |
125 | [[svn:foundation/databoard/trunk/org.simantics.databoard/src/org/simantics/databoard/binding/UnionBinding.java|UnionBinding]]
126 | Union
127 |- style="background-color: #f9f9f9; " |
128 | [[svn:foundation/databoard/trunk/org.simantics.databoard/src/org/simantics/databoard/binding/BooleanBinding.java|BooleanBinding]],[[svn:foundation/databoard/trunk/org.simantics.databoard/src/org/simantics/databoard/binding/IntBinding.java|IntBinding]],[[svn:foundation/databoard/trunk/org.simantics.databoard/src/org/simantics/databoard/binding/LongBinding.java|LongBinding]],[[svn:foundation/databoard/trunk/org.simantics.databoard/src/org/simantics/databoard/binding/FloatBinding.java|FloatBinding]],[[svn:foundation/databoard/trunk/org.simantics.databoard/src/org/simantics/databoard/binding/DoubleBinding.java|DoubleBinding]]
129 | Primitive and numeric Bindings
130 |- style="background-color: #f9f9f9; " |
131 | [[svn:foundation/databoard/trunk/org.simantics.databoard/src/org/simantics/databoard/binding/StringBinding.java|StringBinding]]
132 | String 
133 |- style="background-color: #f9f9f9; " |
134 | [[svn:foundation/databoard/trunk/org.simantics.databoard/src/org/simantics/databoard/binding/OptionalBinding.java|OptionalBinding]]
135 | Optional value
136 |- style="background-color: #f9f9f9; " |
137 | [[svn:foundation/databoard/trunk/org.simantics.databoard/src/org/simantics/databoard/binding/VariantBinding.java|VariantBinding]]
138 | Variant value
139 |}
140
141
142 Binding can be acquired or created using one of the following methods:
143 * Constructor 
144 * Constant
145 * Reflection-Read from a Class 
146 * Created using [[svn:foundation/databoard/trunk/org.simantics.databoard/src/org/simantics/databoard/bindingscheme/BindingScheme.java|BindingScheme]]
147     Binding binding = new DoubleBinding( doubleType );
148     Binding binding = new RecordBinding() { ... };
149     Binding binding = Bindings.DOUBLE;
150     Binding binding = Binding.getBinding( Double.class );
151     Binding binding = Binding.getBinding( Datatypes.DOUBLE );
152
153 ==Reflection==
154 '''Data Type and Binding can be read automatically from a Class by utility.'''
155     Datatype type = Datatypes.getDatatype( Foo.class );
156     Binding binding = Bindings.getBinding( Foo.class );
157
158 Bindings for generics classes can be created by passing arguments.
159     Binding e = Bindings.getBinding(List.class, String.class);
160     List<String> list = (List<String>) e.createRandom(5);
161
162     Binding binding = Bindings.getBinding( Map.class, Integer.class, Integer.class );
163     Map<Integer, Integer> value = (Map<Integer, Integer>) binding.createDefault();
164
165 Even cascading generics...
166     Binding e = Bindings.getBinding(List.class, List.class, String.class);
167     List<List<String>> listList = (List<List<String>>) e.createRandom(5);
168
169
170 '''Classes are RecordTypes'''
171     class Foo {
172         public int x, y, z;
173     }
174 Is a binding to the following Datatype
175     type Foo = { x : Integer, y : Integer, z : Integer }
176
177 '''There are three types of classes supported, and therefore three ways how objects are constructed.'''
178 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. 
179
180 ''Record-like classes:''
181     class Foo {
182         public String name;
183         public Object value;
184     }
185
186 ''Immutable classes:''
187     class Foo {
188         private String name;
189         private Object value;
190         
191         public Foo(String name, Object value) {
192             this.name = name;
193             this.value = value;
194         }
195         
196         public String getName() {
197             return name;
198         }
199         
200         public Object getValue() {
201             return value;
202         }
203         
204     }
205
206 ''Bean-like classes:''
207     class Foo {
208         private String name;
209         private Object value;
210         
211         public void setName(String name) {
212             this.name = name;
213         }
214         
215         public void setValue(Object value) {
216             this.value = value;
217         }
218         
219         public String getName() {
220             return name;
221         }
222         
223         public Object getValue() {
224             return value;
225         }
226         
227     }
228
229 '''Static and transient fields are omited:'''
230     static final long serialVersionUID = -3387516993124229943L;
231     transient int hashCode;
232
233 '''Enumerations are Union Types'''
234     enum Cars { Ferrari, Porche, Lamborghini, Jaguar }    
235 is interpreted as union type
236     type Cars = | Ferrari | Porche | Lamborghini | Jaguar
237
238 If you cannot modify the class, you have to create binding for it by subclassing base binding classes, eg. RecordBinding.
239
240 '''Other exceptions:'''
241 *<code>java.lang.Object</code> is <tt>Variant</tt>.
242 *<code>java.lang.Set<T></code> is <tt>Map(T, {})</tt>.
243 *<code>java.lang.TreeSet<T></code> is <tt>Map(T, {})</tt>.
244 *<code>java.lang.HashSet<T></code> is <tt>Map(T, {})</tt>. (Note HashSet binding has very low performance.)
245 *<code>java.lang.Map<K, V></code> is <tt>Map(K, V)</tt>.
246 *<code>java.lang.TreeMap<K, V></code> is <tt>Map(K, V)</tt>.
247 *<code>java.lang.HashMap<K, V></code> is <tt>Map(K, V)</tt>. (Note HashMap binding has very low performance.)
248 *<code>java.lang.List<T></code> is <tt>Array(T)</tt>.
249 *<code>java.lang.ArrayList<T></code> is <tt>Array(T)</tt>.
250 *<code>java.lang.LinkedList<T></code> is <tt>Array(T)</tt>.
251 *<code>void</code> is <tt>{}</tt>.
252 *The stacktrace of <code>Exception.class</code> is omited.
253
254 ===Annotations===
255 Java Classes / Fields can be annotated with the following annotations ('''[[svn:foundation/databoard/trunk/org.simantics.databoard/src/org/simantics/databoard/annotations/|org.simantics.databoard.annotations]]''').
256
257
258 '''UnionTypes are abstract classes or interfaces with <code>@Union</code> annotation.'''
259     @Union({A.class, B.class}) interface Union1 {               
260     }
261     
262     class A implements Union1 {
263         public int value;
264     }
265     
266     class B implements Union1 {
267         public String name;
268     }
269
270
271 '''<code>@Referable</code> denotes that the class has recursion and is a referable record.'''
272     public @Referable class Node {
273         public Node[] children;
274     }
275
276
277 '''Fields that can have <tt>null</tt> value have <code>@Optional</code> annotation.'''
278     @Optional String name;
279
280
281 '''String valid values are set with <code>@Pattern</code> as regular expression. ([http://en.wikipedia.org/wiki/Regular_expression])'''
282     String @Pattern("(19|20)\\d\\d[- /.](0[1-9]|1[012])[- /.](0[1-9]|[12][0-9]|3[01])") date;
283     
284     type Date = String( Pattern = "(19|20)\d\d[- /.](0[1-9]|1[012])[- /.](0[1-9]|[12][0-9]|3[01])" )
285
286
287 '''String content type is set with a <code>@MIMEType</code>. ([http://en.wikipedia.org/wiki/Mime_type MIME Type])'''
288     @MIMEType("text/xml") String document;
289
290
291 '''Array size restricted with @Length.'''
292     @Length("[0..10]") int[] array;
293     @Length({"[320]", "[240]"}) int[][] image;
294
295
296 '''Valid numeric range is set with @Range.'''
297     @Range("[0..100]") double alpha;
298     @Range("[0..]" double length;
299
300
301 '''<tt>Range</tt> and <tt>Length</tt> notation:'''
302 *Exact Value "0"
303 *Exclude all "()"
304 *Unlimited "[..]"
305 *Inclusive range "[0..100]"
306 *Exclusive range "(0..100)"
307 *Inclusive lower bound and exclusive upper bound "[0..100)"
308
309
310 '''Engineering unit type is given with @Unit.'''
311     @Unit("km/h") double maxVelocity;
312
313 '''The serializer generated with reflection can be overriden with @SpecializedSerializer'''
314     @SpecializedSerializer(MySerializer.class) 
315     public class MyRecord {
316         ...
317     }
318
319 == Mapping Scheme ==
320 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.
321
322 <code>DefaultBindingScheme</code> is a scheme that converts any datatype to a binding. It prefers java.lang.X primitives.
323 The Class mapping for each type is listed below.
324 {| style="background-color: #e9e9e9; border: 1px solid #aaaaaa; "
325 | '''Type'''
326 | '''Class'''
327 |- style="background-color: #f9f9f9; " |
328 | <code>BooleanType</code>
329 | <code>Boolean.class</code>
330 |- style="background-color: #f9f9f9; " |
331 | <code>ByteType</code>
332 | <code>Byte.class</code>
333 |- style="background-color: #f9f9f9; " |
334 | <code>FloatType</code>
335 | <code>Float.class</code>
336 |- style="background-color: #f9f9f9; " |
337 | <code>DoubleType</code>
338 | <code>eDouble.class</code>
339 |- style="background-color: #f9f9f9; " |
340 | <code>IntegerType</code>
341 | <code>Integer.class</code>
342 |- style="background-color: #f9f9f9; " |
343 | <code>LongType</code>
344 | <code>Long.class</code>
345 |- style="background-color: #f9f9f9; " |
346 | <code>StringType</code>
347 | <code>String.class</code>
348 |- style="background-color: #f9f9f9; " |
349 | <code>UnionType</code>
350 | <code>TaggedObject.class</code>
351 |- style="background-color: #f9f9f9; " |
352 | <code>OptionType</code>
353 | <code>ValueContainer.class</code>
354 |- style="background-color: #f9f9f9; " |
355 | <code>RecordType</code>
356 | <code>Object[].class</code>
357 |- style="background-color: #f9f9f9; " |
358 | <code>ArrayType</code>
359 | <code>ArrayList.class</code>
360 |- style="background-color: #f9f9f9; " |
361 | <code>Array(Byte)</code>
362 | <code>byte[].class</code>
363 |- style="background-color: #f9f9f9; " |
364 | <code>MapType</code>
365 | <code>TreeMap.class</code>
366 |- style="background-color: #f9f9f9; " |
367 | <code>VariantType</code>
368 | <code>Variant.class</code>
369 |}
370
371 <code>MutableBindingScheme</code> is a scheme that provides a fully implementing mutable binding for all data types. 
372 The Class mapping for each type is listed below.
373
374 {| style="background-color: #e9e9e9; border: 1px solid #aaaaaa; "
375 | '''Type'''
376 | '''Class'''
377 |- style="background-color: #f9f9f9; " |
378 | <code>BooleanType</code>
379 | <code>MutableBoolean.class</code>
380 |- style="background-color: #f9f9f9; " |
381 | <code>ByteType</code>
382 | <code>MutableByte.class</code>
383 |- style="background-color: #f9f9f9; " |
384 | <code>FloatType</code>
385 | <code>MutableFloat.class</code>
386 |- style="background-color: #f9f9f9; " |
387 | <code>DoubleType</code>
388 | <code>MutableDouble.class</code>
389 |- style="background-color: #f9f9f9; " |
390 | <code>IntegerType</code>
391 | <code>MutableInt.class</code>
392 |- style="background-color: #f9f9f9; " |
393 | <code>LongType</code>
394 | <code>MutableLong.class</code>
395 |- style="background-color: #f9f9f9; " |
396 | <code>StringType</code>
397 | <code>MutableString.class</code>
398 |- style="background-color: #f9f9f9; " |
399 | <code>UnionType</code>
400 | <code>TaggedObject.class</code>
401 |- style="background-color: #f9f9f9; " |
402 | <code>OptionType</code>
403 | <code>ValueContainer.class</code>
404 |- style="background-color: #f9f9f9; " |
405 | <code>RecordType</code>
406 | <code>Object[].class</code>
407 |- style="background-color: #f9f9f9; " |
408 | <code>ArrayType</code>
409 | <code>ArrayList.class</code>
410 |- style="background-color: #f9f9f9; " |
411 | <code>MapType</code>
412 | <code>TreeMap.class</code>
413 |- style="background-color: #f9f9f9; " |
414 | <code>VariantType</code>
415 | <code>Variant.class</code>
416 |}
417
418
419 ===Serialization===
420 [[svn:foundation/databoard/trunk/org.simantics.databoard/src/org/simantics/databoard/serialization/binary/Serializer.java|Serializer.java]] is a class that serializes Values into and from binary serialization format. It follows the Databoard [[Databoard_Specification#Binary_File_Format|Binary File Format]].
421
422     Binding binding = Bindings.DOUBLE;
423     Serializer serializer = Bindings.getSerializer( binding );
424     byte[] data = serializer.serialize( new Double( 100.0 ) );
425     
426     Double value = (Double) serializer.deserialize( data );
427
428 Files can be partially accessed using BinaryAccessor, see [[#Accessors|Accessors]]. This is useful when handling larger than memory files.
429
430 ===Validation===
431 '''Value''' can be ''well-formed'' or ''valid''. 
432 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
433
434 Validation mechanism in Binding asserts that the instance is a valid value of the respective Data Type.
435     try {
436         Binding.assertInstaceIsValid( object );
437     } catch( BindingException e ) {
438         // In-valid object
439     }
440
441 ===Other Notes===
442 *<tt>Binding</tt> is a <tt>Comparator</tt>, all data values are comparable, the order is defined in [[Databoard_Specification#Comparison|Specification]].
443 *<tt>Binding#createDefault()</tt> creates a valid instance of the Datatype.
444 *<tt>Binding#createRandom(int)</tt> creates a valid instance with random values. Useful for unit tests.
445 *<tt>Binding#clone(Object)</tt> creates a new instance with same content.
446 *<tt>Binding#readFrom(Object, Binding, Binding)</tt> copies contents from another object of same type.
447
448 ===Parsing & Printing===
449
450 Data values are printed and parsed of the [[Databoard_Specification|Text notation]] with the following <code>Binding</code> methods:
451
452     String text = binding.printValue( value, true );
453     
454     Object value = binding.parseValue( text );
455
456 And also to value definitions <tt>''name : type = value''</tt>
457     StringBuilder sb = new StringBuilder();
458     DataValueRepository repo = new DataValueRepository();
459     repo.put( "temp", binding, value );
460     binding.printValue( value, sb, repo, true );
461     String text = sb.toString();
462     
463     Object value = binding.parseValueDefinition( text );
464
465 =Adapter=
466 There can be different Java Class Bindings for a single data type. For example, <code>Double</code> type can be have bindings <code>DoubleJavaBinding</code> and <code>MutableDoubleBinding</code> to two respective classes <code>java.lang.Double</code> and <code>MutableDouble</code>. Instance of one binding can be adapted to instance of another with an <code>[[svn:foundation/databoard/trunk/org.simantics.databoard/src/org/simantics/databoard/adapter/Adapter.java|Adapter]]</code>.
467
468 Adapter can be created automatically or implemented self.
469     Adapter adapter = new Adapter() { ... };
470     Adapter adapter = Bindings.getAdapter( domainBinding, rangeBinding );
471
472 Example:
473     Adapter adapter = Bindings.getAdapter(Bindings.MUTABLE_DOUBLE, Bindings.DOUBLE);
474     java.lang.Double double = adapter.adapt( new MutableDouble(5.0) );
475
476 There is also convenience.
477     java.lang.Double double = Bindings.adapt( new MutableDouble(5.0), Bindings.MUTABLE_DOUBLE, Bindings.DOUBLE );
478
479 The argument given to <code>Adapter#adapt(Object)</code> may be re-used in the result unless the adapter is a cloning adapter which guarantees a clone. Note, even wih cloning adapters immutable classes, (eg java.lang.Integer) are never cloned.
480     Adapter cloner = Bindings.adapterCache.getAdapter(domain, range, false, true);
481     cloner.adapt( ... );
482
483     Rectangle2D rect2 = Bindings.clone( rect1, rectBinding, rectBinding );
484
485 ===Type Conversion===
486 In some cases different types may be are type-conversion compatible. An instance of one type is convertible to instance of another.
487
488 '''Engineering Units of same quantity are convertible.'''
489     class CarSI {
490         String modelName;               
491         @Unit("km/h") double maxVelocity;               
492         @Unit("kg") double mass;                
493         @Unit("cm") double length; 
494         @Unit("kW") double power;
495     }
496     
497     class CarIm {
498         String modelName;               
499         @Unit("mph") float maxVelocity;         
500         @Unit("lbs") float mass;                
501         @Unit("ft") float length; 
502         @Unit("hp(M)") float power;
503     }
504     
505     Adapter si2imAdapter = Bindings.getTypeAdapter(
506         Bindings.getBinding(CarSI.class), 
507         Bindings.getBinding(CarIm.class) );
508     
509     CarIm americanCarInfo = si2imAdapter.adapt( europeanCarInfo );
510
511
512 '''Primitive Types.''' Note, primitive adapter throws an exception at runtime if values are not adaptable.
513     Adapter adapter = getTypeAdapter( integerBinding, doubleBinding );
514     Double double = adapter.adapt( new Integer( 5 ) );
515
516
517 '''Records are matched by field names.'''
518     class Foo {
519         int x, y, z;
520     }
521     class Bar {
522         int z, y, x;
523     }
524     Adapter adapter = getTypeAdapter( fooBinding, barBinding );
525     
526
527 '''Subtype to supertype:''' Note, this conversion cannot be not symmetric, supertypes cannot be converted to subtypes.
528     class Node {
529         String id;
530     }
531     class ValueNode extends Node {
532         Object value;
533     }
534     Adapter adapter = getTypeAdapter( valueNodeBinding, nodeBinding );
535
536 '''Non-existing fields to Optional fields''' 
537     class Node {
538         String id;
539     }
540     class NominalNode {
541         String id;
542         @Optional String name;
543     }
544     Adapter adapter = getTypeAdapter( nodeBinding, nominalNodeBinding );
545     
546
547 '''Enumerations'''
548     enum Cars { Audio, BMW, Mercedes, Honda, Mazda, Toyota, Ford, Mitsubishi, Nissan, GM }
549     enum JapaneseCars { Honda, Mazda, Toyota, Nissan, Mitsubishi }
550     
551     Binding carsBinding = Bindings.getBinding( Cars.class );
552     Binding japaneseCarsBinding = Bindings.getBinding( JapaneseCars.class );
553     Adapter adapter = Bindings.adapterCache.getAdapter(japaneseCarsBinding, carsBinding, true, false);
554
555 =Accessors=
556 Say, you have several gigabytes of data in a file. The whole object doesn't need to be serialized at once. You can read and write the value partially using [[svn:foundation/databoard/trunk/org.simantics.databoard/src/org/simantics/databoard/accessor/|Accessor]] interface. The actual container can be a file, memory byte[]/ByteBuffer or a Java Object. The content is structured as tree using Databoard's type system. All but referable records are supported (=no recursion in accessors). 
557
558 '''[[svn:foundation/databoard/trunk/org.simantics.databoard/src/org/simantics/databoard/accessor|org.simantics.databoard.accessor]] interfaces'''.
559 {| style="background-color: #e9e9e9; border: 1px solid #aaaaaa; "
560 | '''Class'''
561 | '''Description'''
562 |- style="background-color: #f9f9f9; " |
563 | [[svn:foundation/databoard/trunk/org.simantics.databoard/src/org/simantics/databoard/accessor/Accessor.java|Accessor]]
564 | Base class for all data Accessors
565 |- style="background-color: #f9f9f9; " |
566 | [[svn:foundation/databoard/trunk/org.simantics.databoard/src/org/simantics/databoard/accessor/RecordAccessor.java|RecordAccessor]]
567 | Record 
568 |- style="background-color: #f9f9f9; " |
569 | [[svn:foundation/databoard/trunk/org.simantics.databoard/src/org/simantics/databoard/accessor/ArrayAccessor.java|ArrayAccessor]]
570 | Array - an ordered sequence of elements of one value.
571 |- style="background-color: #f9f9f9; " |
572 | [[svn:foundation/databoard/trunk/org.simantics.databoard/src/org/simantics/databoard/accessor/MapAccessor.java|MapAccessor]]
573 | Map - an ''ordered'' map of keys to values. 
574 |- style="background-color: #f9f9f9; " |
575 | [[svn:foundation/databoard/trunk/org.simantics.databoard/src/org/simantics/databoard/accessor/UnionAccessor.java|UnionAccessor]]
576 | Union
577 |- style="background-color: #f9f9f9; " |
578 | [[svn:foundation/databoard/trunk/org.simantics.databoard/src/org/simantics/databoard/accessor/BooleanAccessor.java|BooleanAccessor]],[[svn:foundation/databoard/trunk/org.simantics.databoard/src/org/simantics/databoard/accessor/IntAccessor.java|IntAccessor]],[[svn:foundation/databoard/trunk/org.simantics.databoard/src/org/simantics/databoard/accessor/LongAccessor.java|LongAccessor]],[[svn:foundation/databoard/trunk/org.simantics.databoard/src/org/simantics/databoard/accessor/FloatAccessor.java|FloatAccessor]],[[svn:foundation/databoard/trunk/org.simantics.databoard/src/org/simantics/databoard/accessor/DoubleAccessor.java|DoubleAccessor]]
579 | Primitive and numeric Accessors
580 |- style="background-color: #f9f9f9; " |
581 | [[svn:foundation/databoard/trunk/org.simantics.databoard/src/org/simantics/databoard/accessor/StringAccessor.java|StringAccessor]]
582 | String 
583 |- style="background-color: #f9f9f9; " |
584 | [[svn:foundation/databoard/trunk/org.simantics.databoard/src/org/simantics/databoard/accessor/OptionalAccessor.java|OptionalAccessor]]
585 | Optional value
586 |- style="background-color: #f9f9f9; " |
587 | [[svn:foundation/databoard/trunk/org.simantics.databoard/src/org/simantics/databoard/accessor/VariantAccessor.java|VariantAccessor]]
588 | Variant value
589 |}
590
591 [[svn:foundation/databoard/trunk/org.simantics.databoard/src/org/simantics/databoard/Accessors.java|Accessors]] and [[svn:foundation/databoard/trunk/org.simantics.databoard/src/org/simantics/databoard/Files.java|Files]] are facade classes that contains utilities for instantiating and handling Accessors.
592
593 <code>[[svn:foundation/databoard/trunk/org.simantics.databoard/src/org/simantics/databoard/accessor/binary/|Binary Accessor]]</code> is an access to a value in binary format (<tt>byte[]</tt> or <tt>ByteBuffer</tt>).
594
595 '''Example:''' Binary accessor
596 <div style="background-color:#fffff7; border: 1px dashed #cccccc; padding: 2ex; margin-left:2em; margin-right:2em; margin-top: 1em; margin-bottom:1em;"><syntaxhighlight lang="java">
597 Datatype type = Datatypes.getDatatype( Rectangle2D.Double.class );
598 Binding binding = Bindings.getBinding( Rectangle2D.Double.class );
599 Serializer s = Binding.getSerializer( binding );
600
601 // Serialize rectangle
602 Rectangle2D rect = new Rectangle2D.Double(0,0, 10, 10);
603 byte[] data = s.serialize(rect);
604
605 // Open accessor to byte data and modify first field in the byte data
606 RecordAccessor ra = Accessors.getAccessor(data, type);
607 ra.setFieldValue(0, Bindings.DOUBLE, 5.0);
608
609 // Deserialize values from the byte data back to the rectangle object
610 s.deserialize(data, rect);
611 System.out.println(rect.getX());
612 </syntaxhighlight></div>
613
614 '''Example:''' File accessor, create
615 <div style="background-color:#fffff7; border: 1px dashed #cccccc; padding: 2ex; margin-left:2em; margin-right:2em; margin-top: 1em; margin-bottom:1em;"><syntaxhighlight lang="java">
616 RecordType type = Datatypes.getDatatype( Rectangle2D.Double.class );
617 // Create a new file and initialize it with rectangle type, and open file accessor
618 FileRecordAccessor fa = Accessors.createFile( file, type );
619
620 // Write the first field (x)
621 fa.setFieldValue(0, Bindings.DOUBLE, 5.0);
622 fa.close();
623 </syntaxhighlight></div>
624
625 '''Example:''' File accessor, open
626 <div style="background-color:#fffff7; border: 1px dashed #cccccc; padding: 2ex; margin-left:2em; margin-right:2em; margin-top: 1em; margin-bottom:1em;"><syntaxhighlight lang="java">
627 // Open an accessor to an existing binary file
628 FileVariantAccessor fa = Accessors.openAccessor(file);
629 RecordAccessor ra = fa.getContentAccessor();
630
631 // Read the first field (x)
632 Double x = (Double) ra.getFieldValue(0, Bindings.DOUBLE);
633 fa.close();
634 </syntaxhighlight></div>
635
636 '''Example:''' Java Accessor
637 <div style="background-color:#fffff7; border: 1px dashed #cccccc; padding: 2ex; margin-left:2em; margin-right:2em; margin-top: 1em; margin-bottom:1em;"><syntaxhighlight lang="java">
638 Binding binding = Bindings.getBinding(Rectangle2D.Double.class);
639 Rectangle2D rect = new Rectangle2D.Double(0,0, 10, 10);
640
641 // Open accessor to rectangle
642 RecordAccessor ra = Accessors.getAccessor(binding, rect);
643
644 // Set rectangle's first field (x) to 5.0
645 ra.setFieldValue(0, Bindings.DOUBLE, 5.0);
646 System.out.println( rect.getX() );
647 </syntaxhighlight></div>
648
649
650 ==Accessor Reference==
651 Accessors can be opened to a sub-nodes with AccessorReference or by calling getAccessor. AccessorReference is a string of instances, either accessor type specific of LabelReferences. 
652     ChildReference ref = ChildReference.compile(
653       new NameReference("node"),
654       new ComponentReference()
655     );
656     Accessor child = accessor.getComponent( ref );
657
658     ChildReference ref = ChildReference.compile(
659        new LabelReference("node"),
660        new LabelReference("v")
661     );
662     Accessor child = accessor.getComponent( ref );
663
664     ChildReference ref = ChildReference.create("n-node/v");
665     Accessor child = accessor.getComponent( ref );
666
667     ChildReference ref = ChildReference.create("node/v");
668     Accessor child = accessor.getComponent( ref );
669
670     VariantAccessor va = recordAccessor.getFieldAccessor("node");
671     Accessor child = va.getValueAccessor();
672
673 ==Listening mechanism==
674 Accessor offers a monitoring mechanism for the data model. 
675 There is an <code>[[svn:foundation/databoard/trunk/org.simantics.databoard/src/org/simantics/databoard/accessor/interestset/InterestSet.java|InterestSet]]</code> that is a description of a sub-tree that is to be monitored of the data model.
676 <code>[[svn:foundation/databoard/trunk/org.simantics.databoard/src/org/simantics/databoard/accessor/event/Event.java|Events]]</code> are objects that spawned on changes to the data model. Each event object is annotated with [[svn:foundation/databoard/trunk/org.simantics.databoard/src/org/simantics/databoard/accessor/reference/|reference path]] that is in relation to the node where the listener was placed.
677
678 Accessor Listeners use [[EventThread Pattern]] pattern.
679
680 =Utilities=
681
682 *[[svn:foundation/databoard/trunk/org.simantics.databoard/src/org/simantics/databoard/Datatypes.java|Datatypes]] is a facade class that has functions for handling Datatypes.
683 *[[svn:foundation/databoard/trunk/org.simantics.databoard/src/org/simantics/databoard/Bindings.java|Bindings]] is a facade class that has functions for handling Bindings.
684 *[[svn:foundation/databoard/trunk/org.simantics.databoard/src/org/simantics/databoard/Accessors.java|Accessors]] is a facade class that has functions for handling Accessors.
685 *[[svn:foundation/databoard/trunk/org.simantics.databoard/src/org/simantics/databoard/Files.java|Files]] has Read, Write and accessor functions.
686 *[[svn:foundation/databoard/trunk/org.simantics.databoard/src/org/simantics/databoard/Units.java|Units]] is a facade class that has functions for handling Engineering Units.
687 *[[svn:foundation/databoard/trunk/org.simantics.databoard/src/org/simantics/databoard/Methods.java|Methods]] has Methods, Interfaces and RPC utility functions.
688
689 *[[svn:foundation/databoard/trunk/org.simantics.databoard/src/org/simantics/databoard/util/binary/RandomAccessBinary.java|RandomAccessBinary]] is a interface for byte handling operations. In addition to basic primitive reading & writing, there are methods for grow, shrink, insert and remove. 
690 **[[svn:foundation/databoard/trunk/org.simantics.databoard/src/org/simantics/databoard/util/binary/BinaryFile.java|BinaryFile]] and [[svn:foundation/databoard/trunk/org.simantics.databoard/src/org/simantics/databoard/util/binary/BinaryMemory.java|BinaryMemory]] are corresponding file and memory implementations. 
691 **[[svn:foundation/databoard/trunk/org.simantics.databoard/src/org/simantics/databoard/util/binary/Blob.java|Blob]] is an implementation that represents a sub-region of a RandomAccessBinary. 
692
693 ==Interface Types==
694 There are interfaces, method types and method type definitions. 
695 Interface type describes a software interface. It is a collection of methods type definitions. 
696 Method type is an unnamed function with the following properties : Response Type, Request Type and ErrorType; where Response Type is any Data Type, Request Type is a Record and Error Type is an Union.
697 Method type definition is nominal method description.
698
699 The respective Java classes are:
700 *[[svn:foundation/databoard/trunk/org.simantics.databoard/src/org/simantics/databoard/method/Interface.java|Interface.java]] 
701 *[[svn:foundation/databoard/trunk/org.simantics.databoard/src/org/simantics/databoard/method/MethodTypeDefinition.java|MethodTypeDefinition.java]]
702 *[[svn:foundation/databoard/trunk/org.simantics.databoard/src/org/simantics/databoard/method/MethodType.java|MethodType.java]]
703
704 In java InterfaceType description can be created with one of the following methods:
705 * Implementing InterfaceType
706 * Reading an Java Interface Class using reflection
707     Interface it = new Interface( ... methodDefinitions );
708     Interface it = getInterface( MyInterface.class );
709
710 [[svn:foundation/databoard/trunk/org.simantics.databoard/src/org/simantics/databoard/method/MethodInterface.java|MethodInterface.java]] is a binding of an
711 Java Instance and an Interface Type. It decouples the method invocation from the object.
712
713 MethodInterface can be created with the following methods:
714 * Implementation
715 * Reflection
716     MethodInterface mi   = new MethodInterface() {...}
717     MethodInterface mi   = Datatypes.bindInterface( MyInterface.class, myObject );
718
719 Utilities <code>Datatypes.createProxy()</code> and <code>Datatypes.bindInterface()</code> adapt between MethodInterface and Java Instance.
720     MethodInterface mi   = Datatypes.bindInterface( MyInterface.class, myObject );
721     MyInterface myObject = Datatypes.createProxy( MyInterface.class, mi );
722
723 ==Remote Procedure Call==
724 Utilities [[svn:foundation/databoard/trunk/org.simantics.databoard/src/org/simantics/databoard/method/Server.java|Server.java]] and [[svn:foundation/databoard/trunk/org.simantics.databoard/src/org/simantics/databoard/method/Client.java|Client.java]] put MethodInterface over TCP Socket. 
725     Server myServer      = new Server(8192, mi);
726     MethodInterface mi   = new Client("localhost", 8192);
727
728 MethodInterface with Server and Client together forms a Remote Procedure Call (RPC) mechanism.
729     public interface MyInterface { String helloWorld(String msg); }
730     
731     [Server]
732     MethodInterface mi   = Methods.bindInterface( MyInterface.class, myObject );
733     Server myServer      = new Server(8192, mi);
734     
735     [Client]
736     MethodInterface mi   = new Client("localhost", 8192);
737     MyInterface myObject = Methods.createProxy( MyInterface.class, mi );
738
739 [[Category: Data management & Experiment Control]]