[源码解析]Collections

【版权声明】未经博主同意，谢绝转载！（请尊重原创，博主保留追究权）
https://blog.csdn.net/m0_69908381/article/details/130313129
出自【进步*于辰的博客】

注：列表类：ArrayList<E>。

1、概述

继承关系：

• java.lang.Object
  • java.util.Collections

---

public class Collections extends Object

此类完全由在 collection 上进行操作或返回 collection 的静态方法组成。它包含在 collection 上操作的多态算法，即“包装器”，包装器返回由指定 collection 支持的新 collection，以及少数其他内容。

如果为此类的方法所提供的 collection 或类对象为 null，则这些方法都会抛出 NullPointerException。

此类中所含多态算法的文档通常都包括对实现 的简短描述。应该将这类实现视为实现注意事项，而不是将它们视为规范 的一部分。实现者应该可以随意使用其他算法替代，只要遵循规范本身即可。（例如，sort 使用的算法不一定是一个合并排序算法，但它必须是稳定的。）

如果该 collection 不支持适当的可变基元，比如 set 方法，则此类中包含的“破坏性”算法，即可修改其所操作的 collection 的算法，被指定抛出 UnsupportedOperationException。如果调用不会对 collection 产生任何影响，那么这些算法可能（但不一定）抛出此异常。例如，在已经排序的、不可修改列表上调用 sort 方法可能会（也可能不会）抛出 UnsupportedOperationException。

此类是 Java Collections Framework 的成员。

从以下版本开始：
1.2
另请参见：
Collection、Set、List、Map

2、方法摘要

2.1 static <T> boolean addAll(Collection<? super T> c, T… a)

将所有指定元素添加到指定 collection 中。

public static <T> boolean addAll(Collection<? super T> c, T... elements) {
    boolean result = false;
    for (T element : elements)
        result |= c.add(element);
    return result;
}

若返回 true，不能说明全部添加成功，因为|=。

2.2 static <T> int binarySearch(List<? extends Comparable<? super T>> list, T key)

使用二进制搜索算法来搜索指定列表，以获得指定对象。

public static <T> int binarySearch(List<? extends Comparable<? super T>> list, T key) {
    if (list instanceof RandomAccess || list.size()<BINARYSEARCH_THRESHOLD)
        return Collections.indexedBinarySearch(list, key);
    else
        return Collections.iteratorBinarySearch(list, key);
}

诸如此类方法的底层逻辑，可参考Arrays类的第2.2项。

2.3 static <T> int binarySearch(List<? extends T> list, T key, Comparator<? super T> c)

使用二进制搜索算法来搜索指定列表，以获得指定对象。同上1项。

public static <T> int binarySearch(List<? extends T> list, T key, Comparator<? super T> c) {
    if (c==null)
        return binarySearch((List<? extends Comparable<? super T>>) list, key);

    if (list instanceof RandomAccess || list.size()<BINARYSEARCH_THRESHOLD)
        return Collections.indexedBinarySearch(list, key, c);
    else
        return Collections.iteratorBinarySearch(list, key, c);
}

后续解析。

2.4 static <E> Collection<E> checkedCollection(Collection<E> c, Class<E> type)

返回指定 collection 的一个动态类型安全视图。

2.5 static <E> List checkedList(List<E> list, Class<E> type)

返回指定列表的一个动态类型安全视图。

2.6 static <K, V> Map<K, V> checkedMap(Map<K, V> m, Class<K> keyType, Class<V> valueType)

返回指定映射的一个动态类型安全视图。

2.7 static <E> Set<E> checkedSet(Set<E> s, Class type)

返回指定 set 的一个动态类型安全视图。

2.8 static <K, V> SortedMap<K, V> checkedSortedMap(SortedMap<K, V> m, Class<K> keyType, Class<V> valueType)

返回指定有序映射的一个动态类型安全视图。

2.9 static <E> SortedSet<E> checkedSortedSet(SortedSet<E> s, Class type)

返回指定有序 set 的一个动态类型安全视图。

2.10 static <T> void copy(List<? super T> dest, List<? extends T> src)

将所有元素从一个列表复制到另一个列表。

public static <T> void copy(List<? super T> dest, List<? extends T> src) {
    int srcSize = src.size();
    if (srcSize > dest.size())
        throw new IndexOutOfBoundsException("Source does not fit in dest");

    if (srcSize < COPY_THRESHOLD ||// COPY_THRESHOLD 为 10，暂不知其用途
        (src instanceof RandomAccess && dest instanceof RandomAccess)) {
        for (int i=0; i<srcSize; i++)
            dest.set(i, src.get(i));
    } else {// ------A
        ListIterator<? super T> di=dest.listIterator();
        ListIterator<? extends T> si=src.listIterator();
        for (int i=0; i<srcSize; i++) {
            di.next();
            di.set(si.next());
        }
    }
}

