--- /dev/null
+center>'''Databoard 0.6.1 Developer Manual'''</center>\r
+\r
+=Datatype=\r
+In Databoard all values have a type representation, [[svn:foundation/databoard/trunk/org.simantics.databoard/src/org/simantics/databoard/type/Datatype.java|Datatype.java]]. \r
+It is the base abstract class for all concrete type classes (See table below). \r
+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.\r
+\r
+'''[[svn:foundation/databoard/trunk/org.simantics.databoard/src/org/simantics/databoard/type|org.simantics.databoard.type]]'''.\r
+{| style="background-color: #e9e9e9; border: 1px solid #aaaaaa; "\r
+| '''Class'''\r
+| '''Description'''\r
+|- style="background-color: #f9f9f9; " |\r
+| [[svn:foundation/databoard/trunk/org.simantics.databoard/src/org/simantics/databoard/type/Datatype.java|Datatype]]\r
+| Base class for all data types\r
+|- style="background-color: #f9f9f9; " |\r
+| [[svn:foundation/databoard/trunk/org.simantics.databoard/src/org/simantics/databoard/type/RecordType.java|RecordType]]\r
+| Record \r
+|- style="background-color: #f9f9f9; " |\r
+| [[svn:foundation/databoard/trunk/org.simantics.databoard/src/org/simantics/databoard/type/ArrayType.java|ArrayType]]\r
+| Array - an ordered sequence of elements of one type.\r
+|- style="background-color: #f9f9f9; " |\r
+| [[svn:foundation/databoard/trunk/org.simantics.databoard/src/org/simantics/databoard/type/MapType.java|MapType]]\r
+| Map - an ordered map of keys to values. \r
+|- style="background-color: #f9f9f9; " |\r
+| [[svn:foundation/databoard/trunk/org.simantics.databoard/src/org/simantics/databoard/type/UnionType.java|UnionType]]\r
+| Union\r
+|- style="background-color: #f9f9f9; " |\r
+| [[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]]\r
+| Primitive and numeric types\r
+|- style="background-color: #f9f9f9; " |\r
+| [[svn:foundation/databoard/trunk/org.simantics.databoard/src/org/simantics/databoard/type/StringType.java|StringType]]\r
+| String \r
+|- style="background-color: #f9f9f9; " |\r
+| [[svn:foundation/databoard/trunk/org.simantics.databoard/src/org/simantics/databoard/type/OptionalType.java|OptionalType]]\r
+| Optional value\r
+|- style="background-color: #f9f9f9; " |\r
+| [[svn:foundation/databoard/trunk/org.simantics.databoard/src/org/simantics/databoard/type/VariantType.java|VariantType]]\r
+| Variant value\r
+|}\r
+\r
+\r
+Datatype can be acquired or created using one of the following methods:\r
+* Construct new\r
+* Constant \r
+* [[#Reflection|Reflection]]-Read from a Class\r
+* Read from string of [[Databoard_Specification|the text notation]].\r
+ Datatype type = new DoubleType();\r
+ Datatype type = Datatypes.DOUBLE;\r
+ Datatype type = Datatypes.getDatatype( Double.class );\r
+ \r
+ Datatypes.addDefinition("type Node = { id : String; children : Node[] }");\r
+ Datatype type = Datatypes.getDatatype("Node");\r
+\r
+\r
+==Parsing==\r
+Datatypes are parsed using <code>Datatypes.DatatypeRepository</code>. \r
+ Datatypes.addDefinition("type Node = { id : String; children : Node[] }");\r
+ Datatype type = Datatypes.getDatatype("Node");\r
+\r
+Types are printed to types and definitions with \r
+ String type = type.toString();\r
+ \r
+ DatatypeRepository repo = new DatatypeRepository();\r
+ repo.add("temp1", type);\r
+ String typeDef = repo.toString();\r
+\r
+==Structure Example==\r
+A node is a recursive type. With databoard typesystem it could be stated as\r
+ type Node = {\r
+ id : String;\r
+ displayNames : LocalizedTexts;\r
+ children : Node[];\r
+ value : Optional(Variant);\r
+ }\r
+\r
+[[Image:NodeType.png|Type presented as tree]]\r
+\r
+\r
+A couple of instances with Databoard value notation:\r
+ root : Node = {\r
+ id = \93PI_01\94\r
+ displayNames = map{ \93en\94 = \93Instrument \93 }\r
+ children = \r
+ [ \r
+ {id=\94Child\94, \r
+ displayNames = map{ \93en\94 = \93Child\94} },\r
+ value = 5 : Integer\r
+ }\r
+ ]\r
+ value = \93<root>\94 : String\r
+ }\r
+\r
+[[Image:NodeInstance.png|Node values preseted as tree]]\r
+\r
+=Binding=\r
+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. \r
+\r
+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. \r
+ Java Object + Binding = Databoard Value\r
+\r
+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
+ Binding binding = Binding.getBinding( Double.class );\r
+\r
+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
+ Binding binding = new RecordBinding() { ... };\r
+\r
+\r
+'''[[svn:foundation/databoard/trunk/org.simantics.databoard/src/org/simantics/databoard/binding|org.simantics.databoard.binding]]'''.\r
+{| style="background-color: #e9e9e9; border: 1px solid #aaaaaa; "\r
+| '''Class'''\r
+| '''Description'''\r
+|- style="background-color: #f9f9f9; " |\r
+| [[svn:foundation/databoard/trunk/org.simantics.databoard/src/org/simantics/databoard/binding/DataBinding.java|DataBinding]]\r
+| Base class for all data Bindings\r
+|- style="background-color: #f9f9f9; " |\r
+| [[svn:foundation/databoard/trunk/org.simantics.databoard/src/org/simantics/databoard/binding/RecordBinding.java|RecordBinding]]\r
+| Record \r
+|- style="background-color: #f9f9f9; " |\r
+| [[svn:foundation/databoard/trunk/org.simantics.databoard/src/org/simantics/databoard/binding/ArrayBinding.java|ArrayBinding]]\r
+| Array - an ordered sequence of elements of one value.\r
+|- style="background-color: #f9f9f9; " |\r
+| [[svn:foundation/databoard/trunk/org.simantics.databoard/src/org/simantics/databoard/binding/MapBinding.java|MapBinding]]\r
+| Map - an ''ordered'' map of keys to values. \r
+|- style="background-color: #f9f9f9; " |\r
+| [[svn:foundation/databoard/trunk/org.simantics.databoard/src/org/simantics/databoard/binding/UnionBinding.java|UnionBinding]]\r
+| Union\r
+|- style="background-color: #f9f9f9; " |\r
+| [[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]]\r
+| Primitive and numeric Bindings\r
+|- style="background-color: #f9f9f9; " |\r
+| [[svn:foundation/databoard/trunk/org.simantics.databoard/src/org/simantics/databoard/binding/StringBinding.java|StringBinding]]\r
+| String \r
+|- style="background-color: #f9f9f9; " |\r
+| [[svn:foundation/databoard/trunk/org.simantics.databoard/src/org/simantics/databoard/binding/OptionalBinding.java|OptionalBinding]]\r
+| Optional value\r
+|- style="background-color: #f9f9f9; " |\r
+| [[svn:foundation/databoard/trunk/org.simantics.databoard/src/org/simantics/databoard/binding/VariantBinding.java|VariantBinding]]\r
+| Variant value\r
+|}\r
+\r
+\r
+Binding can be acquired or created using one of the following methods:\r
+* Constructor \r
+* Constant\r
+* Reflection-Read from a Class \r
+* Created using [[svn:foundation/databoard/trunk/org.simantics.databoard/src/org/simantics/databoard/bindingscheme/BindingScheme.java|BindingScheme]]\r
+ Binding binding = new DoubleBinding( doubleType );\r
+ Binding binding = new RecordBinding() { ... };\r
+ Binding binding = Bindings.DOUBLE;\r
+ Binding binding = Binding.getBinding( Double.class );\r
+ Binding binding = Binding.getBinding( Datatypes.DOUBLE );\r
+\r
+==Reflection==\r
+'''Data Type and Binding can be read automatically from a Class by utility.'''\r
+ Datatype type = Datatypes.getDatatype( Foo.class );\r
+ Binding binding = Bindings.getBinding( Foo.class );\r
+\r
+Bindings for generics classes can be created by passing arguments.\r
+ Binding e = Bindings.getBinding(List.class, String.class);\r
+ List<String> list = (List<String>) e.createRandom(5);\r
+\r
+ Binding binding = Bindings.getBinding( Map.class, Integer.class, Integer.class );\r
+ Map<Integer, Integer> value = (Map<Integer, Integer>) binding.createDefault();\r
+\r
+Even cascading generics...\r
+ Binding e = Bindings.getBinding(List.class, List.class, String.class);\r
+ List<List<String>> listList = (List<List<String>>) e.createRandom(5);\r
+\r
+\r
+'''Classes are RecordTypes'''\r
+ class Foo {\r
+ public int x, y, z;\r
+ }\r
+Is a binding to the following Datatype\r
+ type Foo = { x : Integer, y : Integer, z : Integer }\r
+\r
+'''There are three types of classes supported, and therefore three ways how objects are constructed.'''\r
+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
+\r
+''Record-like classes:''\r
+ class Foo {\r
+ public String name;\r
+ public Object value;\r
+ }\r
+\r
+''Immutable classes:''\r
+ class Foo {\r
+ private String name;\r
+ private Object value;\r
+ \r
+ public Foo(String name, Object value) {\r
+ this.name = name;\r
+ this.value = value;\r
+ }\r
+ \r
+ public String getName() {\r
+ return name;\r
+ }\r
+ \r
+ public Object getValue() {\r
+ return value;\r
+ }\r
+ \r
+ }\r
+\r
+''Bean-like classes:''\r
+ class Foo {\r
+ private String name;\r
+ private Object value;\r
+ \r
+ public void setName(String name) {\r
+ this.name = name;\r
+ }\r
+ \r
+ public void setValue(Object value) {\r
+ this.value = value;\r
+ }\r
+ \r
+ public String getName() {\r
+ return name;\r
+ }\r
+ \r
+ public Object getValue() {\r
+ return value;\r
+ }\r
+ \r
+ }\r
+\r
+'''Static and transient fields are omited:'''\r
+ static final long serialVersionUID = -3387516993124229943L;\r
+ transient int hashCode;\r
+\r
+'''Enumerations are Union Types'''\r
+ enum Cars { Ferrari, Porche, Lamborghini, Jaguar } \r
+is interpreted as union type\r
+ type Cars = | Ferrari | Porche | Lamborghini | Jaguar\r
+\r
+If you cannot modify the class, you have to create binding for it by subclassing base binding classes, eg. RecordBinding.\r
+\r
+'''Other exceptions:'''\r
+*<code>java.lang.Object</code> is <tt>Variant</tt>.\r
+*<code>java.lang.Set<T></code> is <tt>Map(T, {})</tt>.\r
+*<code>java.lang.TreeSet<T></code> is <tt>Map(T, {})</tt>.\r
+*<code>java.lang.HashSet<T></code> is <tt>Map(T, {})</tt>. (Note HashSet binding has very low performance.)\r
+*<code>java.lang.Map<K, V></code> is <tt>Map(K, V)</tt>.\r
+*<code>java.lang.TreeMap<K, V></code> is <tt>Map(K, V)</tt>.\r
+*<code>java.lang.HashMap<K, V></code> is <tt>Map(K, V)</tt>. (Note HashMap binding has very low performance.)\r
+*<code>java.lang.List<T></code> is <tt>Array(T)</tt>.\r
+*<code>java.lang.ArrayList<T></code> is <tt>Array(T)</tt>.\r
+*<code>java.lang.LinkedList<T></code> is <tt>Array(T)</tt>.\r
+*<code>void</code> is <tt>{}</tt>.\r
+*The stacktrace of <code>Exception.class</code> is omited.\r
+\r
+===Annotations===\r
+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]]''').\r
+\r
+\r
+'''UnionTypes are abstract classes or interfaces with <code>@Union</code> annotation.'''\r
+ @Union({A.class, B.class}) interface Union1 { \r
+ }\r
+ \r
+ class A implements Union1 {\r
+ public int value;\r
+ }\r
+ \r
+ class B implements Union1 {\r
+ public String name;\r
+ }\r
+\r
+\r
+'''<code>@Referable</code> denotes that the class has recursion and is a referable record.'''\r
+ public @Referable class Node {\r
+ public Node[] children;\r
+ }\r
+\r
+\r
+'''Fields that can have <tt>null</tt> value have <code>@Optional</code> annotation.'''\r
+ @Optional String name;\r
+\r
+\r
+'''String valid values are set with <code>@Pattern</code> as regular expression. ([http://en.wikipedia.org/wiki/Regular_expression])'''\r
+ String @Pattern("(19|20)\\d\\d[- /.](0[1-9]|1[012])[- /.](0[1-9]|[12][0-9]|3[01])") date;\r
+ \r
+ type Date = String( Pattern = "(19|20)\d\d[- /.](0[1-9]|1[012])[- /.](0[1-9]|[12][0-9]|3[01])" )\r
+\r
+\r
+'''String content type is set with a <code>@MIMEType</code>. ([http://en.wikipedia.org/wiki/Mime_type MIME Type])'''\r
+ @MIMEType("text/xml") String document;\r
+\r
+\r
+'''Array size restricted with @Length.'''\r
+ @Length("[0..10]") int[] array;\r
+ @Length({"[320]", "[240]"}) int[][] image;\r
+\r
+\r
+'''Valid numeric range is set with @Range.'''\r
+ @Range("[0..100]") double alpha;\r
+ @Range("[0..]" double length;\r
+\r
+\r
+'''<tt>Range</tt> and <tt>Length</tt> notation:'''\r
+*Exact Value "0"\r
+*Exclude all "()"\r
+*Unlimited "[..]"\r
+*Inclusive range "[0..100]"\r
+*Exclusive range "(0..100)"\r
+*Inclusive lower bound and exclusive upper bound "[0..100)"\r
+\r
+\r
+'''Engineering unit type is given with @Unit.'''\r
+ @Unit("km/h") double maxVelocity;\r
+\r
+'''The serializer generated with reflection can be overriden with @SpecializedSerializer'''\r
+ @SpecializedSerializer(MySerializer.class) \r
+ public class MyRecord {\r
+ ...\r
+ }\r
+\r
+== Mapping Scheme ==\r
+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
+\r
+<code>DefaultBindingScheme</code> is a scheme that converts any datatype to a binding. It prefers java.lang.X primitives.\r
+The Class mapping for each type is listed below.\r
+{| style="background-color: #e9e9e9; border: 1px solid #aaaaaa; "\r
+| '''Type'''\r
+| '''Class'''\r
+|- style="background-color: #f9f9f9; " |\r
+| <code>BooleanType</code>\r
+| <code>Boolean.class</code>\r
+|- style="background-color: #f9f9f9; " |\r
+| <code>ByteType</code>\r
+| <code>Byte.class</code>\r
+|- style="background-color: #f9f9f9; " |\r
+| <code>FloatType</code>\r
+| <code>Float.class</code>\r
+|- style="background-color: #f9f9f9; " |\r
+| <code>DoubleType</code>\r
+| <code>eDouble.class</code>\r
+|- style="background-color: #f9f9f9; " |\r
+| <code>IntegerType</code>\r
+| <code>Integer.class</code>\r
+|- style="background-color: #f9f9f9; " |\r
+| <code>LongType</code>\r
+| <code>Long.class</code>\r
+|- style="background-color: #f9f9f9; " |\r
+| <code>StringType</code>\r
+| <code>String.class</code>\r
+|- style="background-color: #f9f9f9; " |\r
+| <code>UnionType</code>\r
+| <code>TaggedObject.class</code>\r
+|- style="background-color: #f9f9f9; " |\r
+| <code>OptionType</code>\r
+| <code>ValueContainer.class</code>\r
+|- style="background-color: #f9f9f9; " |\r
+| <code>RecordType</code>\r
+| <code>Object[].class</code>\r
+|- style="background-color: #f9f9f9; " |\r
+| <code>ArrayType</code>\r
+| <code>ArrayList.class</code>\r
+|- style="background-color: #f9f9f9; " |\r
+| <code>Array(Byte)</code>\r
+| <code>byte[].class</code>\r
+|- style="background-color: #f9f9f9; " |\r
+| <code>MapType</code>\r
+| <code>TreeMap.class</code>\r
+|- style="background-color: #f9f9f9; " |\r
+| <code>VariantType</code>\r
+| <code>Variant.class</code>\r
+|}\r
+\r
+<code>MutableBindingScheme</code> is a scheme that provides a fully implementing mutable binding for all data types. \r
+The Class mapping for each type is listed below.\r
+\r
+{| style="background-color: #e9e9e9; border: 1px solid #aaaaaa; "\r
+| '''Type'''\r
+| '''Class'''\r
+|- style="background-color: #f9f9f9; " |\r
+| <code>BooleanType</code>\r
+| <code>MutableBoolean.class</code>\r
+|- style="background-color: #f9f9f9; " |\r
+| <code>ByteType</code>\r
+| <code>MutableByte.class</code>\r
+|- style="background-color: #f9f9f9; " |\r
+| <code>FloatType</code>\r
+| <code>MutableFloat.class</code>\r
+|- style="background-color: #f9f9f9; " |\r
+| <code>DoubleType</code>\r
+| <code>MutableDouble.class</code>\r
+|- style="background-color: #f9f9f9; " |\r
+| <code>IntegerType</code>\r
+| <code>MutableInt.class</code>\r
+|- style="background-color: #f9f9f9; " |\r
+| <code>LongType</code>\r
+| <code>MutableLong.class</code>\r
+|- style="background-color: #f9f9f9; " |\r
+| <code>StringType</code>\r
+| <code>MutableString.class</code>\r
+|- style="background-color: #f9f9f9; " |\r
+| <code>UnionType</code>\r
+| <code>TaggedObject.class</code>\r
+|- style="background-color: #f9f9f9; " |\r
+| <code>OptionType</code>\r
+| <code>ValueContainer.class</code>\r
+|- style="background-color: #f9f9f9; " |\r
+| <code>RecordType</code>\r
+| <code>Object[].class</code>\r
+|- style="background-color: #f9f9f9; " |\r
+| <code>ArrayType</code>\r
+| <code>ArrayList.class</code>\r
+|- style="background-color: #f9f9f9; " |\r
+| <code>MapType</code>\r
+| <code>TreeMap.class</code>\r
+|- style="background-color: #f9f9f9; " |\r
+| <code>VariantType</code>\r
+| <code>Variant.class</code>\r
+|}\r
+\r
+\r
+===Serialization===\r
+[[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]].\r
+\r
+ Binding binding = Bindings.DOUBLE;\r
+ Serializer serializer = Bindings.getSerializer( binding );\r
+ byte[] data = serializer.serialize( new Double( 100.0 ) );\r
+ \r
+ Double value = (Double) serializer.deserialize( data );\r
+\r
+Files can be partially accessed using BinaryAccessor, see [[#Accessors|Accessors]]. This is useful when handling larger than memory files.\r
+\r
+===Validation===\r
+'''Value''' can be ''well-formed'' or ''valid''. \r
+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
+\r
+Validation mechanism in Binding asserts that the instance is a valid value of the respective Data Type.\r
+ try {\r
+ Binding.assertInstaceIsValid( object );\r
+ } catch( BindingException e ) {\r
+ // In-valid object\r
+ }\r
+\r
+===Other Notes===\r
+*<tt>Binding</tt> is a <tt>Comparator</tt>, all data values are comparable, the order is defined in [[Databoard_Specification#Comparison|Specification]].\r
+*<tt>Binding#createDefault()</tt> creates a valid instance of the Datatype.\r
+*<tt>Binding#createRandom(int)</tt> creates a valid instance with random values. Useful for unit tests.\r
+*<tt>Binding#clone(Object)</tt> creates a new instance with same content.\r
+*<tt>Binding#readFrom(Object, Binding, Binding)</tt> copies contents from another object of same type.\r
+\r
+===Parsing & Printing===\r
+\r
+Data values are printed and parsed of the [[Databoard_Specification|Text notation]] with the following <code>Binding</code> methods:\r
+\r
+ String text = binding.printValue( value, true );\r
+ \r
+ Object value = binding.parseValue( text );\r
+\r
+And also to value definitions <tt>''name : type = value''</tt>\r
+ StringBuilder sb = new StringBuilder();\r
+ DataValueRepository repo = new DataValueRepository();\r
+ repo.put( "temp", binding, value );\r
+ binding.printValue( value, sb, repo, true );\r
+ String text = sb.toString();\r
+ \r
+ Object value = binding.parseValueDefinition( text );\r
+\r
+=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>[[svn:foundation/databoard/trunk/org.simantics.databoard/src/org/simantics/databoard/adapter/Adapter.java|Adapter]]</code>.\r
+\r
+Adapter can be created automatically or implemented self.\r
+ Adapter adapter = new Adapter() { ... };\r
+ Adapter adapter = Bindings.getAdapter( domainBinding, rangeBinding );\r
+\r
+Example:\r
+ Adapter adapter = Bindings.getAdapter(Bindings.MUTABLE_DOUBLE, Bindings.DOUBLE);\r
+ java.lang.Double double = adapter.adapt( new MutableDouble(5.0) );\r
+\r
+There is also convenience.\r
+ java.lang.Double double = Bindings.adapt( new MutableDouble(5.0), Bindings.MUTABLE_DOUBLE, Bindings.DOUBLE );\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
+ Adapter cloner = Bindings.adapterCache.getAdapter(domain, range, false, true);\r
+ cloner.adapt( ... );\r
+\r
+ Rectangle2D rect2 = Bindings.clone( rect1, rectBinding, rectBinding );\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
+ 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
+\r
+\r
+'''Primitive Types.''' Note, primitive adapter throws an exception at runtime if values are not adaptable.\r
+ Adapter adapter = getTypeAdapter( integerBinding, doubleBinding );\r
+ Double double = adapter.adapt( new Integer( 5 ) );\r
+\r
+\r
+'''Records are matched by field names.'''\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
+ \r
+\r
+'''Subtype to supertype:''' Note, this conversion cannot be not symmetric, supertypes cannot be converted to subtypes.\r
+ class Node {\r
+ String id;\r
+ }\r
+ class ValueNode extends Node {\r
+ Object value;\r
+ }\r
+ Adapter adapter = getTypeAdapter( valueNodeBinding, nodeBinding );\r
+\r
+'''Non-existing fields to Optional fields''' \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
+ \r
+\r
+'''Enumerations'''\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
+\r
+=Accessors=\r
+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). \r
+\r
+'''[[svn:foundation/databoard/trunk/org.simantics.databoard/src/org/simantics/databoard/accessor|org.simantics.databoard.accessor]] interfaces'''.\r
+{| style="background-color: #e9e9e9; border: 1px solid #aaaaaa; "\r
+| '''Class'''\r
+| '''Description'''\r
+|- style="background-color: #f9f9f9; " |\r
+| [[svn:foundation/databoard/trunk/org.simantics.databoard/src/org/simantics/databoard/accessor/Accessor.java|Accessor]]\r
+| Base class for all data Accessors\r
+|- style="background-color: #f9f9f9; " |\r
+| [[svn:foundation/databoard/trunk/org.simantics.databoard/src/org/simantics/databoard/accessor/RecordAccessor.java|RecordAccessor]]\r
+| Record \r
+|- style="background-color: #f9f9f9; " |\r
+| [[svn:foundation/databoard/trunk/org.simantics.databoard/src/org/simantics/databoard/accessor/ArrayAccessor.java|ArrayAccessor]]\r
+| Array - an ordered sequence of elements of one value.\r
+|- style="background-color: #f9f9f9; " |\r
+| [[svn:foundation/databoard/trunk/org.simantics.databoard/src/org/simantics/databoard/accessor/MapAccessor.java|MapAccessor]]\r
+| Map - an ''ordered'' map of keys to values. \r
+|- style="background-color: #f9f9f9; " |\r
+| [[svn:foundation/databoard/trunk/org.simantics.databoard/src/org/simantics/databoard/accessor/UnionAccessor.java|UnionAccessor]]\r
+| Union\r
+|- style="background-color: #f9f9f9; " |\r
+| [[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]]\r
+| Primitive and numeric Accessors\r
+|- style="background-color: #f9f9f9; " |\r
+| [[svn:foundation/databoard/trunk/org.simantics.databoard/src/org/simantics/databoard/accessor/StringAccessor.java|StringAccessor]]\r
+| String \r
+|- style="background-color: #f9f9f9; " |\r
+| [[svn:foundation/databoard/trunk/org.simantics.databoard/src/org/simantics/databoard/accessor/OptionalAccessor.java|OptionalAccessor]]\r
+| Optional value\r
+|- style="background-color: #f9f9f9; " |\r
+| [[svn:foundation/databoard/trunk/org.simantics.databoard/src/org/simantics/databoard/accessor/VariantAccessor.java|VariantAccessor]]\r
+| Variant value\r
+|}\r
+\r
+[[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.\r
+\r
+<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>).\r
+\r
+'''Example:''' Binary accessor\r
+<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">\r
+Datatype type = Datatypes.getDatatype( Rectangle2D.Double.class );\r
+Binding binding = Bindings.getBinding( Rectangle2D.Double.class );\r
+Serializer s = Binding.getSerializer( binding );\r
+\r
+// Serialize rectangle\r
+Rectangle2D rect = new Rectangle2D.Double(0,0, 10, 10);\r
+byte[] data = s.serialize(rect);\r
+\r
+// Open accessor to byte data and modify first field in the byte data\r
+RecordAccessor ra = Accessors.getAccessor(data, type);\r
+ra.setFieldValue(0, Bindings.DOUBLE, 5.0);\r
+\r
+// Deserialize values from the byte data back to the rectangle object\r
+s.deserialize(data, rect);\r
+System.out.println(rect.getX());\r
+</syntaxhighlight></div>\r
+\r
+'''Example:''' File accessor, create\r
+<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">\r
+RecordType type = Datatypes.getDatatype( Rectangle2D.Double.class );\r
+// Create a new file and initialize it with rectangle type, and open file accessor\r
+FileRecordAccessor fa = Accessors.createFile( file, type );\r
+\r
+// Write the first field (x)\r
+fa.setFieldValue(0, Bindings.DOUBLE, 5.0);\r
+fa.close();\r
+</syntaxhighlight></div>\r
+\r
+'''Example:''' File accessor, open\r
+<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">\r
+// Open an accessor to an existing binary file\r
+FileVariantAccessor fa = Accessors.openAccessor(file);\r
+RecordAccessor ra = fa.getContentAccessor();\r
+\r
+// Read the first field (x)\r
+Double x = (Double) ra.getFieldValue(0, Bindings.DOUBLE);\r
+fa.close();\r
+</syntaxhighlight></div>\r
+\r
+'''Example:''' Java Accessor\r
+<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">\r
+Binding binding = Bindings.getBinding(Rectangle2D.Double.class);\r
+Rectangle2D rect = new Rectangle2D.Double(0,0, 10, 10);\r
+\r
+// Open accessor to rectangle\r
+RecordAccessor ra = Accessors.getAccessor(binding, rect);\r
+\r
+// Set rectangle's first field (x) to 5.0\r
+ra.setFieldValue(0, Bindings.DOUBLE, 5.0);\r
+System.out.println( rect.getX() );\r
+</syntaxhighlight></div>\r
+\r
+\r
+==Accessor Reference==\r
+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. \r
+ ChildReference ref = ChildReference.compile(\r
+ new NameReference("node"),\r
+ new ComponentReference()\r
+ );\r
+ Accessor child = accessor.getComponent( ref );\r
+\r
+ ChildReference ref = ChildReference.compile(\r
+ new LabelReference("node"),\r
+ new LabelReference("v")\r
+ );\r
+ Accessor child = accessor.getComponent( ref );\r
+\r
+ ChildReference ref = ChildReference.create("n-node/v");\r
+ Accessor child = accessor.getComponent( ref );\r
+\r
+ ChildReference ref = ChildReference.create("node/v");\r
+ Accessor child = accessor.getComponent( ref );\r
+\r
+ VariantAccessor va = recordAccessor.getFieldAccessor("node");\r
+ Accessor child = va.getValueAccessor();\r
+\r
+==Listening mechanism==\r
+Accessor offers a monitoring mechanism for the data model. \r
+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.\r
+<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.\r
+\r
+Accessor Listeners use [[EventThread Pattern]] pattern.\r
+\r
+=Utilities=\r
+\r
+*[[svn:foundation/databoard/trunk/org.simantics.databoard/src/org/simantics/databoard/Datatypes.java|Datatypes]] is a facade class that has functions for handling Datatypes.\r
+*[[svn:foundation/databoard/trunk/org.simantics.databoard/src/org/simantics/databoard/Bindings.java|Bindings]] is a facade class that has functions for handling Bindings.\r
+*[[svn:foundation/databoard/trunk/org.simantics.databoard/src/org/simantics/databoard/Accessors.java|Accessors]] is a facade class that has functions for handling Accessors.\r
+*[[svn:foundation/databoard/trunk/org.simantics.databoard/src/org/simantics/databoard/Files.java|Files]] has Read, Write and accessor functions.\r
+*[[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.\r
+*[[svn:foundation/databoard/trunk/org.simantics.databoard/src/org/simantics/databoard/Methods.java|Methods]] has Methods, Interfaces and RPC utility functions.\r
+\r
+*[[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. \r
+**[[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. \r
+**[[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. \r
+\r
+==Interface Types==\r
+There are interfaces, method types and method type definitions. \r
+Interface type describes a software interface. It is a collection of methods type definitions. \r
+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.\r
+Method type definition is nominal method description.\r
+\r
+The respective Java classes are:\r
+*[[svn:foundation/databoard/trunk/org.simantics.databoard/src/org/simantics/databoard/method/Interface.java|Interface.java]] \r
+*[[svn:foundation/databoard/trunk/org.simantics.databoard/src/org/simantics/databoard/method/MethodTypeDefinition.java|MethodTypeDefinition.java]]\r
+*[[svn:foundation/databoard/trunk/org.simantics.databoard/src/org/simantics/databoard/method/MethodType.java|MethodType.java]]\r
+\r
+In java InterfaceType description can be created with one of the following methods:\r
+* Implementing InterfaceType\r
+* Reading an Java Interface Class using reflection\r
+ Interface it = new Interface( ... methodDefinitions );\r
+ Interface it = getInterface( MyInterface.class );\r
+\r
+[[svn:foundation/databoard/trunk/org.simantics.databoard/src/org/simantics/databoard/method/MethodInterface.java|MethodInterface.java]] is a binding of an\r
+Java Instance and an Interface Type. It decouples the method invocation from the object.\r
+\r
+MethodInterface can be created with the following methods:\r
+* Implementation\r
+* Reflection\r
+ MethodInterface mi = new MethodInterface() {...}\r
+ MethodInterface mi = Datatypes.bindInterface( MyInterface.class, myObject );\r
+\r
+Utilities <code>Datatypes.createProxy()</code> and <code>Datatypes.bindInterface()</code> adapt between MethodInterface and Java Instance.\r
+ MethodInterface mi = Datatypes.bindInterface( MyInterface.class, myObject );\r
+ MyInterface myObject = Datatypes.createProxy( MyInterface.class, mi );\r
+\r
+==Remote Procedure Call==\r
+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. \r
+ Server myServer = new Server(8192, mi);\r
+ MethodInterface mi = new Client("localhost", 8192);\r
+\r
+MethodInterface with Server and Client together forms a Remote Procedure Call (RPC) mechanism.\r
+ public interface MyInterface { String helloWorld(String msg); }\r
+ \r
+ [Server]\r
+ MethodInterface mi = Methods.bindInterface( MyInterface.class, myObject );\r
+ Server myServer = new Server(8192, mi);\r
+ \r
+ [Client]\r
+ MethodInterface mi = new Client("localhost", 8192);\r
+ MyInterface myObject = Methods.createProxy( MyInterface.class, mi );\r
+\r
+[[Category: Data management & Experiment Control]]\r
Code Review / simantics / platform.git / blobdiff