001: /*
002: * Licensed to the Apache Software Foundation (ASF) under one or more
003: * contributor license agreements. See the NOTICE file distributed with
004: * this work for additional information regarding copyright ownership.
005: * The ASF licenses this file to You under the Apache License, Version 2.0
006: * (the "License"); you may not use this file except in compliance with
007: * the License. You may obtain a copy of the License at
008: *
009: * http://www.apache.org/licenses/LICENSE-2.0
010: *
011: * Unless required by applicable law or agreed to in writing, software
012: * distributed under the License is distributed on an "AS IS" BASIS,
013: * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014: * See the License for the specific language governing permissions and
015: * limitations under the License.
016: */
017:
018: package java.util;
019:
020: /**
021: * SortedMap is a Map where the iterators sequence in order of the sorted keys.
022: */
023: public interface SortedMap<K, V> extends Map<K, V> {
024:
025: /**
026: * Answers the Comparator used to compare elements in this SortedMap.
027: *
028: * @return a Comparator or null if the natural order is used
029: */
030: public Comparator<? super K> comparator();
031:
032: /**
033: * Answer the first sorted key in this SortedMap.
034: *
035: * @return the first sorted key
036: *
037: * @exception NoSuchElementException
038: * when this SortedMap is empty
039: */
040: public K firstKey();
041:
042: /**
043: * Answers a <code>SortedMap</code> of the specified portion of this
044: * <code>SortedMap</code> which contains keys less than the end key. Users
045: * should be aware that the return value is actually backed by this
046: * <code>SortedMap</code>. Hence any modifications made to one will be
047: * immediately visible to the other.
048: *
049: * @param endKey
050: * the end key
051: * @return a submap where the keys are less than <code>endKey</code>
052: *
053: * @exception ClassCastException
054: * when the class of the end key is inappropriate for this
055: * SubMap
056: * @exception NullPointerException
057: * when the end key is null and this SortedMap does not
058: * support null keys
059: */
060: public SortedMap<K, V> headMap(K endKey);
061:
062: /**
063: * Answers the last sorted key in this SortedMap.
064: *
065: * @return the last sorted key
066: *
067: * @exception NoSuchElementException
068: * when this SortedMap is empty
069: */
070: public K lastKey();
071:
072: /**
073: * Answers a SortedMap of the specified portion of this SortedMap which
074: * contains keys greater or equal to the start key but less than the end
075: * key. Users should be aware that the return value is actually backed by
076: * this <code>SortedMap</code>. Hence any modifications made to one will
077: * be immediately visible to the other.
078: *
079: * @param startKey
080: * the start key
081: * @param endKey
082: * the end key
083: * @return a submap where the keys are greater or equal to
084: * <code>startKey</code> and less than <code>endKey</code>
085: *
086: * @exception ClassCastException
087: * when the class of the start or end key is inappropriate
088: * for this SubMap
089: * @exception NullPointerException
090: * when the start or end key is null and this SortedMap does
091: * not support null keys
092: * @exception IllegalArgumentException
093: * when the start key is greater than the end key
094: */
095: public SortedMap<K, V> subMap(K startKey, K endKey);
096:
097: /**
098: * Answers a SortedMap of the specified portion of this SortedMap which
099: * contains keys greater or equal to the start key. The returned SortedMap
100: * is backed by this SortedMap so changes to one are reflected by the other.
101: *
102: * @param startKey
103: * the start key
104: * @return a submap where the keys are greater or equal to
105: * <code>startKey</code>
106: *
107: * @exception ClassCastException
108: * when the class of the start key is inappropriate for this
109: * SubMap
110: * @exception NullPointerException
111: * when the start key is null and this SortedMap does not
112: * support null keys
113: */
114: public SortedMap<K, V> tailMap(K startKey);
115: }
|