KickJava   Java API By Example, From Geeks To Geeks.

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


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  * An ordered collection of <code>byte</code> values.
21  *
22  * @see org.apache.commons.collections.primitives.adapters.ByteListList
23  * @see org.apache.commons.collections.primitives.adapters.ListByteList
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 ByteList extends ByteCollection {
31     /**
32      * Appends the specified element to the end of me
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      * Inserts the specified element at the specified position
55      * (optional operation). Shifts the element currently
56      * at that position (if any) and any subsequent elements to the
57      * right, increasing their indices.
58      *
59      * @param index the index at which to insert the element
60      * @param element the value to insert
61      *
62      * @throws UnsupportedOperationException when this operation is not
63      * supported
64      * @throws IllegalArgumentException if some aspect of the specified element
65      * prevents it from being added to me
66      * @throws IndexOutOfBoundsException if the specified index is out of range
67      */

68     void add(int index, byte element);
69           
70     /**
71      * Inserts all of the elements in the specified collection into me,
72      * at the specified position (optional operation). Shifts the
73      * element currently at that position (if any) and any subsequent
74      * elements to the right, increasing their indices. The new elements
75      * will appear in the order that they are returned by the given
76      * collection's {@link ByteCollection#iterator iterator}.
77      *
78      * @param index the index at which to insert the first element from
79      * the specified collection
80      * @param collection the {@link ByteCollection ByteCollection} of elements to add
81      * @return <code>true</code> iff I changed as a result of this call
82      *
83      * @throws UnsupportedOperationException when this operation is not
84      * supported
85      * @throws IndexOutOfBoundsException if the specified index is out of range
86      */

87     boolean addAll(int index, ByteCollection collection);
88     
89     /**
90      * Returns <code>true</code> iff <i>that</i> is an <code>ByteList</code>
91      * that contains the same elements in the same order as me.
92      * In other words, returns <code>true</code> iff <i>that</i> is
93      * a <code>ByteList</code> that has the same {@link #size() size} as me,
94      * and for which the elements returned by its
95      * {@link ByteList#iterator iterator} are equal (<code>==</code>) to
96      * the corresponding elements within me.
97      * (This contract ensures that this method works properly across
98      * different implementations of the <code>ByteList</code> interface.)
99      *
100      * @param that the object to compare to me
101      * @return <code>true</code> iff <i>that</i> is an <code>ByteList</code>
102      * that contains the same elements in the same order as me
103      */

104     boolean equals(Object JavaDoc that);
105     
106     /**
107      * Returns the value of the element at the specified position
108      * within me.
109      *
110      * @param index the index of the element to return
111      * @return the value of the element at the specified position
112      * @throws IndexOutOfBoundsException if the specified index is out of range
113      */

114     byte get(int index);
115         
116     /**
117      * Returns my hash code.
118      * <p />
119      * The hash code of an <code>ByteList</code> is defined to be the
120      * result of the following calculation:
121      * <pre> int hash = 1;
122      * for(ByteIterator iter = iterator(); iter.hasNext(); ) {
123      * byte value = iter.next();
124      * hash = 31*hash + (int)(value ^ (value >>> 32));
125      * }</pre>
126      * <p />
127      * This contract ensures that this method is consistent with
128      * {@link #equals equals} and with the
129      * {@link java.util.List#hashCode hashCode}
130      * method of a {@link java.util.List List} of {@link Byte}s.
131      *
132      * @return my hash code
133      */

134     int hashCode();
135
136     /**
137      * Returns the index of the first occurrence
138      * of the specified element within me,
139      * or <code>-1</code> if I do not contain
140      * the element.
141      *
142      * @param element the element to search for
143      * @return the smallest index of an element matching the specified value,
144      * or <code>-1</code> if no such matching element can be found
145      */

146     int indexOf(byte element);
147      
148     /**
149      * Returns an {@link ByteIterator iterator} over all my elements,
150      * in the appropriate sequence.
151      * @return an {@link ByteIterator iterator} over all my elements.
152      */

153     ByteIterator iterator();
154
155     /**
156      * Returns the index of the last occurrence
157      * of the specified element within me,
158      * or -1 if I do not contain the element.
159      *
160      * @param element the element to search for
161      * @return the largest index of an element matching the specified value,
162      * or <code>-1</code> if no such matching element can be found
163      */

164     int lastIndexOf(byte element);
165     
166     /**
167      * Returns a
168      * {@link ByteListIterator bidirectional iterator}
169      * over all my elements, in the appropriate sequence.
170      */

171     ByteListIterator listIterator();
172     
173     /**
174      * Returns a
175      * {@link ByteListIterator bidirectional iterator}
176      * over all my elements, in the appropriate sequence,
177      * starting at the specified position. The
178      * specified <i>index</i> indicates the first
179      * element that would be returned by an initial
180      * call to the
181      * {@link ByteListIterator#next next}
182      * method. An initial call to the
183      * {@link ByteListIterator#previous previous}
184      * method would return the element with the specified
185      * <i>index</i> minus one.
186      *
187      * @throws IndexOutOfBoundsException if the specified index is out of range
188      */

189     ByteListIterator listIterator(int index);
190     
191     /**
192      * Removes the element at the specified position in
193      * (optional operation). Any subsequent elements
194      * are shifted to the left, subtracting one from their
195      * indices. Returns the element that was removed.
196      *
197      * @param index the index of the element to remove
198      * @return the value of the element that was removed
199      *
200      * @throws UnsupportedOperationException when this operation is not
201      * supported
202      * @throws IndexOutOfBoundsException if the specified index is out of range
203      */

204     byte removeElementAt(int index);
205    
206     /**
207      * Replaces the element at the specified
208      * position in me with the specified element
209      * (optional operation).
210      *
211      * @param index the index of the element to change
212      * @param element the value to be stored at the specified position
213      * @return the value previously stored at the specified position
214      *
215      * @throws UnsupportedOperationException when this operation is not
216      * supported
217      * @throws IndexOutOfBoundsException if the specified index is out of range
218      */

219     byte set(int index, byte element);
220     
221     /**
222      * Returns a view of the elements within me
223      * between the specified <i>fromIndex</i>, inclusive, and
224      * <i>toIndex</i>, exclusive. The returned <code>ByteList</code>
225      * is backed by me, so that any changes in
226      * the returned list are reflected in me, and vice-versa.
227      * The returned list supports all of the optional operations
228      * that I support.
229      * <p/>
230      * Note that when <code><i>fromIndex</i> == <i>toIndex</i></code>,
231      * the returned list is initially empty, and when
232      * <code><i>fromIndex</i> == 0 && <i>toIndex</i> == {@link #size() size()}</code>
233      * the returned list is my "improper" sublist, containing all my elements.
234      * <p/>
235      * The semantics of the returned list become undefined
236      * if I am structurally modified in any way other than
237      * via the returned list.
238      *
239      * @param fromIndex the smallest index (inclusive) in me that appears in
240      * the returned list
241      * @param toIndex the largest index (exclusive) in me that appears in the
242      * returned list
243      * @return a view of this list from <i>fromIndex</i> (inclusive) to
244      * <i>toIndex</i> (exclusive)
245      *
246      * @throws IndexOutOfBoundsException if either specified index is out of range
247      */

248     ByteList subList(int fromIndex, int toIndex);
249
250 }
251
Popular Tags