View Javadoc

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 03:14:21 -0500 (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 }