001/* 002 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 003 * 004 * This code is free software; you can redistribute it and/or modify it 005 * under the terms of the GNU General Public License version 2 only, as 006 * published by the Free Software Foundation. Oracle designates this 007 * particular file as subject to the "Classpath" exception as provided 008 * by Oracle in the LICENSE file that accompanied this code. 009 * 010 * This code is distributed in the hope that it will be useful, but WITHOUT 011 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 012 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 013 * version 2 for more details (a copy is included in the LICENSE file that 014 * accompanied this code). 015 * 016 * You should have received a copy of the GNU General Public License version 017 * 2 along with this work; if not, write to the Free Software Foundation, 018 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 019 * 020 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 021 * or visit www.oracle.com if you need additional information or have any 022 * questions. 023 */ 024 025/* 026 * This file is available under and governed by the GNU General Public 027 * License version 2 only, as published by the Free Software Foundation. 028 * However, the following notice accompanied the original version of this 029 * file: 030 * 031 * Written by Doug Lea and Josh Bloch with assistance from members of JCP 032 * JSR-166 Expert Group and released to the public domain, as explained at 033 * http://creativecommons.org/publicdomain/zero/1.0/ 034 */ 035package Torello.Java.ReadOnly; 036 037import Torello.Java.Additional.RemoveUnsupportedIterator; 038 039import java.util.Collection; 040import java.util.Comparator; 041import java.util.NavigableSet; 042 043/** 044 * Immutable variant of Java Collections Framework interface 045 * <CODE>java.util.NavigableSet<E></CODE>. 046 * 047 * <EMBED CLASS='external-html' DATA-JDK=ReadOnlyNavigableSet DATA-FILE-ID=INTERFACES> 048 * 049 * @param <E> the type of elements maintained by this set 050 */ 051@Torello.JavaDoc.JDHeaderBackgroundImg(EmbedTagFileID="JDHBI_INTERFACE") 052public interface ReadOnlyNavigableSet<E> extends ReadOnlySortedSet<E> 053{ 054 // ******************************************************************************************** 055 // ******************************************************************************************** 056 // Original JDK Interface Methods 057 // ******************************************************************************************** 058 // ******************************************************************************************** 059 060 061 /** 062 * Returns the greatest element in this set strictly less than the given element, or 063 * {@code null} if there is no such element. 064 * 065 * @param e the value to match 066 * 067 * @return the greatest element less than {@code e}, or {@code null} if there is no such 068 * element 069 * 070 * @throws ClassCastException if the specified element cannot be compared with the elements 071 * currently in the set 072 * 073 * @throws NullPointerException if the specified element is null and this set does not permit 074 * null elements 075 */ 076 E lower(E e); 077 078 /** 079 * Returns the greatest element in this set less than or equal to the given element, or 080 * {@code null} if there is no such element. 081 * 082 * @param e the value to match 083 * 084 * @return the greatest element less than or equal to {@code e}, or {@code null} if there is no 085 * such element 086 * 087 * @throws ClassCastException if the specified element cannot be compared with the elements 088 * currently in the set 089 * 090 * @throws NullPointerException if the specified element is null and this set does not permit 091 * null elements 092 */ 093 E floor(E e); 094 095 /** 096 * Returns the least element in this set greater than or equal to 097 * the given element, or {@code null} if there is no such element. 098 * 099 * @param e the value to match 100 * 101 * @return the least element greater than or equal to {@code e}, or {@code null} if there is no 102 * such element 103 * 104 * @throws ClassCastException if the specified element cannot be compared with the elements 105 * currently in the set 106 * 107 * @throws NullPointerException if the specified element is null and this set does not permit 108 * null elements 109 */ 110 E ceiling(E e); 111 112 /** 113 * Returns the least element in this set strictly greater than the 114 * given element, or {@code null} if there is no such element. 115 * 116 * @param e the value to match 117 * 118 * @return the least element greater than {@code e}, or {@code null} if there is no such 119 * element 120 * 121 * @throws ClassCastException if the specified element cannot be compared with the elements 122 * currently in the set 123 * 124 * @throws NullPointerException if the specified element is null and this set does not permit 125 * null elements 126 */ 127 E higher(E e); 128 129 /** 130 * Returns an iterator over the elements in this set, in ascending order. 131 * @return an iterator over the elements in this set, in ascending order 132 */ 133 RemoveUnsupportedIterator<E> iterator(); 134 135 /** 136 * Returns a reverse order view of the elements contained in this set. 137 * 138 * <BR /><BR />The expression {@code s.descendingSet().descendingSet()} returns a view of 139 * {@code s} essentially equivalent to {@code s}. 140 * 141 * @return a reverse order view of this set 142 */ 143 ReadOnlyNavigableSet<E> descendingSet(); 144 145 /** 146 * Returns an iterator over the elements in this set, in descending order. 147 * Equivalent in effect to {@code descendingSet().iterator()}. 148 * 149 * @return an iterator over the elements in this set, in descending order 150 */ 151 RemoveUnsupportedIterator<E> descendingIterator(); 152 153 /** 154 * Returns a view of the portion of this set whose elements range from {@code fromElement} to 155 * {@code toElement}. If {@code fromElement} and {@code toElement} are equal, the returned set 156 * is empty unless {@code fromInclusive} and {@code toInclusive} are both true. The returned 157 * set supports all optional set operations that this set supports. 158 * 159 * @param fromElement low endpoint of the returned set 160 * @param fromInclusive {@code TRUE} if the low endpoint is to be included in the returned view 161 * @param toElement high endpoint of the returned set 162 * @param toInclusive {@code TRUE} if the high endpoint is to be included in the returned view 163 * 164 * @return a view of the portion of this set whose elements range from {@code fromElement}, 165 * inclusive, to {@code toElement}, exclusive 166 * 167 * @throws ClassCastException if {@code fromElement} and 168 * {@code toElement} cannot be compared to one another using this 169 * set's comparator (or, if the set has no comparator, using 170 * natural ordering). Implementations may, but are not required 171 * to, throw this exception if {@code fromElement} or 172 * {@code toElement} cannot be compared to elements currently in 173 * the set. 174 * 175 * @throws NullPointerException if {@code fromElement} or {@code toElement} is null and this 176 * set does not permit null elements 177 * 178 * @throws IllegalArgumentException if {@code fromElement} is greater than {@code toElement}; 179 * or if this set itself has a restricted range, and {@code fromElement} or {@code toElement} 180 * lies outside the bounds of the range. 181 */ 182 ReadOnlyNavigableSet<E> subSet( 183 E fromElement, boolean fromInclusive, 184 E toElement, boolean toInclusive 185 ); 186 187 /** 188 * Returns a view of the portion of this set whose elements are less than (or equal to, if 189 * {@code inclusive} is true) {@code toElement}. 190 * 191 * @param toElement high endpoint of the returned set 192 * @param inclusive {@code TRUE} if the high endpoint is to be included in the returned view 193 * 194 * @return a view of the portion of this set whose elements are less than (or equal to, if 195 * {@code inclusive} is true) {@code toElement} 196 * 197 * @throws ClassCastException if {@code toElement} is not compatible with this set's comparator 198 * (or, if the set has no comparator, if {@code toElement} does not implement 199 * {@code Comparable}). Implementations may, but are not required to, throw this exception if 200 * {@code toElement} cannot be compared to elements currently in the set. 201 * 202 * @throws NullPointerException if {@code toElement} is null and this set does not permit null 203 * elements 204 * 205 * @throws IllegalArgumentException if this set itself has a restricted range, and 206 * {@code toElement} lies outside the bounds of the range 207 */ 208 ReadOnlyNavigableSet<E> headSet(E toElement, boolean inclusive); 209 210 /** 211 * Returns a view of the portion of this set whose elements are greater than (or equal to, if 212 * {@code inclusive} is true) {@code fromElement}. 213 * 214 * @param fromElement low endpoint of the returned set 215 * @param inclusive {@code TRUE} if the low endpoint is to be included in the returned view 216 * 217 * @return a view of the portion of this set whose elements are greater than or equal to 218 * {@code fromElement} 219 * 220 * @throws ClassCastException if {@code fromElement} is not compatible with this set's 221 * comparator (or, if the set has no comparator, if {@code fromElement} does not implement 222 * {@code Comparable}). Implementations may, but are not required to, throw this exception if 223 * {@code fromElement} cannot be compared to elements currently in the set. 224 * 225 * @throws NullPointerException if {@code fromElement} is null and this set does not permit 226 * null elements 227 * 228 * @throws IllegalArgumentException if this set itself has a restricted range, and 229 * {@code fromElement} lies outside the bounds of the range 230 */ 231 ReadOnlyNavigableSet<E> tailSet(E fromElement, boolean inclusive); 232 233 /** 234 * {@inheritDoc} 235 * 236 * <BR /><BR />Equivalent to {@code subSet(fromElement, true, toElement, false)}. 237 * 238 * @throws ClassCastException {@inheritDoc} 239 * @throws NullPointerException {@inheritDoc} 240 * @throws IllegalArgumentException {@inheritDoc} 241 */ 242 ReadOnlySortedSet<E> subSet(E fromElement, E toElement); 243 244 /** 245 * {@inheritDoc} 246 * 247 * <BR /><BR />Equivalent to {@code headSet(toElement, false)}. 248 * 249 * @throws ClassCastException {@inheritDoc} 250 * @throws NullPointerException {@inheritDoc} 251 * @throws IllegalArgumentException {@inheritDoc} 252 */ 253 ReadOnlySortedSet<E> headSet(E toElement); 254 255 /** 256 * {@inheritDoc} 257 * 258 * <BR /><BR />Equivalent to {@code tailSet(fromElement, true)}. 259 * 260 * @throws ClassCastException {@inheritDoc} 261 * @throws NullPointerException {@inheritDoc} 262 * @throws IllegalArgumentException {@inheritDoc} 263 */ 264 ReadOnlySortedSet<E> tailSet(E fromElement); 265 266 /** 267 * {@inheritDoc} 268 * <BR /><BR /> 269 * This method is equivalent to {@link #descendingSet descendingSet}. 270 * 271 * @implSpec 272 * The implementation in this interface returns the result of calling the 273 * {@code descendingSet} method. 274 * 275 * @return a reverse-ordered view of this collection, as a {@code NavigableSet} 276 */ 277 default ReadOnlyNavigableSet<E> reversed() 278 { return this.descendingSet(); } 279}