KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > apache > commons > collections > primitives > ByteCollection


1 /*
2  * Licensed to the Apache Software Foundation (ASF) under one or more
3  * contributor license agreements. See the NOTICE file distributed with
4  * this work for additional information regarding copyright ownership.
5  * The ASF licenses this file to You under the Apache License, Version 2.0
6  * (the "License"); you may not use this file except in compliance with
7  * the License. You may obtain a copy of the License at
8  *
9  * http://www.apache.org/licenses/LICENSE-2.0
10  *
11  * Unless required by applicable law or agreed to in writing, software
12  * distributed under the License is distributed on an "AS IS" BASIS,
13  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14  * See the License for the specific language governing permissions and
15  * limitations under the License.
16  */

17 package org.apache.commons.collections.primitives;
18
19 /**
20  * A collection of <code>byte</code> values.
21  *
22  * @see org.apache.commons.collections.primitives.adapters.ByteCollectionCollection
23  * @see org.apache.commons.collections.primitives.adapters.CollectionByteCollection
24  *
25  * @since Commons Primitives 1.0
26  * @version $Revision: 480460 $ $Date: 2006-11-29 00:14:21 -0800 (Wed, 29 Nov 2006) $
27  *
28  * @author Rodney Waldhoff
29  */

30 public interface ByteCollection {
31     /**
32      * Ensures that I contain the specified element
33      * (optional operation). Returns <code>true</code>
34      * iff I changed as a result of this call.
35      * <p/>
36      * If a collection refuses to add the specified
37      * element for any reason other than that it already contains
38      * the element, it <i>must</i> throw an exception (rather than
39      * simply returning <tt>false</tt>). This preserves the invariant
40      * that a collection always contains the specified element after
41      * this call returns.
42      *
43      * @param element the value whose presence within me is to be ensured
44      * @return <code>true</code> iff I changed as a result of this call
45      *
46      * @throws UnsupportedOperationException when this operation is not
47      * supported
48      * @throws IllegalArgumentException may be thrown if some aspect of the
49      * specified element prevents it from being added to me
50      */

51     boolean add(byte element);
52
53     /**
54      * {@link #add Adds} all of the elements in the
55      * specified collection to me (optional operation).
56      *
57      * @param c the collection of elements whose presence within me is to
58      * be ensured
59      * @return <code>true</code> iff I changed as a result of this call
60      *
61      * @throws UnsupportedOperationException when this operation is not
62      * supported
63      * @throws IllegalArgumentException may be thrown if some aspect of some
64      * specified element prevents it from being added to me
65      */

66     boolean addAll(ByteCollection c);
67     
68     /**
69      * Removes all my elements (optional operation).
70      * I will be {@link #isEmpty empty} after this
71      * method successfully returns.
72      *
73      * @throws UnsupportedOperationException when this operation is not
74      * supported
75      */

76     void clear();
77
78     /**
79      * Returns <code>true</code> iff I contain
80      * the specified element.
81      *
82      * @param element the value whose presence within me is to be tested
83      * @return <code>true</code> iff I contain the specified element
84      */

85     boolean contains(byte element);
86     
87     /**
88      * Returns <code>true</code> iff I {@link #contains contain}
89      * all of the elements in the given collection.
90      *
91      * @param c the collection of elements whose presence within me is to
92      * be tested
93      * @return <code>true</code> iff I contain the all the specified elements
94      */

95     boolean containsAll(ByteCollection c);
96     
97     /**
98      * Returns <code>true</code> iff I contain no elements.
99      * @return <code>true</code> iff I contain no elements.
100      */

101     boolean isEmpty();
102     
103     /**
104      * Returns an {@link ByteIterator iterator} over all my elements.
105      * This base interface places no constraints on the order
106      * in which the elements are returned by the returned iterator.
107      * @return an {@link ByteIterator iterator} over all my elements.
108      */

109     ByteIterator iterator();
110     
111     /**
112      * Removes all of my elements that are contained in the
113      * specified collection (optional operation).
114      * The behavior of this method is unspecified if
115      * the given collection is modified while this method
116      * is executing. Note that this includes the case
117      * in which the given collection is this collection,
118      * and it is not empty.
119      *
120      * @param c the collection of elements to remove
121      * @return <code>true</code> iff I contained the at least one of the
122      * specified elements, in other words, returns <code>true</code>
123      * iff I changed as a result of this call
124      *
125      * @throws UnsupportedOperationException when this operation is not
126      * supported
127      */

128     boolean removeAll(ByteCollection c);
129      
130     /**
131      * Removes a single occurrence of the specified element
132      * (optional operation).
133      *
134      * @param element the element to remove, if present
135      * @return <code>true</code> iff I contained the specified element,
136      * in other words, iff I changed as a result of this call
137      *
138      * @throws UnsupportedOperationException when this operation is not
139      * supported
140      */

141     boolean removeElement(byte element);
142     
143     /**
144      * Removes all of my elements that are <i>not</i> contained in the
145      * specified collection (optional operation).
146      * (In other words, retains <i>only</i> my elements that are
147      * contained in the specified collection.)
148      * The behavior of this method is unspecified if
149      * the given collection is modified while this method
150      * is executing.
151      *
152      * @param c the collection of elements to retain
153      * @return <code>true</code> iff I changed as a result
154      * of this call
155      *
156      * @throws UnsupportedOperationException when this operation is not
157      * supported
158      */

159     boolean retainAll(ByteCollection c);
160     
161     /**
162      * Returns the number of elements I contain.
163      * @return the number of elements I contain
164      */

165     int size();
166     
167     /**
168      * Returns an array containing all of my elements.
169      * The length of the returned array will be equal
170      * to my {@link #size size}.
171      * <p/>
172      * The returned array will be independent of me,
173      * so that callers may modify that
174      * returned array without modifying this collection.
175      * <p/>
176      * When I guarantee the order in which
177      * elements are returned by an {@link #iterator iterator},
178      * the returned array will contain elements in the
179      * same order.
180      *
181      * @return an array containing all my elements
182      */

183     byte[] toArray();
184     
185     /**
186      * Returns an array containing all of my elements,
187      * using the given array if it is large
188      * enough. When the length of the given array is
189      * larger than the number of elements I contain,
190      * values outside of my range will be unchanged.
191      * <p/>
192      * The returned array will be independent of me,
193      * so that callers may modify that
194      * returned array without modifying this collection.
195      * <p/>
196      * When I guarantee the order in which
197      * elements are returned by an {@link #iterator iterator},
198      * the returned array will contain elements in the
199      * same order.
200      *
201      * @param a an array that may be used to contain the elements
202      * @return an array containing all my elements
203      */

204     byte[] toArray(byte[] a);
205 }
206
Popular Tags