KickJava   Java API By Example, From Geeks To Geeks.

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


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 bi-directional iterator over <code>byte</code> values.
21  *
22  * @see org.apache.commons.collections.primitives.adapters.ByteListIteratorListIterator
23  * @see org.apache.commons.collections.primitives.adapters.ListIteratorByteListIterator
24  *
25  * @since Commons Collections 2.2
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 ByteListIterator extends ByteIterator {
31     /**
32      * Inserts the specified element into my underlying collection
33      * (optional operation).
34      * The element is inserted immediately before the next element
35      * that would have been returned by {@link #next}, if any,
36      * and immediately after the next element that would have been
37      * returned by {@link #previous}, if any.
38      * <p/>
39      * The new element is inserted immediately before the implied
40      * cursor. A subsequent call to {@link #previous} will return
41      * the added element, a subsequent call to {@link #next} will
42      * be unaffected. This call increases by one the value that
43      * would be returned by a call to {@link #nextIndex} or
44      * {@link #previousIndex}.
45      *
46      * @param element the value to be inserted
47      *
48      * @throws UnsupportedOperationException when this operation is not
49      * supported
50      * @throws IllegalArgumentException if some aspect of the specified element
51      * prevents it from being added
52      */
53     void add(byte element);
54
55     /**
56      * Returns <code>true</code> iff I have more elements
57      * when traversed in the forward direction.
58      * (In other words, returns <code>true</code> iff
59      * a call to {@link #next} will return an element
60      * rather than throwing an exception.
61      *
62      * @return <code>true</code> iff I have more elements when
63      * traversed in the forward direction
64      */
65     boolean hasNext();
66     
67     /**
68      * Returns <code>true</code> iff I have more elements
69      * when traversed in the reverse direction.
70      * (In other words, returns <code>true</code> iff
71      * a call to {@link #previous} will return an element
72      * rather than throwing an exception.
73      *
74      * @return <code>true</code> iff I have more elements when
75      * traversed in the reverse direction
76      */
77     boolean hasPrevious();
78
79     /**
80      * Returns the next element in me when traversed in the
81      * forward direction.
82      *
83      * @return the next element in me
84      * @throws java.util.NoSuchElementException if there is no next element
85      */
86     byte next();
87     
88     /**
89      * Returns the index of the element that would be returned
90      * by a subsequent call to {@link #next}, or the number
91      * of elements in my iteration if I have no next element.
92      *
93      * @return the index of the next element in me
94      */
95     int nextIndex();
96
97     /**
98      * Returns the next element in me when traversed in the
99      * reverse direction.
100      *
101      * @return the previous element in me
102      * @throws java.util.NoSuchElementException if there is no previous element
103      */
104     byte previous();
105
106     /**
107      * Returns the index of the element that would be returned
108      * by a subsequent call to {@link #previous}, or
109      * <code>-1</code> if I have no previous element.
110      *
111      * @return the index of the previous element in me
112      */
113     int previousIndex();
114
115     /**
116      * Removes from my underlying collection the last
117      * element returned by {@link #next} or {@link #previous}
118      * (optional operation).
119      *
120      * @throws UnsupportedOperationException if this operation is not
121      * supported
122      * @throws IllegalStateException if neither {@link #next} nor
123      * {@link #previous} has yet been called, or
124      * {@link #remove} or {@link #add} has already been called since
125      * the last call to {@link #next} or {@link #previous}.
126      */
127     void remove();
128
129     /**
130      * Replaces in my underlying collection the last
131      * element returned by {@link #next} or {@link #previous}
132      * with the specified value (optional operation).
133      *
134      * @param element the value to replace the last returned element with
135      * @throws UnsupportedOperationException if this operation is not
136      * supported
137      * @throws IllegalStateException if neither {@link #next} nor
138      * {@link #previous} has yet been called, or
139      * {@link #remove} or {@link #add} has already been called since
140      * the last call to {@link #next} or {@link #previous}.
141      * @throws IllegalArgumentException if some aspect of the specified element
142      * prevents it from being added
143      */
144     void set(byte element);
145 }
146
Popular Tags