KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > bak > pcj > map > ByteKeyLongMap


1 /*
2  * Primitive Collections for Java.
3  * Copyright (C) 2002, 2003 Søren Bak
4  *
5  * This library is free software; you can redistribute it and/or
6  * modify it under the terms of the GNU Lesser General Public
7  * License as published by the Free Software Foundation; either
8  * version 2.1 of the License, or (at your option) any later version.
9  *
10  * This library is distributed in the hope that it will be useful,
11  * but WITHOUT ANY WARRANTY; without even the implied warranty of
12  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
13  * Lesser General Public License for more details.
14  *
15  * You should have received a copy of the GNU Lesser General Public
16  * License along with this library; if not, write to the Free Software
17  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
18  */
19 package bak.pcj.map;
20
21 import bak.pcj.LongCollection;
22 import bak.pcj.set.ByteSet;
23
24 /**
25  * This interface represents maps from byte values to long values.
26  * It is not possible to obtain a set of entries from primitive
27  * collections maps. Instead, an iterator over entries can be
28  * obtained. This removes a number of implementation constraints
29  * imposed by having to implement an entry interface.
30  *
31  * @see bak.pcj.map.ByteKeyLongMapIterator
32  * @see java.util.Map
33  *
34  * @author Søren Bak
35  * @version 1.1 2003/6/1
36  * @since 1.0
37  */
38 public interface ByteKeyLongMap {
39
40     /**
41      * Clears this map.
42      *
43      * @throws UnsupportedOperationException
44      * if the operation is not supported by this map.
45      */
46     void clear();
47
48     /**
49      * Indicates whether this map contains a mapping from a specified
50      * key. If the key is contained in this map, a succeeding call
51      * to {@link #lget() lget()} will return the corresponding value.
52      *
53      * @param key
54      * the key to test for.
55      *
56      * @return <tt>true</tt> if this map contains a mapping from
57      * the specified key; returns <tt>false</tt>
58      * otherwise.
59      *
60      * @see #lget()
61      */
62     boolean containsKey(byte key);
63
64     /**
65      * Indicates whether this map contains a mapping to a specified
66      * value.
67      *
68      * @param value
69      * the value to test for.
70      *
71      * @return <tt>true</tt> if this map contains at least one
72      * mapping to the specified value; returns
73      * <tt>false</tt> otherwise.
74      */
75     boolean containsValue(long value);
76
77     /**
78      * Returns an iterator over the entries of this map. It is
79      * possible to remove entries from this map using the iterator
80      * provided that the concrete map supports removal of
81      * entries.
82      *
83      * @return an iterator over the entries of this map.
84      */
85     ByteKeyLongMapIterator entries();
86
87     /**
88      * Indicates whether this map is equal to some object.
89      *
90      * @param obj
91      * the object with which to compare this map.
92      *
93      * @return <tt>true</tt> if this map is equal to the
94      * specified object; returns <tt>false</tt>
95      * otherwise.
96      */
97     boolean equals(Object JavaDoc obj);
98
99     /**
100      * Maps a specified key to a value. Returns a default value as
101      * specified by the <tt>MapDefaults</tt> class if no mapping
102      * exists for the specified key.
103      *
104      * @param key
105      * the key to map to a value.
106      *
107      * @return the value that the specified key maps to, or
108      * a default value, if no such mapping exists.
109      *
110      * @see MapDefaults
111      * @see #tget(byte)
112      * @see #lget()
113      */
114     long get(byte key);
115
116     /**
117      * Returns a hash code value for this map.
118      *
119      * @return a hash code value for this map.
120      */
121     int hashCode();
122
123     /**
124      * Indicates whether this map is empty.
125      *
126      * @return <tt>true</tt> if this map is empty; returns
127      * <tt>false</tt> otherwise.
128      */
129     boolean isEmpty();
130
131     /**
132      * Returns a set view of the keys of this map. Removals from the
133      * returned set removes the corresponding entries in this map.
134      * Changes to the map are reflected in the set.
135      *
136      * @return a set view of the keys of this map.
137      */
138     ByteSet keySet();
139
140     /**
141      * Returns the last value corresponding to a positive result
142      * from {@link #containsKey(byte) containsKey(byte)}. This is useful
143      * for checking checking the existence of a mapping while
144      * avoiding two lookups on the same key.
145      *
146      * @return the value corresponding to the key from the
147      * last invokation of
148      * {@link #containsKey(byte) containsKey(byte)}.
149      *
150      * @throws IllegalStateException
151      * if {@link #containsKey(byte) containsKey(byte)} has
152      * not been called or the last call resulted in
153      * a return value of <tt>false</tt>.
154      *
155      * @see #get(byte)
156      * @see #tget(byte)
157      * @see #containsKey(byte)
158      */
159     long lget();
160
161     /**
162      * Adds a mapping from a specified key to a specified value to
163      * this map. If a mapping already exists for the specified key
164      * it is overwritten by the new mapping.
165      *
166      * @param key
167      * the key of the mapping to add to this map.
168      *
169      * @param value
170      * the value of the mapping to add to this map.
171      *
172      * @return the old value if a
173      * mapping from the specified key already existed
174      * in this map; otherwise returns a default value as
175      * specified by the <tt>MapDefaults</tt> class.
176      *
177      * @throws UnsupportedOperationException
178      * if the operation is not supported by this map.
179      *
180      * @see MapDefaults
181      */
182     long put(byte key, long value);
183
184     /**
185      * Adds all mappings from a specified map to this map. Any
186      * existing mappings whose keys collide with a new mapping is
187      * overwritten by the new mapping.
188      *
189      * @param map
190      * the map whose mappings to add to this map.
191      *
192      * @throws NullPointerException
193      * if <tt>map</tt> is <tt>null</tt>.
194      *
195      * @throws UnsupportedOperationException
196      * if the operation is not supported by this map.
197      */
198     void putAll(ByteKeyLongMap map);
199
200     /**
201      * Removes the mapping from a specified key from this map.
202      *
203      * @param key
204      * the key whose mapping to remove from this map.
205      *
206      * @return the old value if a
207      * mapping from the specified key already existed
208      * in this map; otherwise returns a default value as
209      * specified by the <tt>MapDefaults</tt> class.
210      *
211      * @throws UnsupportedOperationException
212      * if the operation is not supported by this map.
213      *
214      * @see MapDefaults
215      */
216     long remove(byte key);
217
218     /**
219      * Returns the size of this map. The size is defined as the
220      * number of mappings from keys to values.
221      *
222      * @return the size of this map.
223      */
224     int size();
225
226     /**
227      * Maps a specified key to a value. This method should be used
228      * when the key is known to be in the map.
229      *
230      * @param key
231      * the key to map to a value.
232      *
233      * @return the value that the specified key maps to.
234      *
235      * @throws NoSuchMappingException
236      * if the specified key does not map to any value.
237      *
238      * @see #get(byte)
239      * @see #lget()
240      */
241     long tget(byte key);
242
243     /**
244      * Minimizes the memory used by this map. The exact
245      * operation of this method depends on the class implementing it.
246      * Implementors may choose to ignore it completely.
247      */
248     void trimToSize();
249
250     /**
251      * Returns a collection view of the values in this map. The
252      * collection is not modifiable, but changes to the map are
253      * reflected in the collection.
254      *
255      * @return a collection view of the values in this map.
256      */
257     LongCollection values();
258
259 }
Popular Tags