诸如 ArrayList、Vector、Arrays$ArrayList 等类都是接口 List 与 RandomAccess 的子类，不过，接口 List 与 RandomAccess 的子类范围也有很多不同，咱不清楚哪些情况下 A 会执行，后续说明。

关于set()/get()，若dest/src是由 ArrayList 类上转而来，可参考列表类的第3.11、3.14项。

其他源码都比较简单，大家了解 ListIterator 类（见列表类的第8项）的底层结构就明白了。

示例：

List list1 = Arrays.asList('#', '#', 'd', 'n');
List list2 = Arrays.asList('c', 's');
Collections.copy(list1, list2);
sout list1;// [c, s, d, n]

2.11 static boolean disjoint(Collection<?> c1, Collection<?> c2)

如果两个指定 collection 中没有相同的元素，则返回 true。

2.12 static <T> List emptyList()

返回空的列表（不可变的）。

2.13 static <K, V> Map<K, V> emptyMap()

返回空的映射（不可变的）。

2.14 static <T> Set emptySet()

返回空的 set（不可变的）。

2.15 static <T> Enumeration<T> enumeration(Collection<T> c) `

返回一个指定 collection 上的枚举。

2.16 static <T> void fill(List<? super T> list, T obj)

使用指定元素替换指定列表中的所有元素。

public static <T> void fill(List<? super T> list, T obj) {
    int size = list.size();

    if (size < FILL_THRESHOLD || list instanceof RandomAccess) {
        for (int i=0; i<size; i++)
            list.set(i, obj);
    } else {
        ListIterator<? super T> itr = list.listIterator();
        for (int i=0; i<size; i++) {
            itr.next();
            itr.set(obj);
        }
    }
}

2.17 static int frequency(Collection<?> c, Object o)

返回指定 collection 中等于指定对象的元素数。（统计元素个数）

public static int frequency(Collection<?> c, Object o) {
    int result = 0;
    // 之所以分两种情况，是为了防止空指针异常
    if (o == null) {
        for (Object e : c)
            if (e == null)
                result++;
    } else {
        for (Object e : c)
            if (o.equals(e))
                result++;
    }
    return result;
}

2.18 static int indexOfSubList(List<?> source, List<?> target)

返回指定源列表中第一次出现指定目标列表的起始位置，如果没有出现这样的列表，则返回 -1。

public static int indexOfSubList(List<?> source, List<?> target) {
    int sourceSize = source.size();
    int targetSize = target.size();
    int maxCandidate = sourceSize - targetSize;

    if (sourceSize < INDEXOFSUBLIST_THRESHOLD ||
        (source instanceof RandomAccess&&target instanceof RandomAccess)) {
    nextCand:
        for (int candidate = 0; candidate <= maxCandidate; candidate++) {
            for (int i=0, j=candidate; i<targetSize; i++, j++)
                if (!eq(target.get(i), source.get(j)))
                    continue nextCand;  // Element mismatch, try next cand
            return candidate;  // All elements of candidate matched target
        }
    } else {  // Iterator version of above algorithm
        ListIterator<?> si = source.listIterator();
    nextCand:
        for (int candidate = 0; candidate <= maxCandidate; candidate++) {
            ListIterator<?> ti = target.listIterator();
            for (int i=0; i<targetSize; i++) {
                if (!eq(ti.next(), si.next())) {
                    // Back up source iterator to next candidate
                    for (int j=0; j<i; j++)
                        si.previous();
                    continue nextCand;
                }
            }
            return candidate;
        }
    }
    return -1;  // No candidate matched the target
}

底层逻辑可参考String类的第2.23项。

后续解析。

示例：

List<Integer> list1 = Arrays.asList(2, 1);
List<Integer> list2 = Arrays.asList(1, 2, 1, 3, 1);
sout Collections.indexOfSubList(list2, list2);// 打印：0
sout Collections.indexOfSubList(list2, list1);// 打印：1

2.19 static int lastIndexOfSubList(List<?> source, List<?> target)

返回指定源列表中最后一次出现指定目标列表的起始位置，如果没有出现这样的列表，则返回 -1。

说明：

业务类似上1项，可参考String类的第2.28项。

2.20 static <T> ArrayList<T> list(Enumeration<T> e)

返回一个数组列表，它按照枚举返回元素的顺序包含指定枚举返回的元素。

public static <T> ArrayList<T> list(Enumeration<T> e) {
    ArrayList<T> l = new ArrayList<>();
    while (e.hasMoreElements())
        l.add(e.nextElement());
    return l;
}

2.21 static <T extends Object & Comparable<? super T>> T max(Collection<? extends T> coll)

根据元素的自然顺序，返回给定 collection 的最大元素。

示例。

List<Integer> list = Arrays.asList(1, 21, 231, 81, 0);
int max = Collections.max(list);
sout max;// 打印：231

2.22 static <T> T max(Collection<? extends T> coll, Comparator<? super T> comp)

根据指定比较器产生的顺序，返回给定 collection 的最大元素。

2.23 static <T extends Object & Comparable<? super T>> T min(Collection<? extends T> coll)

根据元素的自然顺序，返回给定 collection 的最小元素。

与21项的区别就是图中红框部分。

2.24 static <T>T min(Collection<? extends T> coll, Comparator<? super T> comp)

根据指定比较器产生的顺序，返回给定 collection 的最小元素。

2.25 static <T> List<T> nCopies(int n, T o)

返回由指定对象的 n 个副本组成的不可变列表。

public static <T> List<T> nCopies(int n, T o) {
    if (n < 0)
        throw new IllegalArgumentException("List length = " + n);
    return new CopiesList<>(n, o);
}

后续解析。

示例：

List<String> list = Collections.nCopies(5, "csdn");
sout list;// [csdn, csdn, csdn, csdn, csdn]

2.26 static <T> boolean replaceAll(List<T> list, T oldVal, T newVal)

使用另一个值替换列表中出现的所有某一指定值。

示例：

List<String> list = Arrays.asList("bi", "li", "bi", "li");
sout list;// [bi, li, bi, li]
sout Collections.replaceAll(list, "bi", "#");// 打印：true
sout list;// [#, li, #, li]

2.27 static void reverse(List<?> list)

反转指定列表中元素的顺序。

2.28 static <T> Comparator<T> reverseOrder()

返回一个比较器，它强行反转实现 Comparable 接口那些对象 collection 上的自然顺序。

2.29 static <T> Comparator<T> reverseOrder(Comparator<T> cmp)

返回一个比较器，它强行反转指定比较器的顺序。

2.30 static void rotate(List<?> list, int distance)

根据指定的距离循环移动指定列表中的元素。

public static void rotate(List<?> list, int distance) {
    if (list instanceof RandomAccess || list.size() < ROTATE_THRESHOLD)
        rotate1(list, distance);
    else
        rotate2(list, distance);
}

示例：

rotate(Arrays.asList(1, 2, 3), 1)   →   3, 1, 2
rotate(Arrays.asList(1, 2, 3), -2)   →   3, 1, 2
rotate(Arrays.asList(1, 2, 3), 2)   →   2, 3, 1
rotate(Arrays.asList(1, 2, 3), -1)   →   2, 3, 1

可见，当distance > 0 时，右移，否则左移。

右移1位与左移2位的结果相同，右移2位与左移1位的结果相同，这就是循环。

$那究竟是如何实现的？$

int mid = -distance % size（见第3.1项），即余数，示例中size为3。

1. 当distance为-2时，余数是-2，执行mid += size，得：mid = 1；
2. 当distance为-1时，余数是-1，执行mid += size，得：mid = 2。

这也是逻辑的巧妙之处。

后续补充解析。

2.31 static void shuffle(List<?> list)

使用默认随机源随机更改指定列表的序列。

public static void shuffle(List<?> list) {
    Random rnd = r;
    if (rnd == null)
        r = rnd = new Random(); // harmless race.
    shuffle(list, rnd);
}

2.32 static void shuffle(List<?> list, Random rnd)

使用指定的随机源随机更改指定列表的序列。

public static void shuffle(List<?> list, Random rnd) {
    int size = list.size();
    if (size < SHUFFLE_THRESHOLD || list instanceof RandomAccess) {
        for (int i=size; i>1; i--)
            swap(list, i-1, rnd.nextInt(i));
    } else {
        Object[] arr = list.toArray();

        // Shuffle array
        for (int i=size; i>1; i--)
            swap(arr, i-1, rnd.nextInt(i));

        ListIterator it = list.listIterator();
        for (int i=0; i<arr.length; i++) {
            it.next();
            it.set(arr[i]);
        }
    }
}

后续解析。

说明：第31、32项

作用与rotate()（第30项）相同，只是distance是随机正数。

2.33 static <T> Set<T> singleton(T o)

返回一个只包含指定对象的不可变 set。

2.34 static <T> List<T> singletonList(T o)

返回一个只包含指定对象的不可变列表。

2.35 static <K, V> Map<K,V> singletonMap(K key, V value)

返回一个不可变的映射，它只将指定键映射到指定值。

2.36 static <T extends Comparable<? super T>> void sort(List<T> list)

根据元素的自然顺序对指定列表按升序进行排序。

public static <T extends Comparable<? super T>> void sort(List<T> list) {
    list.sort(null);
}

sort()的解析可参考ArrayList类的第3.20项。

指定Comparator接口为null，故是“自然排序”。

示例：

List<Integer> list = Arrays.asList(2, 0, 2, 3);
Collections.sort(list);
sout list;// 打印：[0, 2, 2, 3]

2.37 static <T> void sort(List<T> list, Comparator<? super T> c)

根据指定比较器产生的顺序对指定列表进行排序。

2.38 static void swap(List<?> list, int i, int j)

在指定列表的指定位置处交换元素。

public static void swap(List<?> list, int i, int j) {
    // instead of using a raw type here, it's possible to capture
    // the wildcard but it will require a call to a supplementary
    // private method
    final List l = list;
    l.set(i, l.set(j, l.get(i)));
}

从set()的注释可知，set(i, e)的作用是单元素替换，返回值是替换前元素。

因此经推演，l.set(i, l.set(j, l.get(i)))的结果是对索引i、j处的元素进行替换。

2.39 static <T> Collection<T> synchronizedCollection(Collection<T> c)

返回由指定 collection 支持的同步 collection。

2.40 static <T> List<T> synchronizedList(List<T> list)

返回由指定列表支持的同步列表。

public static <T> List<T> synchronizedList(List<T> list) {
    return (list instanceof RandomAccess ?
            new SynchronizedRandomAccessList<>(list) :
            new SynchronizedList<>(list));
}

2.41 static <K, V> Map<K, V> synchronizedMap(Map<K, V> m)

返回由指定映射支持的同步映射。

2.42 static <T> Set<T> synchronizedSet(Set<T> s)

返回由指定 set 支持的同步 set。

2.43 static <K, V> SortedMap<K, V> synchronizedSortedMap(SortedMap<K, V> m)

返回由指定有序映射支持的同步有序映射。

2.44 static <T> SortedSet<T> synchronizedSortedSet(SortedSet<T> s)

返回由指定有序 set 支持的同步有序 set。

2.45 static <T> Collection<T> unmodifiableCollection(Collection<? extends T> c)

返回指定 collection 的不可修改视图。

2.46 static <T> List<T> unmodifiableList(List<? extends T> list)

返回指定列表的不可修改视图。

public static <T> List<T> unmodifiableList(List<? extends T> list) {
    return (list instanceof RandomAccess ?
            new UnmodifiableRandomAccessList<>(list) :
            new UnmodifiableList<>(list));
}

2.47 static <K, V> Map<K, V> unmodifiableMap(Map<? extends K,? extends V> m)

返回指定映射的不可修改视图。

2.48 static <T> Set<T> unmodifiableSet(Set<? extends T> s)

返回指定 set 的不可修改视图。

2.49 static <K, V> SortedMap<K, V> unmodifiableSortedMap(SortedMap<K, ? extends V> m)

返回指定有序映射的不可修改视图。

2.50 static <T> Set<T> unmodifiableSortedSet(SortedSet<T> s) `

