Migrated source code from Simantics SVN

[simantics/platform.git] / bundles / org.simantics.databoard / src-isv / doc / adapter.mediawiki

diff --git a/bundles/org.simantics.databoard/src-isv/doc/adapter.mediawiki b/bundles/org.simantics.databoard/src-isv/doc/adapter.mediawiki
new file mode 100644 (file)
index 0000000..8cead36
--- /dev/null
+++ b/bundles/org.simantics.databoard/src-isv/doc/adapter.mediawiki
@@ -0,0 +1,105 @@
+=Adapter=\r
+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
+\r
+Adapter can be created automatically or implemented self.\r
+<pre class="code">\r
+    Adapter adapter = new Adapter() { ... };\r
+    Adapter adapter = Bindings.getAdapter( domainBinding, rangeBinding );\r
+</pre>\r
+\r
+Example:\r
+<pre class="code">\r
+    Adapter adapter = Bindings.getAdapter(Bindings.MUTABLE_DOUBLE, Bindings.DOUBLE);\r
+    java.lang.Double double = adapter.adapt( new MutableDouble(5.0) );\r
+</pre>\r
+\r
+There is also convenience.\r
+<pre class="code">\r
+    java.lang.Double double = Bindings.adapt( new MutableDouble(5.0), Bindings.MUTABLE_DOUBLE, Bindings.DOUBLE );\r
+</pre>\r
+\r
+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
+<pre class="code">\r
+    Adapter cloner = Bindings.adapterCache.getAdapter(domain, range, false, true);\r
+    cloner.adapt( ... );\r
+\r
+    Rectangle2D rect2 = Bindings.clone( rect1, rectBinding, rectBinding );\r
+</pre>\r
+\r
+==Type Conversion==\r
+In some cases different types may be are type-conversion compatible. An instance of one type is convertible to instance of another.\r
+\r
+'''Engineering Units of same quantity are convertible.'''\r
+<pre class="code">\r
+    class CarSI {\r
+        String modelName;              \r
+        @Unit("km/h") double maxVelocity;              \r
+        @Unit("kg") double mass;               \r
+        @Unit("cm") double length; \r
+        @Unit("kW") double power;\r
+    }\r
+    \r
+    class CarIm {\r
+        String modelName;              \r
+        @Unit("mph") float maxVelocity;                \r
+        @Unit("lbs") float mass;               \r
+        @Unit("ft") float length; \r
+        @Unit("hp(M)") float power;\r
+    }\r
+    \r
+    Adapter si2imAdapter = Bindings.getTypeAdapter(\r
+        Bindings.getBinding(CarSI.class), \r
+        Bindings.getBinding(CarIm.class) );\r
+    \r
+    CarIm americanCarInfo = si2imAdapter.adapt( europeanCarInfo );\r
+</pre>\r
+\r
+'''Primitive Types.''' Note, primitive adapter throws an exception at runtime if values are not adaptable.\r
+<pre class="code">\r
+    Adapter adapter = getTypeAdapter( integerBinding, doubleBinding );\r
+    Double double = adapter.adapt( new Integer( 5 ) );\r
+</pre>\r
+\r
+'''Records are matched by field names.'''\r
+<pre class="code">\r
+    class Foo {\r
+        int x, y, z;\r
+    }\r
+    class Bar {\r
+        int z, y, x;\r
+    }\r
+    Adapter adapter = getTypeAdapter( fooBinding, barBinding );\r
+</pre>    \r
+\r
+'''Subtype to supertype:''' Note, this conversion cannot be not symmetric, supertypes cannot be converted to subtypes.\r
+<pre class="code">\r
+    class Node {\r
+        String id;\r
+    }\r
+    class ValueNode extends Node {\r
+        Object value;\r
+    }\r
+    Adapter adapter = getTypeAdapter( valueNodeBinding, nodeBinding );\r
+</pre>\r
+\r
+'''Non-existing fields to Optional fields'''\r
+<pre class="code"> \r
+    class Node {\r
+        String id;\r
+    }\r
+    class NominalNode {\r
+        String id;\r
+        @Optional String name;\r
+    }\r
+    Adapter adapter = getTypeAdapter( nodeBinding, nominalNodeBinding );\r
+</pre>    \r
+\r
+'''Enumerations'''\r
+<pre class="code">\r
+    enum Cars { Audio, BMW, Mercedes, Honda, Mazda, Toyota, Ford, Mitsubishi, Nissan, GM }\r
+    enum JapaneseCars { Honda, Mazda, Toyota, Nissan, Mitsubishi }\r
+    \r
+    Binding carsBinding = Bindings.getBinding( Cars.class );\r
+    Binding japaneseCarsBinding = Bindings.getBinding( JapaneseCars.class );\r
+    Adapter adapter = Bindings.adapterCache.getAdapter(japaneseCarsBinding, carsBinding, true, false);\r
+</pre>
\ No newline at end of file