1 /*******************************************************************************
2 * Copyright (c) 2010 Association for Decentralized Information Management in
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
10 * VTT Technical Research Centre of Finland - initial API and implementation
11 *******************************************************************************/
12 package org.simantics.databoard.accessor;
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;
25 * Map accessor is an interface to value container of map type
27 * @see MapAccessorIterator iterator helper class
28 * @author Toni Kalajainen <toni.kalajainen@vtt.fi>
30 public interface MapAccessor extends Accessor {
33 * Get the number of elements in the map
35 * @throws AccessorException
37 int size() throws AccessorException;
40 * Get the value that is specified for a key
45 * @return the value or <code>null</code>
46 * @throws AccessorException
48 Object get(Binding keyBinding, Object key, Binding valueBinding) throws AccessorException;
51 * Returns true if map has a value for specified key
55 * @return true if entry exists
56 * @throws AccessorException
58 boolean containsKey(Binding keyBinding, Object key) throws AccessorException;
61 * Returns true if map has a value for one or multiple keys
65 * @return true if value exists
66 * @throws AccessorException
68 boolean containsValue(Binding valueBinding, Object value) throws AccessorException;
71 * Set & copy all entries from a Map Value.
73 * If entries are removed and they have accessors, the accessors are invalidated.
77 * @throws BindingException binding error
78 * @throws UnsupportedOperationException cannot set a new value
80 void setValue(Binding mapBinding, Object newMap) throws AccessorException;
84 * Put an entry to the map. If previous entry exists for the key, it is removed.
90 * @throws AccessorException
92 void put(Binding keyBinding, Object key, Binding valueBinding, Object value) throws AccessorException;
97 * If there is an accessor, it becomes invalid.
101 * @throws AccessorException
103 void remove(Binding keyBinding, Object key) throws AccessorException;
106 * Remove all values between an two keys.
108 * If there is an existing accessor, it becomes invalid.
111 * @param startKey start key, inclusive
112 * @param endKey end key, exclusive
113 * @throws AccessorException
115 // void removeRange(Binding keyBinding, Object startKey, Object endKey) throws AccessorException;
120 * If there is an accessor to a removed container, it becomes invalid.
122 * @throws AccessorException
124 void clear() throws AccessorException;
127 * Put entries from a map. Replaces any possible existing entry.
130 * @param valueBinding
132 * @throws AccessorException
134 void putAll(Binding keyBinding, Binding valueBinding, Map<Object, Object> from) throws AccessorException;
137 * Put entries from a map. Replaces any possible existing entry.
140 * @param valueBinding
143 * @throws AccessorException
145 void putAll(Binding keyBinding, Binding valueBinding, Object[] keys, Object[] values) throws AccessorException;
148 * Get all entries, write to a Java Collection
151 * @param valueBinding
153 * @throws AccessorException
155 void getAll(Binding keyBinding, Binding valueBinding, Map<Object, Object> to) throws AccessorException;
158 * Get all entries in order, write to 2 arrays.
161 * @param valueBinding
164 * @throws AccessorException
166 void getAll(Binding keyBinding, Binding valueBinding, Object[] keys, Object[] values) throws AccessorException;
169 * Count the number of entries between two keyes
172 * @param fromInclusive
174 * @param endInclusive
175 * @return number of entries in range
176 * @throws AccessorException
178 int count(Binding keyBinding, Object from, boolean fromInclusive, Object end, boolean endInclusive) throws AccessorException;
181 * Read a range of entries
185 * @param fromInclusive
187 * @param endInclusive
188 * @param keyArrayBinding
190 * @param valueArrayBinding
192 * @param resultLimit maximum number of entries to read, -1 for no limit
193 * @return the number of entries read
194 * @throws AccessorException
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;
202 * Get all keys in order
205 * @return an array or keys
206 * @throws AccessorException
208 Object[] getKeys(Binding keyBinding) throws AccessorException;
213 * @param valueBinding
214 * @return an array of values
215 * @throws AccessorException
217 Object[] getValues(Binding valueBinding) throws AccessorException;
220 * Get an accessor to a value. It becomes invalid if the entry is
221 * removed or overwritten with a new value.
225 * @return value accessor
226 * @throws AccessorConstructionException
228 <T extends Accessor> T getValueAccessor(Binding keyBinding, Object key) throws AccessorConstructionException;
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;