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