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
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags