bundles/org.simantics.databoard/src/org/simantics/databoard/accessor/wire/IWireServer.java

   1 /*******************************************************************************\r
   2  * Copyright (c) 2010- Association for Decentralized Information Management in\r
   3  * Industry THTH ry.\r
   4  * All rights reserved. This program and the accompanying materials\r
   5  * are made available under the terms of the Eclipse Public License v1.0\r
   6  * which accompanies this distribution, and is available at\r
   7  * http://www.eclipse.org/legal/epl-v10.html\r
   8  * \r
   9  * Contributors:\r
  10  *    VTT Technical Research Centre of Finland - initial API and implementation\r
  11  *******************************************************************************/\r
  12 package org.simantics.databoard.accessor.wire;\r
  13 \r
  14 import java.util.LinkedList;\r
  15 \r
  16 import org.simantics.databoard.accessor.event.Event;\r
  17 import org.simantics.databoard.accessor.interestset.InterestSet;\r
  18 import org.simantics.databoard.accessor.reference.ChildReference;\r
  19 import org.simantics.databoard.annotations.Optional;\r
  20 import org.simantics.databoard.binding.mutable.MutableVariant;\r
  21 import org.simantics.databoard.type.Datatype;\r
  22 \r
  23 public interface IWireServer {\r
  24         \r
  25         /**\r
  26          * Open a handle to an accessor. \r
  27          * \r
  28          * @param ref accessor refence or <code>null<code> for root\r
  29          * @return accessor info\r
  30          * @throws WireException\r
  31          */\r
  32         AccessorInfo openAccessor(ChildReference ref) throws WireException;\r
  33         \r
  34         static class AccessorInfo {\r
  35                 public int accessorId;\r
  36                 public Datatype type;\r
  37         }\r
  38         \r
  39         /**\r
  40          * Close a group of accessor handles.\r
  41          * Open listener and lock handles are released.\r
  42          * \r
  43          * @param accIds accessor ids\r
  44          */\r
  45         int closeAccessors(Integer[] accIds) throws WireException;\r
  46         \r
  47         /**\r
  48          * Acquire mutual-exclusive write lock, and optionally read lock.\r
  49          * The lock covers the node and its sub-tree.\r
  50          * \r
  51          * Lock prevents access from other wire clients.\r
  52          * \r
  53          * @param accId\r
  54          * @param readLock\r
  55          * @param timeout in milliseconds, -1 = infinite\r
  56          * @return lockId, or -1 if failed \r
  57          */\r
  58 //      int requestLock(int accId, boolean readLock, long timeout)  throws WireException;\r
  59         \r
  60         /**\r
  61          * Release lock\r
  62          * \r
  63          * @param lockId\r
  64          */\r
  65 //      void releaseLock(int lockId);\r
  66 \r
  67         /**\r
  68          * Read the value as whole.\r
  69          * \r
  70          * If accessor is locked, read operation delays until lock\r
  71          * is released.\r
  72          * \r
  73          * @param accId\r
  74          * @return value\r
  75          * @throws WireException \r
  76          */\r
  77         MutableVariant getValue(int accId) throws WireException;\r
  78         \r
  79         /**\r
  80          * Apply a list of changes to the node.\r
  81          * \r
  82          * If rollback is true, a rollback log is returned.\r
  83          * Rollback log is a list of events that revert modifications\r
  84          * if applied.<p> \r
  85          * \r
  86          * In case of error rollback log is filled with\r
  87          * events that counter modification that were already applied\r
  88          * before the error occured.<p> \r
  89          * \r
  90          * @param accId\r
  91          * @param changeSet\r
  92          * @param rollback\r
  93          * @return apply result\r
  94          */\r
  95         ApplyResult apply(int accId, Event[] changeSet, boolean rollback);\r
  96         \r
  97         public static class ApplyResult {\r
  98                 public @Optional WireException error;\r
  99                 public @Optional LinkedList<Event> rollbackLog;\r
 100         }\r
 101 \r
 102         /**\r
 103          * Create listener \r
 104          * \r
 105          * @param accId\r
 106          * @param interestSet\r
 107          * @param pathPrefix\r
 108          * @return lisId\r
 109          * @throws WireException\r
 110          */\r
 111         int addListener(int accId, InterestSet interestSet, ChildReference pathPrefix) throws WireException;\r
 112         \r
 113         /**\r
 114          * Remove listener \r
 115          * \r
 116          * @param lisId\r
 117          * @throws WireException\r
 118          */\r
 119         int removeListener(int lisId) throws WireException;\r
 120         \r
 121         // Array, Map, Record, Union\r
 122         /**\r
 123          * Get size of an array, map, record or union\r
 124          * \r
 125          * @param accId\r
 126          * @throws WireException\r
 127          */\r
 128         int size(int accId) throws WireException;\r
 129         \r
 130         /**\r
 131          * Remove all array or map elements\r
 132          * \r
 133          * @param accId\r
 134          * @throws WireException\r
 135          */\r
 136         int clear(int accId) throws WireException;\r
 137 \r
 138         boolean containsKey(int accId, MutableVariant key) throws WireException;\r
 139         boolean containsValue(int accId, MutableVariant value) throws WireException;\r
 140         MutableVariant getFirstKey(int accId) throws WireException;\r
 141         MutableVariant getLastKey(int accId) throws WireException;\r
 142         MutableVariant getLowerKey(int accId, MutableVariant key) throws WireException;\r
 143         MutableVariant getFloorKey(int accId, MutableVariant key) throws WireException;\r
 144         MutableVariant getCeilingKey(int accId, MutableVariant key) throws WireException;\r
 145         MutableVariant getHigherKey(int accId, MutableVariant key) throws WireException;\r
 146 \r
 147         /**\r
 148          * Get map entry value\r
 149          *  \r
 150          * @param accId\r
 151          * @param key\r
 152          * @return value\r
 153          * @throws WireException\r
 154          */\r
 155         MutableVariant getMapValue(int accId, MutableVariant key) throws WireException;\r
 156         \r
 157         /**\r
 158          * Get map values as array\r
 159          * \r
 160          * @param accId\r
 161          * @return values in array inside a variant\r
 162          * @throws WireException\r
 163          */\r
 164         MutableVariant getMapValues(int accId) throws WireException;\r
 165         \r
 166         /**\r
 167          * Get map keys as array\r
 168          * \r
 169          * @param accId\r
 170          * @return keys in array inside a variant\r
 171          * @throws WireException\r
 172          */\r
 173         MutableVariant getMapKeys(int accId) throws WireException;\r
 174         \r
 175         // Optional\r
 176         /**\r
 177          * Get value status of an Optional node\r
 178          * \r
 179          * @param accId\r
 180          * @return <code>true</code> if there is value in the node \r
 181          * @throws WireException \r
 182          */\r
 183         boolean hasValue(int accId) throws WireException;\r
 184         \r
 185         // Union\r
 186         /**\r
 187          * Get tag index of a Union node\r
 188          * \r
 189          * @param accId\r
 190          * @return tag index\r
 191          * @throws WireException \r
 192          */\r
 193         int getTag(int accId) throws WireException;\r
 194         \r
 195         // Array\r
 196         \r
 197         /**\r
 198          * add objects to array\r
 199          * \r
 200          * @param accId\r
 201          * @param index insert pos, -1 = at the end\r
 202          * @param array\r
 203          * @return actual insert pos\r
 204          */\r
 205         int addAll(int accId, int index, MutableVariant array) throws WireException;\r
 206         \r
 207         /**\r
 208          * \r
 209          * @param accId\r
 210          * @param index insert pos, -1 = at the end\r
 211          * @param object\r
 212          * @return actual insert pos\r
 213          * @throws WireException\r
 214          */\r
 215         int add(int accId, int index, MutableVariant object) throws WireException;\r
 216         \r
 217         /**\r
 218          * Get array element value\r
 219          *  \r
 220          * @param accId\r
 221          * @param index\r
 222          * @return value\r
 223          * @throws WireException\r
 224          */\r
 225         MutableVariant getArrayElement(int accId, int index) throws WireException;      \r
 226         \r
 227 }\r
 228 \r