bundles/org.simantics.databoard/src-isv/doc/accessor.mediawiki

   1 =Accessors=\r
   2 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
   3 \r
   4 '''[../javadoc/org/simantics/databoard/accessor.html|org.simantics.databoard.accessor] interfaces'''.\r
   5 {| style="background-color: #e9e9e9; border: 1px solid #aaaaaa; "\r
   6 | '''Class'''\r
   7 | '''Description'''\r
   8 |- style="background-color: #f9f9f9; " |\r
   9 | [../javadoc/org/simantics/databoard/accessor/Accessor.html|Accessor]\r
  10 | Base class for all data Accessors\r
  11 |- style="background-color: #f9f9f9; " |\r
  12 | [../javadoc/org/simantics/databoard/accessor/RecordAccessor.html|RecordAccessor]\r
  13 | Record \r
  14 |- style="background-color: #f9f9f9; " |\r
  15 | [../javadoc/org/simantics/databoard/accessor/ArrayAccessor.html|ArrayAccessor]\r
  16 | Array - an ordered sequence of elements of one value.\r
  17 |- style="background-color: #f9f9f9; " |\r
  18 | [../javadoc/org/simantics/databoard/accessor/MapAccessor.html|MapAccessor]\r
  19 | Map - an ''ordered'' map of keys to values. \r
  20 |- style="background-color: #f9f9f9; " |\r
  21 | [../javadoc/org/simantics/databoard/accessor/UnionAccessor.html|UnionAccessor]\r
  22 | Union\r
  23 |- style="background-color: #f9f9f9; " |\r
  24 | [../javadoc/org/simantics/databoard/accessor/BooleanAccessor.html|BooleanAccessor],[../javadoc/org/simantics/databoard/accessor/IntAccessor.html|IntAccessor],[../javadoc/org/simantics/databoard/accessor/LongAccessor.html|LongAccessor],[../javadoc/org/simantics/databoard/accessor/FloatAccessor.html|FloatAccessor],[../javadoc/org/simantics/databoard/accessor/DoubleAccessor.html|DoubleAccessor]\r
  25 | Primitive and numeric Accessors\r
  26 |- style="background-color: #f9f9f9; " |\r
  27 | [../javadoc/org/simantics/databoard/accessor/StringAccessor.html|StringAccessor]\r
  28 | String \r
  29 |- style="background-color: #f9f9f9; " |\r
  30 | [../javadoc/org/simantics/databoard/accessor/OptionalAccessor.html|OptionalAccessor]\r
  31 | Optional value\r
  32 |- style="background-color: #f9f9f9; " |\r
  33 | [../javadoc/org/simantics/databoard/accessor/VariantAccessor.html|VariantAccessor]\r
  34 | Variant value\r
  35 |}\r
  36 \r
  37 [../javadoc/org/simantics/databoard/Accessors.html|Accessors] and [../javadoc/org/simantics/databoard/Files.html|Files] are facade classes that contains utilities for instantiating and handling Accessors.\r
  38 \r
  39 <code>[../javadoc/org/simantics/databoard/accessor/binary/index.html|Binary Accessor]</code> is an access to a value in binary format (<tt>byte[]</tt> or <tt>ByteBuffer</tt>).\r
  40 \r
  41 '''Example:''' Binary accessor\r
  42 <pre class="code">\r
  43 Datatype type = Datatypes.getDatatype( Rectangle2D.Double.class );\r
  44 Binding binding = Bindings.getBinding( Rectangle2D.Double.class );\r
  45 Serializer s = Binding.getSerializer( binding );\r
  46 \r
  47 // Serialize rectangle\r
  48 Rectangle2D rect = new Rectangle2D.Double(0,0, 10, 10);\r
  49 byte[] data = s.serialize(rect);\r
  50 \r
  51 // Open accessor to byte data and modify first field in the byte data\r
  52 RecordAccessor ra = Accessors.getAccessor(data, type);\r
  53 ra.setFieldValue(0, Bindings.DOUBLE, 5.0);\r
  54 \r
  55 // Deserialize values from the byte data back to the rectangle object\r
  56 s.deserialize(data, rect);\r
  57 System.out.println(rect.getX());\r
  58 </pre>\r
  59 \r
  60 '''Example:''' File accessor, create\r
  61 <pre class="code">\r
  62 RecordType type = Datatypes.getDatatype( Rectangle2D.Double.class );\r
  63 // Create a new file and initialize it with rectangle type, and open file accessor\r
  64 FileRecordAccessor fa = Accessors.createFile( file, type );\r
  65 \r
  66 // Write the first field (x)\r
  67 fa.setFieldValue(0, Bindings.DOUBLE, 5.0);\r
  68 fa.close();\r
  69 </pre>\r
  70 \r
  71 '''Example:''' File accessor, open\r
  72 <pre class="code">\r
  73 // Open an accessor to an existing binary file\r
  74 FileVariantAccessor fa = Accessors.openAccessor(file);\r
  75 RecordAccessor ra = fa.getContentAccessor();\r
  76 \r
  77 // Read the first field (x)\r
  78 Double x = (Double) ra.getFieldValue(0, Bindings.DOUBLE);\r
  79 fa.close();\r
  80 </pre>\r
  81 \r
  82 '''Example:''' Java Accessor\r
  83 <pre class="code">\r
  84 Binding binding = Bindings.getBinding(Rectangle2D.Double.class);\r
  85 Rectangle2D rect = new Rectangle2D.Double(0,0, 10, 10);\r
  86 \r
  87 // Open accessor to rectangle\r
  88 RecordAccessor ra = Accessors.getAccessor(binding, rect);\r
  89 \r
  90 // Set rectangle's first field (x) to 5.0\r
  91 ra.setFieldValue(0, Bindings.DOUBLE, 5.0);\r
  92 System.out.println( rect.getX() );\r
  93 </pre>\r
  94 \r
  95 \r
  96 ==Accessor Reference==\r
  97 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
  98 <pre class="code">\r
  99     ChildReference ref = ChildReference.compile(\r
 100       new NameReference("node"),\r
 101       new ComponentReference()\r
 102     );\r
 103     Accessor child = accessor.getComponent( ref );\r
 104 \r
 105     ChildReference ref = ChildReference.compile(\r
 106        new LabelReference("node"),\r
 107        new LabelReference("v")\r
 108     );\r
 109     Accessor child = accessor.getComponent( ref );\r
 110 \r
 111     ChildReference ref = ChildReference.create("n-node/v");\r
 112     Accessor child = accessor.getComponent( ref );\r
 113 \r
 114     ChildReference ref = ChildReference.create("node/v");\r
 115     Accessor child = accessor.getComponent( ref );\r
 116 \r
 117     VariantAccessor va = recordAccessor.getFieldAccessor("node");\r
 118     Accessor child = va.getValueAccessor();\r
 119 </pre>\r
 120 \r
 121 ==Listening mechanism==\r
 122 Accessor offers a monitoring mechanism for the data model. \r
 123 There is an <code>[../javadoc/org/simantics/databoard/accessor/interestset/InterestSet.html|InterestSet]</code> that is a description of a sub-tree that is to be monitored of the data model.\r
 124 <code>[../javadoc/org/simantics/databoard/accessor/event/Event.html|Events]</code> are objects that spawned on changes to the data model. Each event object is annotated with [../javadoc/org/simantics/databoard/accessor/reference/index.html|reference path] that is in relation to the node where the listener was placed.\r
 125 \r
 126 Accessor Listeners use [EventThread Pattern] pattern.\r