bundles/org.simantics.databoard/src-isv/doc/adapter.mediawiki

   1 =Adapter=\r
   2 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>[../javadoc/org/simantics/databoard/adapter/Adapter.html|Adapter]</code>.\r
   3 \r
   4 Adapter can be created automatically or implemented self.\r
   5 <pre class="code">\r
   6     Adapter adapter = new Adapter() { ... };\r
   7     Adapter adapter = Bindings.getAdapter( domainBinding, rangeBinding );\r
   8 </pre>\r
   9 \r
  10 Example:\r
  11 <pre class="code">\r
  12     Adapter adapter = Bindings.getAdapter(Bindings.MUTABLE_DOUBLE, Bindings.DOUBLE);\r
  13     java.lang.Double double = adapter.adapt( new MutableDouble(5.0) );\r
  14 </pre>\r
  15 \r
  16 There is also convenience.\r
  17 <pre class="code">\r
  18     java.lang.Double double = Bindings.adapt( new MutableDouble(5.0), Bindings.MUTABLE_DOUBLE, Bindings.DOUBLE );\r
  19 </pre>\r
  20 \r
  21 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.\r
  22 <pre class="code">\r
  23     Adapter cloner = Bindings.adapterCache.getAdapter(domain, range, false, true);\r
  24     cloner.adapt( ... );\r
  25 \r
  26     Rectangle2D rect2 = Bindings.clone( rect1, rectBinding, rectBinding );\r
  27 </pre>\r
  28 \r
  29 ==Type Conversion==\r
  30 In some cases different types may be are type-conversion compatible. An instance of one type is convertible to instance of another.\r
  31 \r
  32 '''Engineering Units of same quantity are convertible.'''\r
  33 <pre class="code">\r
  34     class CarSI {\r
  35         String modelName;               \r
  36         @Unit("km/h") double maxVelocity;               \r
  37         @Unit("kg") double mass;                \r
  38         @Unit("cm") double length; \r
  39         @Unit("kW") double power;\r
  40     }\r
  41     \r
  42     class CarIm {\r
  43         String modelName;               \r
  44         @Unit("mph") float maxVelocity;         \r
  45         @Unit("lbs") float mass;                \r
  46         @Unit("ft") float length; \r
  47         @Unit("hp(M)") float power;\r
  48     }\r
  49     \r
  50     Adapter si2imAdapter = Bindings.getTypeAdapter(\r
  51         Bindings.getBinding(CarSI.class), \r
  52         Bindings.getBinding(CarIm.class) );\r
  53     \r
  54     CarIm americanCarInfo = si2imAdapter.adapt( europeanCarInfo );\r
  55 </pre>\r
  56 \r
  57 '''Primitive Types.''' Note, primitive adapter throws an exception at runtime if values are not adaptable.\r
  58 <pre class="code">\r
  59     Adapter adapter = getTypeAdapter( integerBinding, doubleBinding );\r
  60     Double double = adapter.adapt( new Integer( 5 ) );\r
  61 </pre>\r
  62 \r
  63 '''Records are matched by field names.'''\r
  64 <pre class="code">\r
  65     class Foo {\r
  66         int x, y, z;\r
  67     }\r
  68     class Bar {\r
  69         int z, y, x;\r
  70     }\r
  71     Adapter adapter = getTypeAdapter( fooBinding, barBinding );\r
  72 </pre>    \r
  73 \r
  74 '''Subtype to supertype:''' Note, this conversion cannot be not symmetric, supertypes cannot be converted to subtypes.\r
  75 <pre class="code">\r
  76     class Node {\r
  77         String id;\r
  78     }\r
  79     class ValueNode extends Node {\r
  80         Object value;\r
  81     }\r
  82     Adapter adapter = getTypeAdapter( valueNodeBinding, nodeBinding );\r
  83 </pre>\r
  84 \r
  85 '''Non-existing fields to Optional fields'''\r
  86 <pre class="code"> \r
  87     class Node {\r
  88         String id;\r
  89     }\r
  90     class NominalNode {\r
  91         String id;\r
  92         @Optional String name;\r
  93     }\r
  94     Adapter adapter = getTypeAdapter( nodeBinding, nominalNodeBinding );\r
  95 </pre>    \r
  96 \r
  97 '''Enumerations'''\r
  98 <pre class="code">\r
  99     enum Cars { Audio, BMW, Mercedes, Honda, Mazda, Toyota, Ford, Mitsubishi, Nissan, GM }\r
 100     enum JapaneseCars { Honda, Mazda, Toyota, Nissan, Mitsubishi }\r
 101     \r
 102     Binding carsBinding = Bindings.getBinding( Cars.class );\r
 103     Binding japaneseCarsBinding = Bindings.getBinding( JapaneseCars.class );\r
 104     Adapter adapter = Bindings.adapterCache.getAdapter(japaneseCarsBinding, carsBinding, true, false);\r
 105 </pre>