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: * Set is a collection which does not allow duplicate elements.
022: *
023: * @since 1.2
024: */
025: public interface Set<E> extends Collection<E> {
026:
027: /**
028: * Adds the specified object to this Set. The Set is not modified if it
029: * already contains the object.
030: *
031: * @param object
032: * the object to add
033: * @return true if this Set is modified, false otherwise
034: *
035: * @exception UnsupportedOperationException
036: * when adding to this Set is not supported
037: * @exception ClassCastException
038: * when the class of the object is inappropriate for this Set
039: * @exception IllegalArgumentException
040: * when the object cannot be added to this Set
041: */
042: public boolean add(E object);
043:
044: /**
045: * Adds the objects in the specified Collection which do not exist in this
046: * Set.
047: *
048: * @param collection
049: * the Collection of objects
050: * @return true if this Set is modified, false otherwise
051: *
052: * @exception UnsupportedOperationException
053: * when adding to this Set is not supported
054: * @exception ClassCastException
055: * when the class of an object is inappropriate for this Set
056: * @exception IllegalArgumentException
057: * when an object cannot be added to this Set
058: */
059: public boolean addAll(Collection<? extends E> collection);
060:
061: /**
062: * Removes all elements from this Set, leaving it empty.
063: *
064: * @exception UnsupportedOperationException
065: * when removing from this Set is not supported
066: *
067: * @see #isEmpty
068: * @see #size
069: */
070: public void clear();
071:
072: /**
073: * Searches this Set for the specified object.
074: *
075: * @param object
076: * the object to search for
077: * @return true if object is an element of this Set, false otherwise
078: */
079: public boolean contains(Object object);
080:
081: /**
082: * Searches this Set for all objects in the specified Collection.
083: *
084: * @param collection
085: * the Collection of objects
086: * @return true if all objects in the specified Collection are elements of
087: * this Set, false otherwise
088: */
089: public boolean containsAll(Collection<?> collection);
090:
091: /**
092: * Compares the argument to the receiver, and answers true if they represent
093: * the <em>same</em> object using a class specific comparison.
094: *
095: * @param object
096: * Object the object to compare with this object.
097: * @return boolean <code>true</code> if the object is the same as this
098: * object <code>false</code> if it is different from this object.
099: * @see #hashCode
100: */
101: public boolean equals(Object object);
102:
103: /**
104: * Answers an integer hash code for the receiver. Objects which are equal
105: * answer the same value for this method.
106: *
107: * @return the receiver's hash
108: *
109: * @see #equals
110: */
111: public int hashCode();
112:
113: /**
114: * Answers if this Set has no elements, a size of zero.
115: *
116: * @return true if this Set has no elements, false otherwise
117: *
118: * @see #size
119: */
120: public boolean isEmpty();
121:
122: /**
123: * Answers an Iterator on the elements of this Set.
124: *
125: * @return an Iterator on the elements of this Set
126: *
127: * @see Iterator
128: */
129: public Iterator<E> iterator();
130:
131: /**
132: * Removes any occurrence of the specified object from this Set.
133: *
134: * @param object
135: * the object to remove
136: * @return true if this Set is modified, false otherwise
137: *
138: * @exception UnsupportedOperationException
139: * when removing from this Set is not supported
140: */
141: public boolean remove(Object object);
142:
143: /**
144: * Removes all objects in the specified Collection from this Set.
145: *
146: * @param collection
147: * the Collection of objects to remove
148: * @return true if this Set is modified, false otherwise
149: *
150: * @exception UnsupportedOperationException
151: * when removing from this Set is not supported
152: */
153: public boolean removeAll(Collection<?> collection);
154:
155: /**
156: * Removes all objects from this Set that are not contained in the specified
157: * Collection.
158: *
159: * @param collection
160: * the Collection of objects to retain
161: * @return true if this Set is modified, false otherwise
162: *
163: * @exception UnsupportedOperationException
164: * when removing from this Set is not supported
165: */
166: public boolean retainAll(Collection<?> collection);
167:
168: /**
169: * Answers the number of elements in this Set.
170: *
171: * @return the number of elements in this Set
172: */
173: public int size();
174:
175: /**
176: * Answers an array containing all elements contained in this Set.
177: *
178: * @return an array of the elements from this Set
179: */
180: public Object[] toArray();
181:
182: /**
183: * Answers an array containing all elements contained in this Set. If the
184: * specified array is large enough to hold the elements, the specified array
185: * is used, otherwise an array of the same type is created. If the specified
186: * array is used and is larger than this Set, the array element following
187: * the collection elements is set to null.
188: *
189: * @param array
190: * the array
191: * @return an array of the elements from this Set
192: *
193: * @exception ArrayStoreException
194: * when the type of an element in this Set cannot be stored
195: * in the type of the specified array
196: */
197: public <T> T[] toArray(T[] array);
198: }
|