bundles/org.simantics.databoard/src/org/simantics/databoard/accessor/MapAccessor.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;
  13
  14 import java.util.Map;
  15
  16 import org.simantics.databoard.accessor.error.AccessorConstructionException;
  17 import org.simantics.databoard.accessor.error.AccessorException;
  18 import org.simantics.databoard.accessor.impl.MapAccessorIterator;
  19 import org.simantics.databoard.binding.ArrayBinding;
  20 import org.simantics.databoard.binding.Binding;
  21 import org.simantics.databoard.binding.error.BindingException;
  22 import org.simantics.databoard.type.MapType;
  23
  24 /**
  25  * Map accessor is an interface to value container of map type
  26  *
  27  * @see MapAccessorIterator iterator helper class
  28  * @author Toni Kalajainen <toni.kalajainen@vtt.fi>
  29  */
  30 public interface MapAccessor extends Accessor {
  31
  32         /**
  33          * Get the number of elements in the map
  34          * @return size
  35          * @throws AccessorException
  36          */
  37         int size() throws AccessorException;
  38
  39         /**
  40          * Get the value that is specified for a key
  41          *
  42          * @param keyBinding
  43          * @param key
  44          * @param valueBinding
  45          * @return the value or <code>null</code>
  46          * @throws AccessorException
  47          */
  48         Object get(Binding keyBinding, Object key, Binding valueBinding) throws AccessorException;
  49
  50         /**
  51          * Returns true if map has a value for specified key
  52          *
  53          * @param keyBinding
  54          * @param key
  55          * @return true if entry exists
  56          * @throws AccessorException
  57          */
  58         boolean containsKey(Binding keyBinding, Object key) throws AccessorException;
  59
  60         /**
  61          * Returns true if map has a value for one or multiple keys
  62          *
  63          * @param valueBinding
  64          * @param value
  65          * @return true if value exists
  66          * @throws AccessorException
  67          */
  68         boolean containsValue(Binding valueBinding, Object value) throws AccessorException;
  69
  70         /**
  71          * Set & copy all entries from a Map Value.
  72          *
  73          * If entries are removed and they have accessors, the accessors are invalidated.
  74          *
  75          * @param mapBinding
  76          * @param newMap
  77          * @throws BindingException binding error
  78          * @throws UnsupportedOperationException cannot set a new value
  79          */
  80         void setValue(Binding mapBinding, Object newMap) throws AccessorException;
  81
  82
  83         /**
  84          * Put an entry to the map. If previous entry exists for the key, it is removed.
  85          *
  86          * @param keyBinding
  87          * @param key
  88          * @param valueBinding
  89          * @param value
  90          * @throws AccessorException
  91          */
  92         void put(Binding keyBinding, Object key, Binding valueBinding, Object value) throws AccessorException;
  93
  94         /**
  95          * Remove an entry.
  96          *
  97          * If there is an accessor, it becomes invalid.
  98          *
  99          * @param keyBinding
 100          * @param key
 101          * @throws AccessorException
 102          */
 103         void remove(Binding keyBinding, Object key) throws AccessorException;
 104
 105         /**
 106          * Remove all values between an two keys.
 107          *
 108          * If there is an existing accessor, it becomes invalid.
 109          *
 110          * @param keyBinding
 111          * @param startKey start key, inclusive
 112          * @param endKey end key, exclusive
 113          * @throws AccessorException
 114          */
 115 //      void removeRange(Binding keyBinding, Object startKey, Object endKey) throws AccessorException;
 116
 117         /**
 118          * Clear all entries.
 119          *
 120          * If there is an accessor to a removed container, it becomes invalid.
 121          *
 122          * @throws AccessorException
 123          */
 124         void clear() throws AccessorException;
 125
 126         /**
 127          * Put entries from a map. Replaces any possible existing entry.
 128          *
 129          * @param keyBinding
 130          * @param valueBinding
 131          * @param from
 132          * @throws AccessorException
 133          */
 134         void putAll(Binding keyBinding, Binding valueBinding, Map<Object, Object> from) throws AccessorException;
 135
 136         /**
 137          * Put entries from a map. Replaces any possible existing entry.
 138          *
 139          * @param keyBinding
 140          * @param valueBinding
 141          * @param keys
 142          * @param values
 143          * @throws AccessorException
 144          */
 145         void putAll(Binding keyBinding, Binding valueBinding, Object[] keys, Object[] values) throws AccessorException;
 146
 147         /**
 148          * Get all entries, write to a Java Collection
 149          *
 150          * @param keyBinding
 151          * @param valueBinding
 152          * @param to
 153          * @throws AccessorException
 154          */
 155         void getAll(Binding keyBinding, Binding valueBinding, Map<Object, Object> to) throws AccessorException;
 156
 157         /**
 158          * Get all entries in order, write to 2 arrays.
 159          *
 160          * @param keyBinding
 161          * @param valueBinding
 162          * @param keys
 163          * @param values
 164          * @throws AccessorException
 165          */
 166         void getAll(Binding keyBinding, Binding valueBinding, Object[] keys, Object[] values) throws AccessorException;
 167
 168         /**
 169          * Count the number of entries between two keyes
 170          * @param keyBinding
 171          * @param from
 172      * @param fromInclusive
 173          * @param end
 174      * @param endInclusive
 175      * @return number of entries in range
 176          * @throws AccessorException
 177          */
 178         int count(Binding keyBinding, Object from, boolean fromInclusive, Object end, boolean endInclusive) throws AccessorException;
 179
 180         /**
 181          * Read a range of entries
 182          *
 183          * @param keyBinding
 184          * @param from
 185          * @param fromInclusive
 186          * @param end
 187          * @param endInclusive
 188          * @param keyArrayBinding
 189          * @param keysArray
 190          * @param valueArrayBinding
 191          * @param valueArray
 192          * @param resultLimit maximum number of entries to read, -1 for no limit
 193          * @return the number of entries read
 194          * @throws AccessorException
 195          */
 196         int getEntries(Binding keyBinding, Object from, boolean fromInclusive, Object end, boolean endInclusive,
 197                         ArrayBinding keyArrayBinding, Object keysArray,
 198                         ArrayBinding valueArrayBinding, Object valueArray,
 199                         int resultLimit) throws AccessorException;
 200
 201         /**
 202          * Get all keys in order
 203          *
 204          * @param keyBinding
 205          * @return an array or keys
 206          * @throws AccessorException
 207          */
 208         Object[] getKeys(Binding keyBinding) throws AccessorException;
 209
 210         /**
 211          * Get all values
 212          *
 213          * @param valueBinding
 214          * @return an array of values
 215          * @throws AccessorException
 216          */
 217         Object[] getValues(Binding valueBinding) throws AccessorException;
 218
 219         /**
 220          * Get an accessor to a value. It becomes invalid if the entry is
 221          * removed or overwritten with a new value.
 222          *
 223          * @param keyBinding
 224          * @param key
 225          * @return value accessor
 226          * @throws AccessorConstructionException
 227          */
 228         <T extends Accessor> T getValueAccessor(Binding keyBinding, Object key) throws AccessorConstructionException;
 229
 230         MapType type();
 231
 232         Object getFirstKey(Binding keyBinding) throws AccessorException;
 233         Object getLastKey(Binding keyBinding) throws AccessorException;
 234         Object getLowerKey(Binding keyBinding, Object key) throws AccessorException;
 235         Object getFloorKey(Binding keyBinding, Object key) throws AccessorException;
 236         Object getCeilingKey(Binding keyBinding, Object key) throws AccessorException;
 237         Object getHigherKey(Binding keyBinding, Object key) throws AccessorException;
 238
 239 }
 240