|
|||||||||||||||||||
Source file | Conditionals | Statements | Methods | TOTAL | |||||||||||||||
MapIterator.java | - | - | - | - |
|
1 | package org.drools.util; | |
2 | /* | |
3 | * Copyright 2003-2004 The Apache Software Foundation | |
4 | * | |
5 | * Licensed under the Apache License, Version 2.0 (the "License"); | |
6 | * you may not use this file except in compliance with the License. | |
7 | * You may obtain a copy of the License at | |
8 | * | |
9 | * http://www.apache.org/licenses/LICENSE-2.0 | |
10 | * | |
11 | * Unless required by applicable law or agreed to in writing, software | |
12 | * distributed under the License is distributed on an "AS IS" BASIS, | |
13 | * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. | |
14 | * See the License for the specific language governing permissions and | |
15 | * limitations under the License. | |
16 | */ | |
17 | ||
18 | import java.util.Iterator; | |
19 | ||
20 | /** | |
21 | * Defines an iterator that operates over a <code>Map</code>. | |
22 | * <p> | |
23 | * This iterator is a special version designed for maps. It can be more | |
24 | * efficient to use this rather than an entry set iterator where the option is | |
25 | * available, and it is certainly more convenient. | |
26 | * <p> | |
27 | * A map that provides this interface may not hold the data internally using Map | |
28 | * Entry objects, thus this interface can avoid lots of object creation. | |
29 | * <p> | |
30 | * In use, this iterator iterates through the keys in the map. After each call | |
31 | * to <code>next()</code>, the <code>getValue()</code> method provides | |
32 | * direct access to the value. The value can also be set using | |
33 | * <code>setValue()</code>. | |
34 | * | |
35 | * <pre> | |
36 | * MapIterator it = map.mapIterator( ); | |
37 | * while ( it.hasNext( ) ) | |
38 | * { | |
39 | * Object key = it.next( ); | |
40 | * Object value = it.getValue( ); | |
41 | * it.setValue( newValue ); | |
42 | * } | |
43 | * </pre> | |
44 | * | |
45 | * @since Commons Collections 3.0 | |
46 | * @version $Revision: 1.3 $ $Date: 2004/12/06 01:30:38 $ | |
47 | * | |
48 | * @author Stephen Colebourne | |
49 | */ | |
50 | public interface MapIterator | |
51 | extends | |
52 | Iterator | |
53 | { | |
54 | ||
55 | /** | |
56 | * Checks to see if there are more entries still to be iterated. | |
57 | * | |
58 | * @return <code>true</code> if the iterator has more elements | |
59 | */ | |
60 | boolean hasNext(); | |
61 | ||
62 | /** | |
63 | * Gets the next <em>key</em> from the <code>Map</code>. | |
64 | * | |
65 | * @return the next key in the iteration | |
66 | * @throws java.util.NoSuchElementException | |
67 | * if the iteration is finished | |
68 | */ | |
69 | Object next(); | |
70 | ||
71 | // ----------------------------------------------------------------------- | |
72 | /** | |
73 | * Gets the current key, which is the key returned by the last call to | |
74 | * <code>next()</code>. | |
75 | * | |
76 | * @return the current key | |
77 | * @throws IllegalStateException | |
78 | * if <code>next()</code> has not yet been called | |
79 | */ | |
80 | Object getKey(); | |
81 | ||
82 | /** | |
83 | * Gets the current value, which is the value associated with the last key | |
84 | * returned by <code>next()</code>. | |
85 | * | |
86 | * @return the current value | |
87 | * @throws IllegalStateException | |
88 | * if <code>next()</code> has not yet been called | |
89 | */ | |
90 | Object getValue(); | |
91 | ||
92 | // ----------------------------------------------------------------------- | |
93 | /** | |
94 | * Removes the last returned key from the underlying <code>Map</code> | |
95 | * (optional operation). | |
96 | * <p> | |
97 | * This method can be called once per call to <code>next()</code>. | |
98 | * | |
99 | * @throws UnsupportedOperationException | |
100 | * if remove is not supported by the map | |
101 | * @throws IllegalStateException | |
102 | * if <code>next()</code> has not yet been called | |
103 | * @throws IllegalStateException | |
104 | * if <code>remove()</code> has already been called since the | |
105 | * last call to <code>next()</code> | |
106 | */ | |
107 | void remove(); | |
108 | ||
109 | /** | |
110 | * Sets the value associated with the current key (optional operation). | |
111 | * | |
112 | * @param value | |
113 | * the new value | |
114 | * @return the previous value | |
115 | * @throws UnsupportedOperationException | |
116 | * if setValue is not supported by the map | |
117 | * @throws IllegalStateException | |
118 | * if <code>next()</code> has not yet been called | |
119 | * @throws IllegalStateException | |
120 | * if <code>remove()</code> has been called since the last | |
121 | * call to <code>next()</code> | |
122 | */ | |
123 | Object setValue(Object value); | |
124 | ||
125 | } |
|