Java Collections.singletonList
上次修改时间：2025 年 4 月 20 日
Collections.singletonList 方法是 Java 集合框架中的一个实用方法。它返回一个只包含指定对象的不可变列表。当您需要一个不可修改的单元素列表时，此方法非常有用。
返回的列表是可序列化的，并实现了 RandomAccess 接口。与创建一个包含一个元素的常规列表相比，它更节省空间。此方法尤其适用于需要列表的 API。
Collections.singletonList 概述
Collections.singletonList 创建一个不可变的单元素列表。该列表不能被修改 - 尝试添加、删除或设置元素将抛出 UnsupportedOperationException。这使其线程安全。
该方法是 java.util.Collections 实用程序类的一部分。它在 Java 1.3 中引入。该实现针对单元素存储进行了优化，使其在这种特定情况下比常规列表更有效。
基本 singletonList 用法
此示例演示了 Collections.singletonList 的最基本用法。我们创建一个包含一个字符串的单元素列表。该示例展示了如何创建和访问列表中的元素。
package com.zetcode;
import java.util.Collections;
import java.util.List;
public class SingletonListBasic {
public static void main(String[] args) {
// Create a single-element list
List<String> singleElementList = Collections.singletonList("Hello");
// Access the element
String element = singleElementList.get(0);
System.out.println("Element: " + element);
// Print the list
System.out.println("List: " + singleElementList);
// Size of the list
System.out.println("Size: " + singleElementList.size());
}
}
此代码创建一个只包含字符串 "Hello" 的不可变列表。然后我们使用 get(0) 访问该元素，因为它只包含一个元素。列表的大小始终为 1。
输出显示了元素值、列表表示形式，并确认了列表大小正好为 1。这演示了 singletonList 的基本行为。
尝试修改 singletonList
此示例展示了尝试修改使用 Collections.singletonList 创建的列表时会发生什么。该列表是不可变的，因此任何修改尝试都会抛出异常。
package com.zetcode;
import java.util.Collections;
import java.util.List;
public class SingletonListModification {
public static void main(String[] args) {
List<Integer> numbers = Collections.singletonList(42);
try {
// Attempt to add element
numbers.add(99);
} catch (UnsupportedOperationException e) {
System.out.println("Cannot add: " + e.getMessage());
}
try {
// Attempt to remove element
numbers.remove(0);
} catch (UnsupportedOperationException e) {
System.out.println("Cannot remove: " + e.getMessage());
}
try {
// Attempt to set element
numbers.set(0, 100);
} catch (UnsupportedOperationException e) {
System.out.println("Cannot set: " + e.getMessage());
}
// Original list remains unchanged
System.out.println("Original list: " + numbers);
}
}
此代码演示了 singletonList 的不可变性。我们尝试添加、删除和修改元素，所有这些都将失败并抛出 UnsupportedOperationException。原始列表保持不变。
输出显示了每次失败的操作和异常消息。这证实了 singletonList 确实是不可变的，并且在创建后无法修改。
将 singletonList 与 API 一起使用
此示例展示了当使用需要列表的 API 时，Collections.singletonList 如何有用。我们演示了将单个值传递给期望列表参数的方法。
package com.zetcode;
import java.util.Collections;
import java.util.List;
public class SingletonListApiUsage {
public static void main(String[] args) {
// Method that requires a List parameter
printNames(Collections.singletonList("Alice"));
// Compare with regular list creation
printNames(List.of("Bob")); // Java 9+
}
private static void printNames(List<String> names) {
System.out.println("Names:");
for (String name : names) {
System.out.println("- " + name);
}
}
}
在这里，我们使用 Collections.singletonList 将单个名称传递给期望列表的方法。这比仅为单个元素创建常规列表更有效。我们还展示了使用 List.of 的 Java 9+ 替代方案。
输出表明这两种方法都正确工作。该方法接收一个只包含一个元素的列表并相应地处理它。
singletonList 在 Collections.addAll 中
此示例演示了将 Collections.singletonList 与 Collections.addAll 一起使用。我们展示了如何使用这些方法一起将单个元素有效地添加到现有集合中。
package com.zetcode;
import java.util.ArrayList;
import java.util.Collections;
import java.util.List;
public class SingletonListWithAddAll {
public static void main(String[] args) {
List<String> colors = new ArrayList<>();
colors.add("Red");
colors.add("Green");
// Add single element using singletonList
Collections.addAll(colors, Collections.singletonList("Blue").toArray(new String[0]));
System.out.println("Colors: " + colors);
// Alternative way
colors.addAll(Collections.singletonList("Yellow"));
System.out.println("Updated colors: " + colors);
}
}
此代码展示了使用 Collections.singletonList 将单个元素添加到列表的两种方法。第一种方法使用 Collections.addAll，而第二种方法使用 List.addAll。
这两种方法都实现了相同的结果，但演示了使用 singletonList 的不同方法。输出显示了列表随着每次添加而增长。
singletonList vs Arrays.asList
此示例将 Collections.singletonList 与 Arrays.asList 在创建单元素列表时进行比较。我们重点介绍了这些方法之间的关键区别。
package com.zetcode;
import java.util.Arrays;
import java.util.Collections;
import java.util.List;
public class SingletonListVsArraysAsList {
public static void main(String[] args) {
// Using singletonList
List<String> singleton = Collections.singletonList("One");
System.out.println("singletonList: " + singleton);
// Using Arrays.asList
List<String> asList = Arrays.asList("One");
System.out.println("Arrays.asList: " + asList);
// Modification attempts
try {
asList.set(0, "Modified");
System.out.println("Modified Arrays.asList: " + asList);
} catch (Exception e) {
System.out.println("Cannot modify Arrays.asList: " + e.getMessage());
}
// Size comparison
System.out.println("singletonList size: " + singleton.size());
System.out.println("Arrays.asList size: " + asList.size());
}
}
此示例比较了创建单元素列表的两种方法。Collections.singletonList 创建一个真正的不可变列表，而 Arrays.asList 创建一个固定大小的列表，该列表允许修改元素，但不允许结构更改。
输出显示 Arrays.asList 允许修改现有元素，但不允许更改列表大小。这两个列表都报告大小为 1，但具有不同的修改功能。
singletonList 在方法返回值中
此示例演示了将 Collections.singletonList 用作方法返回值。当一个方法需要返回一个列表但只有一个值要返回时，它特别有用。
package com.zetcode;
import java.util.Collections;
import java.util.List;
public class SingletonListMethodReturn {
public static void main(String[] args) {
// Get a single search result
List<String> searchResults = searchDatabase("Java");
System.out.println("Search results: " + searchResults);
// Process the result
if (!searchResults.isEmpty()) {
System.out.println("First result: " + searchResults.get(0));
}
}
private static List<String> searchDatabase(String query) {
// Simulate database search
if ("Java".equals(query)) {
return Collections.singletonList("Java Programming");
}
return Collections.emptyList();
}
}
在这里，我们使用 Collections.singletonList 从方法返回单个搜索结果。这比返回 null 或创建完整的列表实现更简洁。调用代码可以将结果视为常规列表。
输出显示了被返回和处理的搜索结果。该方法可以为没有匹配项返回一个空列表，从而保持一致的返回类型。
singletonList 性能
此示例演示了与常规列表实现相比，Collections.singletonList 的性能优势。我们测量了这两种方法的内存使用情况和创建时间。
package com.zetcode;
import java.util.ArrayList;
import java.util.Collections;
import java.util.List;
public class SingletonListPerformance {
public static void main(String[] args) {
final int ITERATIONS = 1_000_000;
// Measure ArrayList creation
long start = System.currentTimeMillis();
for (int i = 0; i < ITERATIONS; i++) {
List<String> list = new ArrayList<>();
list.add("Item");
}
long arrayListTime = System.currentTimeMillis() - start;
// Measure singletonList creation
start = System.currentTimeMillis();
for (int i = 0; i < ITERATIONS; i++) {
List<String> list = Collections.singletonList("Item");
}
long singletonTime = System.currentTimeMillis() - start;
System.out.println("ArrayList time: " + arrayListTime + "ms");
System.out.println("singletonList time: " + singletonTime + "ms");
System.out.println("singletonList is " +
(arrayListTime / (double)singletonTime) + "x faster");
}
}
此基准测试比较了使用 ArrayList 和 Collections.singletonList 创建 1,000,000 个单元素列表。结果显示了这两种方法之间的显着性能差异。
输出表明，对于单元素列表，Collections.singletonList 速度更快，并且更节省内存。这使其成为您只需要在不可变列表中包含一个元素的情况的理想选择。
来源
Java Collections.singletonList 文档
在本文中，我们深入探讨了 Collections.singletonList 方法。我们涵盖了基本用法、不可变性、API 集成、性能以及与替代方案的比较。此方法是有效地使用单元素列表的宝贵工具。
作者
列出所有Java教程。