Java JDK7源码-java.util.ListIterator<E>

源码

1
package java.util;
2
3
public interface ListIterator<E> extends Iterator<E> {
4
5
    /**
6
     * 查询操作
7
     * 继承父接口:java.util.Iterator<E>
8
     * 当向后遍历还有元素时返回true。
9
     * 换句话说,返回ture说明仍然可以通过next()取到元素。
10
     * 若在本方法返回false时继续调用next(),则next()会抛出异常。
11
     */
12
    boolean hasNext();
13
14
    /**
15
     * 查询操作
16
     * 继承父接口:java.util.Iterator<E>
17
     * 返回listIterator当前游标后一个元素,同时游标后移一位。
18
     * 在迭代list的过程中本方法可能会被反复调用,或者与previous()交替被调用。以此控制向前或向后迭代。
19
     * 
20
     * 连续执行的情况下,以下语句均会返回当前游标的后一个元素:
21
     * listIterator.next();
22
     * listIterator.previous();
23
     * 
24
     * 连续执行的情况下,以下语句均会返回当前游标的前一个元素:
25
     * listIterator.previous();
26
     * listIterator.next();
27
     * 
28
     * @throws NoSuchElementException 游标所指的位置之后已无元素。
29
     */
30
    E next();
31
32
    /**
33
     * 查询操作
34
     * 当向前遍历还有元素时返回true。
35
     * 换句话说,返回ture说明仍然可以通过previous()取到元素。
36
     * 若在本方法返回false时继续调用previous(),则previous()会抛出异常。
37
     */
38
    boolean hasPrevious();
39
40
    /**
41
     * 查询操作
42
     * 返回listIterator当前游标前一个元素,同时游标前移一位。
43
     * 在迭代list的过程中本方法可能会被反复调用,或者与next()交替被调用。以此控制向前或向后迭代。
44
     * 
45
     * 连续执行的情况下,以下语句均会返回当前游标的后一个元素:
46
     * listIterator.next();
47
     * listIterator.previous();
48
     * 
49
     * 连续执行的情况下,以下语句均会返回当前游标的前一个元素:
50
     * listIterator.previous();
51
     * listIterator.next();
52
     * 
53
     * @throws NoSuchElementException 游标所指的位置之前已无元素。
54
     */
55
    E previous();
56
57
    /**
58
     * 查询操作
59
     * 返回listIterator当前游标后一个元素的索引。
60
     * 本操作不会移动游标。即本方法会返回下次调用next()时返回的元素的索引。
61
     * 特别的,当游标位于list末尾时,调用本方法不会抛出异常,而是会返回list的长度。
62
     */
63
    int nextIndex();
64
65
    /**
66
     * 查询操作
67
     * 返回listIterator当前游标前一个元素的索引。
68
     * 本操作不会移动游标。即本方法会返回下次调用previous()时返回的元素的索引。
69
     * 特别的,当游标位于list最左边时,调用本方法不会抛出异常,而是会返回-1。
70
     */
71
    int previousIndex();
72
73
    /**
74
     * 改变操作
75
     * 继承父接口:java.util.Iterator<E>
76
     * 本方法可选,实现类可依自身情况决定是否真的需要实现。
77
     * 
78
     * 移除上一次由next()或previous()返回的元素。
79
     * 本方法必须与next()或previous()一一配对。且每个配对之间不能调用add(E e)。
80
     * 
81
     * @throws UnsupportedOperationException listIterator不支持本方法。
82
     * @throws IllegalStateException:本方法未与next()或previous()一一配对,或配对之间调用了add(E e)。
83
     */
84
    void remove();
85
86
    /**
87
     * 改变操作
88
     * 本方法可选,实现类可依自身情况决定是否真的需要实现。
89
     * 
90
     * 用e覆盖上一次由next()或previous()返回的元素的位置的元素。
91
     * 本方法在调用前必须调用一次next()或previous(),否则不知道该覆盖哪个位置的元素。
92
     * 且在本方法与最后一次next()或previous()之间不能调用add(E e)或remove()。
93
     * 
94
     * @throws UnsupportedOperationException listIterator不支持本方法。
95
     * @throws ClassCastException e因为其所属的类禁止被插入list。
96
     * @throws IllegalArgumentException e因其某些属性禁止被插入list。
97
     * @throws IllegalStateException 本方法在调用前没有调用next()或previous(),或在本方法与最后一次next()或previous()之间调用add(E e)或remove()。
98
     */
99
    void set(E e);
100
101
    /**
102
     * 改变操作
103
     * 本方法可选,实现类可依自身情况决定是否真的需要实现。
104
     * 
105
     * 将e插入当前游标所在位置。
106
     * 若list为空,则e将成为list的第一个元素。
107
     * e插入后,当前游标位于e之后的位置。
108
     * 因此插入后第一次如果调用的是next()将返回插入前游标所指的下一个元素;第一次如果调用的是previous()将返回e。
109
     * 
110
     * 调用该方法后,若调用nextIndex()或previousIndex(),和未调用该方法之前相比值均会增加1。
111
     * 
112
     * @throws UnsupportedOperationException listIterator不支持本方法。
113
     * @throws ClassCastException e因为其所属的类禁止被插入list。
114
     * @throws IllegalArgumentException e因其某些属性禁止被插入list。
115
     */
116
    void add(E e);
117
}

已整理层级关系

直接父接口

综述

本接口是Java集合框架中的一员。是专为List接口设计的迭代器。可以双向迭代并修改list,并可获得迭代器当前的游标位置。

与父接口Iterator不同的是,ListIterator没有当前元素的概念。它的游标位置在两个元素之间。当调用previous()时将返回紧邻游标之前的一个元素同时游标前移一位;当调用next()时将返回紧邻游标之后的一个元素同时游标后移一位。

若list的长度为n,则有n+1个位置可供放置游标。形如:

1
                     Element(0)   Element(1)   Element(2)   ... Element(n-1)
2
cursor positions:  ^            ^            ^            ^                  ^

游标无法定义remove()及set(E e)。因为这两个方法操作的是元素本身而游标指向的是元素之间的位置。这两个方法必须与next()或previous()配对(remove()要求一一配对而set(E e)不需要),其操作的元素即为配对方法返回的元素。