001: /*
002: * $Header: /home/cvs/jakarta-commons/primitives/src/java/org/apache/commons/collections/primitives/ByteCollection.java,v 1.3 2003/10/16 20:49:35 scolebourne Exp $
003: * ====================================================================
004: * The Apache Software License, Version 1.1
005: *
006: * Copyright (c) 2002-2003 The Apache Software Foundation. All rights
007: * reserved.
008: *
009: * Redistribution and use in source and binary forms, with or without
010: * modification, are permitted provided that the following conditions
011: * are met:
012: *
013: * 1. Redistributions of source code must retain the above copyright
014: * notice, this list of conditions and the following disclaimer.
015: *
016: * 2. Redistributions in binary form must reproduce the above copyright
017: * notice, this list of conditions and the following disclaimer in
018: * the documentation and/or other materials provided with the
019: * distribution.
020: *
021: * 3. The end-user documentation included with the redistribution, if
022: * any, must include the following acknowledgement:
023: * "This product includes software developed by the
024: * Apache Software Foundation (http://www.apache.org/)."
025: * Alternately, this acknowledgement may appear in the software itself,
026: * if and wherever such third-party acknowledgements normally appear.
027: *
028: * 4. The names "The Jakarta Project", "Commons", and "Apache Software
029: * Foundation" must not be used to endorse or promote products derived
030: * from this software without prior written permission. For written
031: * permission, please contact apache@apache.org.
032: *
033: * 5. Products derived from this software may not be called "Apache"
034: * nor may "Apache" appear in their names without prior written
035: * permission of the Apache Software Foundation.
036: *
037: * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
038: * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
039: * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
040: * DISCLAIMED. IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR
041: * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
042: * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
043: * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
044: * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
045: * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
046: * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
047: * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
048: * SUCH DAMAGE.
049: * ====================================================================
050: *
051: * This software consists of voluntary contributions made by many
052: * individuals on behalf of the Apache Software Foundation. For more
053: * information on the Apache Software Foundation, please see
054: * <http://www.apache.org/>.
055: *
056: */
057:
058: package org.apache.commons.collections.primitives;
059:
060: /**
061: * A collection of <code>byte</code> values.
062: *
063: * @see org.apache.commons.collections.primitives.adapters.ByteCollectionCollection
064: * @see org.apache.commons.collections.primitives.adapters.CollectionByteCollection
065: *
066: * @since Commons Primitives 1.0
067: * @version $Revision: 1.3 $ $Date: 2003/10/16 20:49:35 $
068: *
069: * @author Rodney Waldhoff
070: */
071: public interface ByteCollection {
072: /**
073: * Ensures that I contain the specified element
074: * (optional operation). Returns <code>true</code>
075: * iff I changed as a result of this call.
076: * <p/>
077: * If a collection refuses to add the specified
078: * element for any reason other than that it already contains
079: * the element, it <i>must</i> throw an exception (rather than
080: * simply returning <tt>false</tt>). This preserves the invariant
081: * that a collection always contains the specified element after
082: * this call returns.
083: *
084: * @param element the value whose presence within me is to be ensured
085: * @return <code>true</code> iff I changed as a result of this call
086: *
087: * @throws UnsupportedOperationException when this operation is not
088: * supported
089: * @throws IllegalArgumentException may be thrown if some aspect of the
090: * specified element prevents it from being added to me
091: */
092: boolean add(byte element);
093:
094: /**
095: * {@link #add Adds} all of the elements in the
096: * specified collection to me (optional operation).
097: *
098: * @param c the collection of elements whose presence within me is to
099: * be ensured
100: * @return <code>true</code> iff I changed as a result of this call
101: *
102: * @throws UnsupportedOperationException when this operation is not
103: * supported
104: * @throws IllegalArgumentException may be thrown if some aspect of some
105: * specified element prevents it from being added to me
106: */
107: boolean addAll(ByteCollection c);
108:
109: /**
110: * Removes all my elements (optional operation).
111: * I will be {@link #isEmpty empty} after this
112: * method successfully returns.
113: *
114: * @throws UnsupportedOperationException when this operation is not
115: * supported
116: */
117: void clear();
118:
119: /**
120: * Returns <code>true</code> iff I contain
121: * the specified element.
122: *
123: * @param element the value whose presence within me is to be tested
124: * @return <code>true</code> iff I contain the specified element
125: */
126: boolean contains(byte element);
127:
128: /**
129: * Returns <code>true</code> iff I {@link #contains contain}
130: * all of the elements in the given collection.
131: *
132: * @param c the collection of elements whose presence within me is to
133: * be tested
134: * @return <code>true</code> iff I contain the all the specified elements
135: */
136: boolean containsAll(ByteCollection c);
137:
138: /**
139: * Returns <code>true</code> iff I contain no elements.
140: * @return <code>true</code> iff I contain no elements.
141: */
142: boolean isEmpty();
143:
144: /**
145: * Returns an {@link ByteIterator iterator} over all my elements.
146: * This base interface places no constraints on the order
147: * in which the elements are returned by the returned iterator.
148: * @return an {@link ByteIterator iterator} over all my elements.
149: */
150: ByteIterator iterator();
151:
152: /**
153: * Removes all of my elements that are contained in the
154: * specified collection (optional operation).
155: * The behavior of this method is unspecified if
156: * the given collection is modified while this method
157: * is executing. Note that this includes the case
158: * in which the given collection is this collection,
159: * and it is not empty.
160: *
161: * @param c the collection of elements to remove
162: * @return <code>true</code> iff I contained the at least one of the
163: * specified elements, in other words, returns <code>true</code>
164: * iff I changed as a result of this call
165: *
166: * @throws UnsupportedOperationException when this operation is not
167: * supported
168: */
169: boolean removeAll(ByteCollection c);
170:
171: /**
172: * Removes a single occurrence of the specified element
173: * (optional operation).
174: *
175: * @param element the element to remove, if present
176: * @return <code>true</code> iff I contained the specified element,
177: * in other words, iff I changed as a result of this call
178: *
179: * @throws UnsupportedOperationException when this operation is not
180: * supported
181: */
182: boolean removeElement(byte element);
183:
184: /**
185: * Removes all of my elements that are <i>not</i> contained in the
186: * specified collection (optional operation).
187: * (In other words, retains <i>only</i> my elements that are
188: * contained in the specified collection.)
189: * The behavior of this method is unspecified if
190: * the given collection is modified while this method
191: * is executing.
192: *
193: * @param c the collection of elements to retain
194: * @return <code>true</code> iff I changed as a result
195: * of this call
196: *
197: * @throws UnsupportedOperationException when this operation is not
198: * supported
199: */
200: boolean retainAll(ByteCollection c);
201:
202: /**
203: * Returns the number of elements I contain.
204: * @return the number of elements I contain
205: */
206: int size();
207:
208: /**
209: * Returns an array containing all of my elements.
210: * The length of the returned array will be equal
211: * to my {@link #size size}.
212: * <p/>
213: * The returned array will be independent of me,
214: * so that callers may modify that
215: * returned array without modifying this collection.
216: * <p/>
217: * When I guarantee the order in which
218: * elements are returned by an {@link #iterator iterator},
219: * the returned array will contain elements in the
220: * same order.
221: *
222: * @return an array containing all my elements
223: */
224: byte[] toArray();
225:
226: /**
227: * Returns an array containing all of my elements,
228: * using the given array if it is large
229: * enough. When the length of the given array is
230: * larger than the number of elements I contain,
231: * values outside of my range will be unchanged.
232: * <p/>
233: * The returned array will be independent of me,
234: * so that callers may modify that
235: * returned array without modifying this collection.
236: * <p/>
237: * When I guarantee the order in which
238: * elements are returned by an {@link #iterator iterator},
239: * the returned array will contain elements in the
240: * same order.
241: *
242: * @param a an array that may be used to contain the elements
243: * @return an array containing all my elements
244: */
245: byte[] toArray(byte[] a);
246: }
|