KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > apache > commons > collections > map > LinkedMap


1 /*
2  * Copyright 2003-2004 The Apache Software Foundation
3  *
4  * Licensed under the Apache License, Version 2.0 (the "License");
5  * you may not use this file except in compliance with the License.
6  * You may obtain a copy of the License at
7  *
8  * http://www.apache.org/licenses/LICENSE-2.0
9  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS,
12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  * See the License for the specific language governing permissions and
14  * limitations under the License.
15  */
16 package org.apache.commons.collections.map;
17
18 import java.io.IOException JavaDoc;
19 import java.io.ObjectInputStream JavaDoc;
20 import java.io.ObjectOutputStream JavaDoc;
21 import java.io.Serializable JavaDoc;
22 import java.util.AbstractList JavaDoc;
23 import java.util.Collection JavaDoc;
24 import java.util.Iterator JavaDoc;
25 import java.util.List JavaDoc;
26 import java.util.ListIterator JavaDoc;
27 import java.util.Map JavaDoc;
28
29 import org.apache.commons.collections.iterators.UnmodifiableIterator;
30 import org.apache.commons.collections.iterators.UnmodifiableListIterator;
31 import org.apache.commons.collections.list.UnmodifiableList;
32
33 /**
34  * A <code>Map</code> implementation that maintains the order of the entries.
35  * In this implementation order is maintained by original insertion.
36  * <p>
37  * This implementation improves on the JDK1.4 LinkedHashMap by adding the
38  * {@link org.apache.commons.collections.MapIterator MapIterator}
39  * functionality, additional convenience methods and allowing
40  * bidirectional iteration. It also implements <code>OrderedMap</code>.
41  * In addition, non-interface methods are provided to access the map by index.
42  * <p>
43  * The <code>orderedMapIterator()</code> method provides direct access to a
44  * bidirectional iterator. The iterators from the other views can also be cast
45  * to <code>OrderedIterator</code> if required.
46  * <p>
47  * All the available iterators can be reset back to the start by casting to
48  * <code>ResettableIterator</code> and calling <code>reset()</code>.
49  * <p>
50  * The implementation is also designed to be subclassed, with lots of useful
51  * methods exposed.
52  *
53  * @since Commons Collections 3.0
54  * @version $Revision: 1.9 $ $Date: 2004/02/18 01:13:19 $
55  *
56  * @author Stephen Colebourne
57  */
58 public class LinkedMap
59         extends AbstractLinkedMap implements Serializable JavaDoc, Cloneable JavaDoc {
60
61     /** Serialisation version */
62     private static final long serialVersionUID = 9077234323521161066L;
63     
64     /**
65      * Constructs a new empty map with default size and load factor.
66      */
67     public LinkedMap() {
68         super(DEFAULT_CAPACITY, DEFAULT_LOAD_FACTOR, DEFAULT_THRESHOLD);
69     }
70
71     /**
72      * Constructs a new, empty map with the specified initial capacity.
73      *
74      * @param initialCapacity the initial capacity
75      * @throws IllegalArgumentException if the initial capacity is less than one
76      */
77     public LinkedMap(int initialCapacity) {
78         super(initialCapacity);
79     }
80
81     /**
82      * Constructs a new, empty map with the specified initial capacity and
83      * load factor.
84      *
85      * @param initialCapacity the initial capacity
86      * @param loadFactor the load factor
87      * @throws IllegalArgumentException if the initial capacity is less than one
88      * @throws IllegalArgumentException if the load factor is less than zero
89      */
90     public LinkedMap(int initialCapacity, float loadFactor) {
91         super(initialCapacity, loadFactor);
92     }
93
94     /**
95      * Constructor copying elements from another map.
96      *
97      * @param map the map to copy
98      * @throws NullPointerException if the map is null
99      */
100     public LinkedMap(Map JavaDoc map) {
101         super(map);
102     }
103
104     //-----------------------------------------------------------------------
105 /**
106      * Clones the map without cloning the keys or values.
107      *
108      * @return a shallow clone
109      */
110     public Object JavaDoc clone() {
111         return super.clone();
112     }
113     
114     /**
115      * Write the map out using a custom routine.
116      */
117     private void writeObject(ObjectOutputStream JavaDoc out) throws IOException JavaDoc {
118         out.defaultWriteObject();
119         doWriteObject(out);
120     }
121
122     /**
123      * Read the map in using a custom routine.
124      */
125     private void readObject(ObjectInputStream JavaDoc in) throws IOException JavaDoc, ClassNotFoundException JavaDoc {
126         in.defaultReadObject();
127         doReadObject(in);
128     }
129     
130     //-----------------------------------------------------------------------
131 /**
132      * Gets the key at the specified index.
133      *
134      * @param index the index to retrieve
135      * @return the key at the specified index
136      * @throws IndexOutOfBoundsException if the index is invalid
137      */
138     public Object JavaDoc get(int index) {
139         return getEntry(index).getKey();
140     }
141     
142     /**
143      * Gets the value at the specified index.
144      *
145      * @param index the index to retrieve
146      * @return the key at the specified index
147      * @throws IndexOutOfBoundsException if the index is invalid
148      */
149     public Object JavaDoc getValue(int index) {
150         return getEntry(index).getValue();
151     }
152     
153     /**
154      * Gets the index of the specified key.
155      *
156      * @param key the key to find the index of
157      * @return the index, or -1 if not found
158      */
159     public int indexOf(Object JavaDoc key) {
160         key = convertKey(key);
161         int i = 0;
162         for (LinkEntry entry = header.after; entry != header; entry = entry.after, i++) {
163             if (isEqualKey(key, entry.key)) {
164                 return i;
165             }
166         }
167         return -1;
168     }
169
170     /**
171      * Removes the element at the specified index.
172      *
173      * @param index the index of the object to remove
174      * @return the previous value corresponding the <code>key</code>,
175      * or <code>null</code> if none existed
176      * @throws IndexOutOfBoundsException if the index is invalid
177      */
178     public Object JavaDoc remove(int index) {
179         return remove(get(index));
180     }
181
182     /**
183      * Gets an unmodifiable List view of the keys.
184      * <p>
185      * The returned list is unmodifiable because changes to the values of
186      * the list (using {@link java.util.ListIterator#set(Object)}) will
187      * effectively remove the value from the list and reinsert that value at
188      * the end of the list, which is an unexpected side effect of changing the
189      * value of a list. This occurs because changing the key, changes when the
190      * mapping is added to the map and thus where it appears in the list.
191      * <p>
192      * An alternative to this method is to use {@link #keySet()}.
193      *
194      * @see #keySet()
195      * @return The ordered list of keys.
196      */
197     public List JavaDoc asList() {
198         return new LinkedMapList(this);
199     }
200
201     /**
202      * List view of map.
203      */
204     static class LinkedMapList extends AbstractList JavaDoc {
205         
206         final LinkedMap parent;
207         
208         LinkedMapList(LinkedMap parent) {
209             this.parent = parent;
210         }
211         
212         public int size() {
213             return parent.size();
214         }
215     
216         public Object JavaDoc get(int index) {
217             return parent.get(index);
218         }
219         
220         public boolean contains(Object JavaDoc obj) {
221             return parent.containsKey(obj);
222         }
223
224         public int indexOf(Object JavaDoc obj) {
225             return parent.indexOf(obj);
226         }
227         
228         public int lastIndexOf(Object JavaDoc obj) {
229             return parent.indexOf(obj);
230         }
231         
232         public boolean containsAll(Collection JavaDoc coll) {
233             return parent.keySet().containsAll(coll);
234         }
235         
236         public Object JavaDoc remove(int index) {
237             throw new UnsupportedOperationException JavaDoc();
238         }
239         
240         public boolean remove(Object JavaDoc obj) {
241             throw new UnsupportedOperationException JavaDoc();
242         }
243         
244         public boolean removeAll(Collection JavaDoc coll) {
245             throw new UnsupportedOperationException JavaDoc();
246         }
247         
248         public boolean retainAll(Collection JavaDoc coll) {
249             throw new UnsupportedOperationException JavaDoc();
250         }
251         
252         public void clear() {
253             throw new UnsupportedOperationException JavaDoc();
254         }
255         
256         public Object JavaDoc[] toArray() {
257             return parent.keySet().toArray();
258         }
259
260         public Object JavaDoc[] toArray(Object JavaDoc[] array) {
261             return parent.keySet().toArray(array);
262         }
263         
264         public Iterator JavaDoc iterator() {
265             return UnmodifiableIterator.decorate(parent.keySet().iterator());
266         }
267         
268         public ListIterator JavaDoc listIterator() {
269             return UnmodifiableListIterator.decorate(super.listIterator());
270         }
271         
272         public ListIterator JavaDoc listIterator(int fromIndex) {
273             return UnmodifiableListIterator.decorate(super.listIterator(fromIndex));
274         }
275         
276         public List JavaDoc subList(int fromIndexInclusive, int toIndexExclusive) {
277             return UnmodifiableList.decorate(super.subList(fromIndexInclusive, toIndexExclusive));
278         }
279     }
280     
281 }
282
Popular Tags