Module  java.base
软件包  java.util

Class AbstractList<E>

  • All Implemented Interfaces:
    Iterable<E> ， Collection<E> ， List<E>
    已知直接子类：
    AbstractSequentialList ， ArrayList ， ObservableListBase ， Vector 

    public abstract class AbstractList<E>
extends AbstractCollection<E>
implements List<E>
    该类提供了List接口的骨架实现，以最小化实现由“随机存取”数据存储（如阵列）支持的此接口所需的工作量。 对于顺序访问数据（例如链接列表），应该使用AbstractSequentialList优先于此类。

    要实现一个不可修改的列表，程序员只需要扩展这个类并提供get(int)和size()方法的实现。

    要实现可修改的列表，程序员必须另外覆盖set(int, E)方法（否则将抛出一个UnsupportedOperationException ）。 如果列表是可变大小，则程序员必须另外覆盖add(int, E)和remove(int)方法。

    根据Collection接口规范中的建议，程序员通常应该提供一个void（无参数）和集合构造函数。

    不像其他的抽象集合实现，程序员不必提供迭代器实现; 迭代器和列表迭代器由此类实现的，对的“随机访问”方法顶部： get(int) ， set(int, E) ， add(int, E)和remove(int) 。

    该类中每个非抽象方法的文档详细描述了其实现。 如果正在实施的集合承认更有效的实现，则可以覆盖这些方法中的每一种。

    这个类是Java Collections Framework的成员。

    从以下版本开始：
    1.2

    • 字段详细信息

      • modCount

        protected transient int modCount
        此列表已被结构修改的次数 。 结构修改是改变列表大小的那些修改，或以其他方式扰乱它，使得正在进行的迭代可能产生不正确的结果。

        该字段由迭代器和列表迭代器实现使用，由iterator和listIterator方法返回。 如果该字段的值意外更改，迭代器（或列表迭代器）将抛出ConcurrentModificationException响应next ， remove ， previous ， set或者add操作。 这提供了故障快速行为，而不是面对在迭代期间的并发修改的非确定性行为。

        子类使用此字段是可选的。 如果一个子类希望提供故障快速迭代器（和列表迭代器），那么它只需要在其add(int, E)和remove(int)方法（以及它覆盖的任何其他方法导致对列表的结构修改）中增加该字段。 对add(int, E)或remove(int)单个调用必须在此字段中添加不超过一个，否则迭代器（和列表迭代器）将抛出伪造ConcurrentModificationExceptions 。 如果实现不希望提供故障快速迭代器，则该字段可能会被忽略。

    • 构造方法详细信息

      • AbstractList

        protected AbstractList​()
        唯一的构造函数。 （用于子类构造函数的调用，通常是隐式的。）

    • 方法详细信息

      • add

        public boolean add​(E e)
        将指定的元素追加到此列表的末尾（可选操作）。

        支持此操作的列表可能会限制可能添加到此列表中的元素。 特别地，一些列表将拒绝添加null元素，而其他列表将对可能添加的元素的类型施加限制。 列表类应在其文档中明确指定可能添加哪些元素的限制。

        Specified by:
        add在接口 Collection<E>
        Specified by:
        add在接口 List<E>
        重写：
        add在 AbstractCollection<E>
        实现要求：
        此实现调用add(size(), e) 。

        请注意，除非add(int, E)被覆盖，否则此实现将抛出UnsupportedOperationException 。

        参数
        e - 要附加到此列表的元素
        结果
        true （由 Collection.add(E)指定）
        异常
        UnsupportedOperationException - 如果此列表不支持 add操作
        ClassCastException - 如果指定元素的类阻止将其添加到此列表中
        NullPointerException - 如果指定的元素为空，并且该列表不允许空元素
        IllegalArgumentException - 如果此元素的某些属性阻止将其添加到此列表中

      • get

        public abstract E get​(int index)
        返回此列表中指定位置的元素。
        Specified by:
        get在接口 List<E>
        参数
        index - 要返回的元素的索引
        结果
        该列表中指定位置的元素
        异常
        IndexOutOfBoundsException - 如果索引超出范围（ index < 0 || index >= size() ）

      • set

        public E set​(int index,
             E element)
        用指定的元素（可选操作）替换此列表中指定位置的元素。
        Specified by:
        set在接口 List<E>
        实现要求：
        这个实现总是抛出一个 UnsupportedOperationException 。
        参数
        index - 要替换的元素的索引
        element - 要存储在指定位置的元素
        结果
        该元素以前在指定的位置
        异常
        UnsupportedOperationException - 如果此列表不支持 set操作
        ClassCastException - 如果指定元素的类阻止将其添加到此列表中
        NullPointerException - 如果指定的元素为空，并且该列表不允许空元素
        IllegalArgumentException - 如果指定元素的某些属性阻止将其添加到此列表
        IndexOutOfBoundsException - 如果索引超出范围（ index < 0 || index >= size() ）

      • add

        public void add​(int index,
                E element)
        将指定的元素插入此列表中的指定位置（可选操作）。 将当前位于该位置的元素（如果有）和任何后续元素（向其索引添加一个）移动。
        Specified by:
        add在接口 List<E>
        实现要求：
        这个实现总是抛出一个 UnsupportedOperationException 。
        参数
        index - 要在其中插入指定元素的索引
        element - 要插入的元素
        异常
        UnsupportedOperationException - 如果此列表不支持 add操作
        ClassCastException - 如果指定元素的类阻止将其添加到此列表中
        NullPointerException - 如果指定的元素为空，并且此列表不允许空元素
        IllegalArgumentException - 如果指定元素的某些属性阻止将其添加到此列表中
        IndexOutOfBoundsException - 如果索引超出范围（ index < 0 || index > size() ）

      • remove

        public E remove​(int index)
        删除该列表中指定位置的元素（可选操作）。 将任何后续元素移动到左侧（从其索引中减去一个元素）。 返回从列表中删除的元素。
        Specified by:
        remove在接口 List<E>
        实现要求：
        这个实现总是抛出一个 UnsupportedOperationException 。
        参数
        index - 要删除的元素的索引
        结果
        该元素以前在指定的位置
        异常
        UnsupportedOperationException - 如果此列表不支持 remove操作
        IndexOutOfBoundsException - 如果索引超出范围（ index < 0 || index >= size() ）

      • indexOf

        public int indexOf​(Object o)
        返回此列表中指定元素的第一次出现的索引，如果此列表不包含元素，则返回-1。 更正式地说，返回指数最低i这样Objects.equals(o, get(i)) ，或-1，如果没有这样的指标。
        Specified by:
        indexOf在接口 List<E>
        实现要求：
        这个实现首先得到一个列表迭代器（带有listIterator() ）。 然后，它遍历列表，直到找到指定的元素或达到列表的结尾。
        参数
        o - 要搜索的元素
        结果
        此列表中指定元素的首次出现的索引，如果此列表不包含元素，则为-1
        异常
        ClassCastException - 如果指定元素的类型与此列表不兼容（ optional ）
        NullPointerException - 如果指定的元素为空，此列表不允许空元素（ optional ）

      • lastIndexOf

        public int lastIndexOf​(Object o)
        返回此列表中指定元素的最后一次出现的索引，如果此列表不包含元素，则返回-1。 更正式地说，返回满足i这样Objects.equals(o, get(i)) ，或-1，如果没有这样的指标。
        Specified by:
        lastIndexOf在接口 List<E>
        实现要求：
        这个实现首先得到一个列表迭代器，它指向列表的末尾（带有listIterator(size()) ）。 然后，它在列表中向后迭代，直到找到指定的元素，或者到达列表的开头。
        参数
        o - 要搜索的元素
        结果
        此列表中指定元素的最后一次出现的索引，如果此列表不包含元素，则为-1
        异常
        ClassCastException - 如果指定元素的类型与此列表不兼容（ optional ）
        NullPointerException - 如果指定的元素为空，并且该列表不允许空元素（ optional ）

      • clear

        public void clear​()
        从此列表中删除所有元素（可选操作）。 此呼叫返回后，列表将为空。
        Specified by:
        clear在接口 Collection<E>
        Specified by:
        clear在接口 List<E>
        重写：
        clear在 AbstractCollection<E>
        实现要求：
        此实现调用removeRange(0, size()) 。

        请注意，此实现将抛出UnsupportedOperationException除非remove(int index)或removeRange(int fromIndex, int toIndex)被覆盖。

        异常
        UnsupportedOperationException - 如果此列表不支持 clear操作

      • addAll

        public boolean addAll​(int index,
                      Collection<? extends E> c)
        将指定集合中的所有元素插入到此列表中的指定位置（可选操作）。 将当前位于该位置（如果有的话）的元素和随后的任何元素移动到右边（增加其索引）。 新元素将按照指定集合的迭代器返回的顺序显示在此列表中。 如果在操作进行中修改了指定的集合，则此操作的行为是未定义的。 （注意，如果指定的集合是此列表，并且它是非空的，则会发生这种情况。）
        Specified by:
        addAll在接口 List<E>
        实现要求：
        此实现在指定的集合中获取迭代器，并对其进行迭代，将使用add(int, E)将迭代器获取的元素插入到该列表中的适当位置，每次一个。 许多实现将覆盖此方法的效率。

        请注意，此实现将抛出一个UnsupportedOperationException除非add(int, E)被覆盖。

        参数
        index - 从中指定集合插入第一个元素的索引
        c - 包含要添加到此列表的元素的集合
        结果
        true如果此列表因呼叫而更改
        异常
        UnsupportedOperationException - 如果此列表不支持 addAll操作
        ClassCastException - 如果指定集合的元素的类阻止将其添加到此列表
        NullPointerException - 如果指定的集合包含一个或多个空元素，并且此列表不允许空元素，或者如果指定的集合为空
        IllegalArgumentException - 如果指定集合的元素的某些属性阻止其添加到此列表
        IndexOutOfBoundsException - 如果索引超出范围（ index < 0 || index > size() ）

      • iterator

        public Iterator<E> iterator​()
        以正确的顺序返回该列表中的元素的迭代器。
        Specified by:
        iterator在接口 Collection<E>
        Specified by:
        iterator在接口 Iterable<E>
        Specified by:
        iterator在接口 List<E>
        Specified by:
        iterator在 AbstractCollection<E>
        实现要求：
        此实现返回一个简单的实现Iterator接口，依托后台列表的size() ， get(int) ，并remove(int)方法。

        请注意，该方法返回的迭代器将抛出一个UnsupportedOperationException，以响应其remove方法，除非列表的remove(int)方法被覆盖。

        这种实现可以在面对并发修改时抛出运行时异常，如（protected） modCount字段的说明中所述。

        结果
        在这个列表中的元素以适当的顺序迭代

      • listIterator

        public ListIterator<E> listIterator​()
        返回列表中的列表迭代器（按适当的顺序）。
        Specified by:
        listIterator在接口 List<E>
        实现要求：
        此实现返回 listIterator(0) 。
        结果
        在列表中的元素的列表迭代器（按适当的顺序）
        另请参见：
        listIterator(int)

      • listIterator

        public ListIterator<E> listIterator​(int index)
        从列表中的指定位置开始，返回列表中的元素（按正确顺序）的列表迭代器。 指定的索引指示由初始调用next返回的第一个元素。 初始调用previous将返回指定索引减1的元素。
        Specified by:
        listIterator在接口 List<E>
        实现要求：
        该实现返回了ListIterator接口的直接实现，扩展了iterator()方法返回的Iterator接口的实现。 该ListIterator实现依赖于后台列表的get(int) ， set(int, E) ， add(int, E)和remove(int)方法。

        请注意，此实现返回的列表迭代器将抛出一个UnsupportedOperationException响应其remove ， set和add方法，除非列表的remove(int) ， set(int, E) ，并add(int, E)方法被覆盖。

        如同（protected） modCount字段的规范中所描述的那样，这种实现可以面对并发修改来抛出运行时异常。

        参数
        index - 要从列表迭代器返回的第一个元素的索引（通过调用 next ）
        结果
        在列表中的元素（按正确顺序）的列表迭代器，从列表中的指定位置开始
        异常
        IndexOutOfBoundsException - 如果索引超出范围（ index < 0 || index > size() ）

      • subList

        public List<E> subList​(int fromIndex,
                       int toIndex)
        返回指定的fromIndex （含）和toIndex之间的列表部分的视图。 （如果fromIndex和toIndex相等，返回的列表为空。）返回的列表由此列表支持，因此返回列表中的非结构更改将反映在此列表中，反之亦然。 返回的列表支持此列表支持的所有可选列表操作。

        该方法消除了对显式范围操作（对于数组通常存在的排序）的需要。 任何期望列表的操作都可以通过传递一个子列表视图而不是整个列表来用作范围操作。 例如，以下成语从列表中移除了一系列元素： 

           list.subList(from, to).clear();
        可以为indexOf和lastIndexOf构造类似的成语，并且Collections类中的所有算法都可以应用于子列表。

        如果支持列表（即，此列表）以除了通过返回的列表之外的任何方式进行结构修改 ，则此方法返回的列表的语义将变为未定义。 （结构修改是那些改变此列表的大小，或以其他方式扰乱它，使得正在进行的迭代可能产生不正确的结果）。

        Specified by:
        subList在接口 List<E>
        实现要求：
        此实现返回一个子类AbstractList的列表。 子类门店，在私人领域，subList的大小（可以在其生命周期变化），与预期modCount后台列表的价值。 子类有两个变体，其中一个实现了RandomAccess 。 如果此列表实现RandomAccess则返回的列表将是实现RandomAccess的子类的实例。

        子类的set(int, E) ， get(int) ， add(int, E) ， remove(int) ， addAll(int, Collection)和removeRange(int, int)方法都委托给支持抽象列表上的相应方法，边界检查的指标和调整偏移后。 addAll(Collection c)方法只返回addAll(size, c) 。

        listIterator(int)方法通过支持列表上的列表迭代器返回“包装对象”，后者列表中使用相应的方法创建。 iterator方法只返回listIterator() ，而size方法只返回子类的size字段。

        所有方法首先检查一下后备列表的实际modCount是否等于其预期值，如果不是，则抛出一个ConcurrentModificationException 。

        参数
        fromIndex - 子列表的低端点（含）
        toIndex - 子列表的高端点（排他性）
        结果
        该列表中指定范围的视图
        异常
        IndexOutOfBoundsException - 如果端点索引值超出范围 (fromIndex < 0 || toIndex > size)
        IllegalArgumentException - 如果端点索引不正确 (fromIndex > toIndex)

      • equals

        public boolean equals​(Object o)
        将指定的对象与此列表进行比较以获得相等性。 返回true当且仅当指定的对象也是列表时，两个列表都具有相同的大小，并且两个列表中所有相应的元素对相等 。 （两个元素e1和e2如果为(e1==null ? e2==null : e1.equals(e2)) 等于 (e1==null ? e2==null : e1.equals(e2)) ）。换句话说，如果两个列表以相同的顺序包含相同的元素，则它们被定义为相等。
        Specified by:
        equals在接口 Collection<E>
        Specified by:
        equals在接口 List<E>
        重写：
        equals在 Object
        实现要求：
        此实现首先检查指定的对象是否是此列表。 如果是，则返回true ; 如果不是，它检查指定的对象是否是一个列表。 如果没有，则返回false ; 如果是这样，它会遍历两个列表，比较相应的元素对。 如果任何比较返回false ，此方法返回false 。 如果任何一个迭代器在其他元素之前用尽，则返回false （因为列表长度不等）; 否则返回true当迭代完成。
        参数
        o - 要与此列表相等的对象进行比较
        结果
        true如果指定的对象等于此列表
        另请参见：
        Object.hashCode() ， HashMap

      • removeRange

        protected void removeRange​(int fromIndex,
                           int toIndex)
        从此列表中删除所有索引为fromIndex （含）和toIndex之间的元素。 将任何后续元素移动到左侧（减少其索引）。 此电话(toIndex - fromIndex)列表(toIndex - fromIndex)元素。 （如果是toIndex==fromIndex ，这个操作没有效果）

        此方法由该列表及其子列表中的clear操作调用。 覆盖此方法以利用列表实现的内部结构可以大大提高此列表及其子列表中的clear操作的性能。

        实现要求：
        此实现获取位于fromIndex之前的列表迭代器，并重复调用ListIterator.next后跟ListIterator.remove直到整个范围已被删除。 注意：如果ListIterator.remove需要线性时间，则此实现需要二次时间。
        参数
        fromIndex - 要删除的第一个元素的索引
        toIndex - 要删除的最后一个元素后的索引