bundles/org.simantics.databoard/src/org/simantics/databoard/accessor/ArrayAccessor.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.Collection;
  15
  16 import org.simantics.databoard.accessor.error.AccessorConstructionException;
  17 import org.simantics.databoard.accessor.error.AccessorException;
  18 import org.simantics.databoard.binding.Binding;
  19 import org.simantics.databoard.binding.error.BindingException;
  20 import org.simantics.databoard.type.ArrayType;
  21
  22 public interface ArrayAccessor extends Accessor {
  23
  24         /**
  25          * Add a new value.
  26          *
  27          * @param binding
  28          * @param value value
  29          * @throws AccessorException
  30          */
  31         void add(Binding binding, Object value) throws AccessorException;
  32
  33         /**
  34          * Add an array of elements.
  35          *
  36          * @param binding
  37          * @param values value
  38          * @throws AccessorException
  39          */
  40         void addAll(Binding binding, Object[] values) throws AccessorException;
  41
  42         /**
  43          * Add an array of elements.
  44          *
  45          * If elements are inserted in the middle of the array, existing interest sets
  46          * are updated to reflect the new positions.
  47          *
  48          * @param index position to insert new value to
  49          * @param binding
  50          * @param values
  51          * @throws AccessorException
  52          */
  53         void addAll(int index, Binding binding, Object[] values) throws AccessorException;
  54
  55         /**
  56          * Insert a new value.
  57          *
  58          * If elements are inserted in the middle of the array, existing interest sets
  59          * are updated to reflect the new positions.
  60          *
  61          * @param index position to insert new value to
  62          * @param binding
  63          * @param value value
  64          * @throws AccessorException
  65          */
  66         void add(int index, Binding binding, Object value) throws AccessorException;
  67
  68         /**
  69          * Set all elements from an Array Value.
  70          *
  71          * If array becomes shorter and there are accessors to the removed elements,
  72          * the accessors are invalidated.
  73          *
  74          * @param binding
  75          * @param newValue
  76          * @throws BindingException binding error
  77          * @throws UnsupportedOperationException cannot set a new value
  78          */
  79         void setValue(Binding binding, Object newValue) throws AccessorException;
  80
  81         /**
  82          * Replace a value container with a new value.
  83          *
  84          * @param index
  85          * @param binding
  86          * @param value
  87          * @throws AccessorException
  88          */
  89         void set(int index, Binding binding, Object value) throws AccessorException;
  90
  91         /**
  92          * Remove an element at an index.
  93          *
  94          * If there are listeners to elements after the <code>index</code>, the
  95          * interest sets and accessor paths are updated and decreased.
  96          *
  97          * If there was an accessor, it becomes invalid.
  98          *
  99          * @param index
 100          * @param count
 101          * @throws AccessorException
 102          */
 103         void remove(int index, int count) throws AccessorException;
 104
 105         /**
 106          * Get an accessor to an element.
 107          * The accessor is invalidated if the element is removed from the array.
 108          * <p>
 109          * The accessor is not to the index, it is to the element. For instance, you get accessor X of [2]
 110          * then a new value is inserted before 2. The accessor now points to the element at [3].
 111          *
 112          * @param index
 113          * @return the accessor
 114          * @throws AccessorConstructionException
 115          */
 116         <T extends Accessor> T getAccessor(int index) throws AccessorConstructionException;
 117
 118         /**
 119          * Get a copy of the element
 120          *
 121          * @param index
 122          * @param valueBinding
 123          * @return the element
 124          * @throws AccessorException
 125          */
 126         Object get(int index, Binding valueBinding) throws AccessorException;
 127
 128         /**
 129          * Read the element to an object
 130          *
 131          * @param index
 132          * @param valueBinding
 133          * @param dest
 134          * @throws AccessorException
 135          */
 136         void get(int index, Binding valueBinding, Object dest) throws AccessorException;
 137
 138         /**
 139          * Get all elements and place them to an <code>array</code>.
 140          * Exception is thrown if Array length is too short.
 141          *
 142          * @param valueBinding
 143          * @param array
 144          * @throws AccessorException
 145          */
 146         void getAll(Binding valueBinding, Object[] array) throws AccessorException;
 147
 148         /**
 149          * Get all elements
 150          *
 151          * @param valueBinding
 152          * @param values
 153          * @throws AccessorException
 154          */
 155         void getAll(Binding valueBinding, Collection<Object> values) throws AccessorException;
 156
 157 //      /**
 158 //       * Get a partial array
 159 //       *
 160 //       * @param binding
 161 //       * @param index
 162 //       * @param count
 163 //       * @return array
 164 //       * @throws AccessorException
 165 //       */
 166 //      Object getPartial(ArrayBinding binding, int index, int count) throws AccessorException;
 167
 168         void setSize(int newSize) throws AccessorException;
 169
 170         /**
 171          * Return the number of elements in the array.
 172          *
 173          * @return the number of elements
 174          * @throws AccessorException
 175          */
 176         int size() throws AccessorException;
 177
 178         ArrayType type();
 179
 180         public interface CloseableArrayAccessor extends ArrayAccessor, CloseableAccessor {}
 181
 182 }
 183
 184