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: * SortedSet is a Set which iterates its elements in sorted order.
022: */
023: public interface SortedSet<E> extends Set<E> {
024:
025: /**
026: * Answers the Comparator used to compare elements in this SortedSet.
027: *
028: * @return a Comparator or null if the natural order is used
029: */
030: public Comparator<? super E> comparator();
031:
032: /**
033: * Answer the first sorted element in this SortedSet.
034: *
035: * @return the first sorted element
036: *
037: * @exception NoSuchElementException
038: * when this SortedSet is empty
039: */
040: public E first();
041:
042: /**
043: * Answers a SortedSet of the specified portion of this SortedSet which
044: * contains elements less than the end element. The returned SortedSet is
045: * backed by this SortedSet so changes to one are reflected by the other.
046: *
047: * @param end
048: * the end element
049: * @return a subset where the elements are less than <code>end</code>
050: *
051: * @exception ClassCastException
052: * when the class of the end element is inappropriate for
053: * this SubSet
054: * @exception NullPointerException
055: * when the end element is null and this SortedSet does not
056: * support null elements
057: */
058: public SortedSet<E> headSet(E end);
059:
060: /**
061: * Answer the last sorted element in this SortedSet.
062: *
063: * @return the last sorted element
064: *
065: * @exception NoSuchElementException
066: * when this SortedSet is empty
067: */
068: public E last();
069:
070: /**
071: * Answers a SortedSet of the specified portion of this SortedSet which
072: * contains elements greater or equal to the start element but less than the
073: * end element. The returned SortedSet is backed by this SortedMap so
074: * changes to one are reflected by the other.
075: *
076: * @param start
077: * the start element
078: * @param end
079: * the end element
080: * @return a subset where the elements are greater or equal to
081: * <code>start</code> and less than <code>end</code>
082: *
083: * @exception ClassCastException
084: * when the class of the start or end element is
085: * inappropriate for this SubSet
086: * @exception NullPointerException
087: * when the start or end element is null and this SortedSet
088: * does not support null elements
089: * @exception IllegalArgumentException
090: * when the start element is greater than the end element
091: */
092: public SortedSet<E> subSet(E start, E end);
093:
094: /**
095: * Answers a SortedSet of the specified portion of this SortedSet which
096: * contains elements greater or equal to the start element. The returned
097: * SortedSet is backed by this SortedSet so changes to one are reflected by
098: * the other.
099: *
100: * @param start
101: * the start element
102: * @return a subset where the elements are greater or equal to
103: * <code>start</code>
104: *
105: * @exception ClassCastException
106: * when the class of the start element is inappropriate for
107: * this SubSet
108: * @exception NullPointerException
109: * when the start element is null and this SortedSet does not
110: * support null elements
111: */
112: public SortedSet<E> tailSet(E start);
113: }
|