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]]