1 /* 2 * Copyright 2001-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; 17 18 /** 19 * Defines a map that maintains order and allows both forward and backward 20 * iteration through that order. 21 * 22 * @since Commons Collections 3.0 23 * @version $Revision: 1.6 $ $Date: 2004/02/18 01:15:42 $ 24 * 25 * @author Stephen Colebourne 26 */ 27 public interface OrderedMap extends IterableMap { 28 29 /** 30 * Obtains an <code>OrderedMapIterator</code> over the map. 31 * <p> 32 * A ordered map iterator is an efficient way of iterating over maps 33 * in both directions. 34 * <pre> 35 * BidiMap map = new TreeBidiMap(); 36 * MapIterator it = map.mapIterator(); 37 * while (it.hasNext()) { 38 * Object key = it.next(); 39 * Object value = it.getValue(); 40 * it.setValue("newValue"); 41 * Object previousKey = it.previous(); 42 * } 43 * </pre> 44 * 45 * @return a map iterator 46 */ 47 OrderedMapIterator orderedMapIterator(); 48 49 /** 50 * Gets the first key currently in this map. 51 * 52 * @return the first key currently in this map 53 * @throws java.util.NoSuchElementException if this map is empty 54 */ 55 public Object firstKey(); 56 57 /** 58 * Gets the last key currently in this map. 59 * 60 * @return the last key currently in this map 61 * @throws java.util.NoSuchElementException if this map is empty 62 */ 63 public Object lastKey(); 64 65 /** 66 * Gets the next key after the one specified. 67 * 68 * @param key the key to search for next from 69 * @return the next key, null if no match or at end 70 */ 71 public Object nextKey(Object key); 72 73 /** 74 * Gets the previous key before the one specified. 75 * 76 * @param key the key to search for previous from 77 * @return the previous key, null if no match or at start 78 */ 79 public Object previousKey(Object key); 80 81 } 82