返回指定有序 set 的不可修改视图。

2.51 static <T> Iterator<T> emptyIterator()

返回空迭代器。

2.52 static <T> ListIterator<T> emptyListIterator()

返回空子迭代器。

3、方法摘要（不开放）

3.1 private static void rotate1(List list, int distance)

（业务不明。）

private static<T> void rotate1(List<T> list, int distance) {
    int size = list.size();
    if (size == 0)
        return;
    distance = distance % size;// 即第2.30中说的 mid
    if (distance < 0)
        distance += size;
    if (distance == 0)
        return;

    for (int cycleStart = 0, nMoved = 0; nMoved != size; cycleStart++) {
        T displaced = list.get(cycleStart);
        int i = cycleStart;
        do {
            i += distance;
            if (i >= size)
                i -= size;
            displaced = list.set(i, displaced);
            nMoved ++;
        } while (i != cycleStart);
    }
}

后续解析。

7、嵌套类SynchronizedList<E>

同步List。

预览。

static class SynchronizedList<E>
        extends SynchronizedCollection<E>
        implements List<E> {
    final List<E> list;

    SynchronizedList(List<E> list) {
        super(list);
        this.list = list;
    }
    SynchronizedList(List<E> list, Object mutex) {
        super(list, mutex);
        this.list = list;
    }
	
	public void add(int index, E element) {
        synchronized (mutex) {list.add(index, element);}
    }
    ...
}

可见，“同步”机制是通过对象锁synchronized实现的。

8、嵌套类UnmodifiableList<E>

不可修改List。

预览。

static class UnmodifiableList<E> extends UnmodifiableCollection<E>
                                  implements List<E> {
    final List<? extends E> list;

    UnmodifiableList(List<? extends E> list) {
        super(list);
        this.list = list;
    }

	public void add(int index, E element) {
        throw new UnsupportedOperationException();
    }
    ...
}

可见，之所以“不可修改”，是因为重写的相应方法的方法体没有具体业务，直接抛出异常所致。

最后

如果大家需要Java-API文档，我上传了《Java-API文档-包含5/8/11三个版本》。

---

本文暂缓更新。