1 /*******************************************************************************
\r
2 * Copyright (c) 2010 Association for Decentralized Information Management in
\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
10 * VTT Technical Research Centre of Finland - initial API and implementation
\r
11 *******************************************************************************/
\r
12 package org.simantics.databoard.accessor;
14 import java.util.Map;
\r
16 import org.simantics.databoard.accessor.error.AccessorConstructionException;
\r
17 import org.simantics.databoard.accessor.error.AccessorException;
\r
18 import org.simantics.databoard.accessor.impl.MapAccessorIterator;
\r
19 import org.simantics.databoard.binding.ArrayBinding;
\r
20 import org.simantics.databoard.binding.Binding;
\r
21 import org.simantics.databoard.binding.error.BindingException;
\r
22 import org.simantics.databoard.type.MapType;
\r
25 * Map accessor is an interface to value container of map type
\r
27 * @see MapAccessorIterator iterator helper class
\r
28 * @author Toni Kalajainen <toni.kalajainen@vtt.fi>
\r
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.
\r
108 * If there is an existing accessor, it becomes invalid.
\r
110 * @param keyBinding
\r
111 * @param startKey start key, inclusive
\r
112 * @param endKey end key, exclusive
\r
113 * @throws AccessorException
\r
115 // void removeRange(Binding keyBinding, Object startKey, Object endKey) throws AccessorException;
\r
118 * Clear all entries.
\r
120 * If there is an accessor to a removed container, it becomes invalid.
\r
122 * @throws AccessorException
\r
124 void clear() throws AccessorException;
\r
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
\r
170 * @param keyBinding
\r
172 * @param fromInclusive
\r
174 * @param endInclusive
\r
175 * @return number of entries in range
\r
176 * @throws AccessorException
\r
178 int count(Binding keyBinding, Object from, boolean fromInclusive, Object end, boolean endInclusive) throws AccessorException;
\r
181 * Read a range of entries
\r
183 * @param keyBinding
\r
185 * @param fromInclusive
\r
187 * @param endInclusive
\r
188 * @param keyArrayBinding
\r
190 * @param valueArrayBinding
\r
191 * @param valueArray
\r
192 * @param resultLimit maximum number of entries to read, -1 for no limit
\r
193 * @return the number of entries read
\r
194 * @throws AccessorException
\r
196 int getEntries(Binding keyBinding, Object from, boolean fromInclusive, Object end, boolean endInclusive,
\r
197 ArrayBinding keyArrayBinding, Object keysArray,
\r
198 ArrayBinding valueArrayBinding, Object valueArray,
\r
199 int resultLimit) throws AccessorException;
\r
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;
\r
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;