Databoard Developer Manual

Datatypes are parsed using Datatypes.DatatypeRepository.

    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();

A node is a recursive type. With databoard type system it could be stated as

  type Node = {
         id : String;
         displayNames : LocalizedTexts;
         children : Node[];
         value : Optional(Variant);
       }

A couple of instances with Databoard value notation:

  root : Node = {
           id = �PI_01�
           displayNames = map{ �en� = �Instrument � }
           children = 
            [ 
              {id=�Child�, 
               displayNames = map{ �en� = �Child�} },
               value = 5 : Integer
              }
            ]
           value = �<root>� : String
         }

'''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, e.g. RecordBinding.

'''Other exceptions:'''

• java.lang.Object is Variant

• java.lang.Set<T> is Map(T, {})

• java.lang.TreeSet<T></code> is Map(T, {})`

• java.lang.HashSet<T> is Map(T, {}). (Note HashSet binding has very low performance.)

• java.lang.Map<K, V> is Map(K, V).

• java.lang.TreeMap<K, V> is Map(K, V).

• java.lang.HashMap<K, V> is Map(K, V). (Note HashMap binding has very low performance.)

• java.lang.List<T> is Array(T).

• java.lang.ArrayList<T> is Array(T).

• java.lang.LinkedList<T> is Array(T).

• void is {}.

• The stack trace of Exception.class is omitted.

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.

DefaultBindingScheme is a scheme that converts any datatype to a binding. It prefers java.lang.X primitives. | Type | Class | | ---- | ----- | | BooleanType | Boolean.class | | ByteType | Byte.class | | FloatType | Float.class | | DoubleType | Double.class | | IntegerType | Integer.class | | LongType | Long.class | | StringType | String.class | | UnionType | TaggedObject.class | | OptionType | ValueContainer.class | | RecordType | Object[].class | | ArrayType | ArrayList.class | | Array(Byte) | byte[].class | | MapType | TreeMap.class | | VariantType | Variant.class |

MutableBindingScheme 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; " | | BooleanType | MutableBoolean.class |- style="background-color: #f9f9f9; " | | ByteType | MutableByte.class |- style="background-color: #f9f9f9; " | | FloatType | MutableFloat.class |- style="background-color: #f9f9f9; " | | DoubleType | MutableDouble.class |- style="background-color: #f9f9f9; " | | IntegerType | MutableInt.class |- style="background-color: #f9f9f9; " | | LongType | MutableLong.class |- style="background-color: #f9f9f9; " | | StringType | MutableString.class |- style="background-color: #f9f9f9; " | | UnionType | TaggedObject.class |- style="background-color: #f9f9f9; " | | OptionType | ValueContainer.class |- style="background-color: #f9f9f9; " | | RecordType | Object[].class |- style="background-color: #f9f9f9; " | | ArrayType | ArrayList.class |- style="background-color: #f9f9f9; " | | MapType | TreeMap.class |- style="background-color: #f9f9f9; " | | VariantType | Variant.class |}

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 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();

Accessor offers a monitoring mechanism for the data model. There is an [[svn:foundation/databoard/trunk/org.simantics.databoard/src/org/simantics/databoard/accessor/interestset/InterestSet.java|InterestSet]] that is a description of a sub-tree that is to be monitored of the data model. [[svn:foundation/databoard/trunk/org.simantics.databoard/src/org/simantics/databoard/accessor/event/Event.java|Events]] are objects that spawned on changes to the data model. Each event object is annotated with [] that is in relation to the node where the listener was placed.

Accessor Listeners use [] pattern.

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:

• []

• []

• []

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 );

[] 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 Datatypes.createProxy()</code> and <code>Datatypes.bindInterface() adapt between MethodInterface and Java Instance.

    MethodInterface mi   = Datatypes.bindInterface( MyInterface.class, myObject );
    MyInterface myObject = Datatypes.createProxy( MyInterface.class, mi );

Utilities [] and [] 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 );