View source for Databoard Developer Manual

<center>'''Databoard 0.6.0 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();

=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

Binding can be implemeted by user or a reflection based binding can be acquired using a utility function. Reflection binding is about 50% slower than handwritten one. To write a binding self, sub-class one of the 13 abstract binding classes (There is a base binding class for each Datatype). To acquire automatic binding, use this tool:

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.

'''[[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 is read automatically from a Class.'''
    Datatype type = Datatypes.getDatatype( Foo.class );
    Binding binding = Bindings.getBinding( Foo.class );

Bindings for generics classes can be created by passing argumenst
   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 equivalent to    
    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 equal to type
    type Cars = | Ferrari | Porche | Lamborghini | Jaguar

If you cannot modify your class, you have to create binding yourself 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;

== 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>GenericBindingScheme</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>GenericBinding.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 = binding.serializer();
    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]].
*<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.add( "temp", 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 - never reinstantiated.
    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 extends Node {
        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=
[[svn:foundation/databoard/trunk/org.simantics.databoard/src/org/simantics/databoard/accessor/|Accessor]] is an interface for partial reading, writing and monitoring of a data value. The value can concretely be located as memory byte[], on file, or as Java Object. The data is preseted in a tree model of Databoard type system. All but rccessors do not support referable records are supported (=no recursion).

'''[[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/DataAccessor.java|DataAccessor]]
| 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]] is a facade class 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 Accessor implementation that stores values in a Databoard binary format. The back-end can be bound to file or memory (<tt>byte[]</tt> or <tt>ByteBuffer</tt>).

To create a new file based store and acquire an accessor to it, use:
    RecordType type = Datatypes.getDatatype( Rectangle2D.Double.class );
    FileRecordAccessor file = Accessors.createFile( file, type );

Open an accessor to a binary file, use:
    FileVariantAccessor fa = Accessors.openFile( file );
    FileRecordAccessor ra = fa.getValueAccessor();

<code>[[svn:foundation/databoard/trunk/org.simantics.databoard/src/org/simantics/databoard/accessor/java/|Java Accessor]]</code> is an Accessor implementation that Java Instances as Databoard Data Model. The implementation requires a Binding. To access a Java Object as Accessor, use:
    RecordAccessor ra = Accessors.getAccessor( binding, instance );

Example, writes rectangle to file. Closes it. Opens and reads a single field. 
  Binding binding = Bindings.getBinding( Rectangle2D.Double.class );
  Files.createFile(file, binding, new Rectangle2D.Double(5, 5, 15, 25));
  
  FileVariantAccessor fa = Accessors.openAccessor(file);
  RecordAccessor ra = fa.getContentAccessor();
  System.out.println( ra.getFieldValue(2, Bindings.DOUBLE) );
  fa.close();


==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. 
 AccessorReference ref = AccessorReference.compile(
     new FieldNameReference("node"),
     new VariantValueReference()
 );
 Accessor child = accessor.getAccessor( ref );

 AccessorReference ref = AccessorReference.compile(
     new LabelReference("node"),
     new LabelReference("v")
 );
 Accessor child = accessor.getAccessor( ref );

 AccessorReference ref = AccessorReference.create("n-node/v");
 Accessor child = accessor.getAccessor( ref );

 AccessorReference ref = AccessorReference.create("node/v");
 Accessor child = accessor.getAccessor( 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.

==Example==

There is a data system with the following structure. The structure is presented with Databoard type notation (the text and tree representations below).
  type Node = {
         id : String;
         displayNames : LocalizedTexts;
         children : Node[];
         value : Optional(Variant);
       }

[[Image:NodeType.png]]




An instance of Node resides in the data system in proprietary format. It is accessible with an Databoard accessor.
The tree and the type structure follows the given type representation (text and tree representations below).
  root : Node = {
           id = “PI_01”
           displayNames = map{ “en” = “Instrument “ }
           children = 
            [ 
              {id=”Child”, 
               displayNames = map{ “en” = “Child”} },
               value = 5 : Integer
              }
            ]
           value = “<root>” : String
         }

[[Image:NodeInstance.png]]

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