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

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