Método list() de Java java.nio.file.Files

Java File Java java.nio.file.Files

java.nio.file.Files.list()Es un método de utilidad proporcionado en el paquete Java NIO (New I/O), utilizado para listar el contenido de un directorio. Este método devuelve unStream<Path>objeto que contiene todas las entradas (archivos y subdirectorios) del directorio especificado.

Definición del método

public static Stream<Path> list(Path dir) throws IOException

Parámetros del método

Parámetro dir

  • Tipo：java.nio.file.Path
  • Descripción: la ruta del directorio cuyo contenido se va a listar
  • Notas：
    • Si el parámetro no es un directorio, se lanzaráNotDirectoryException
    • La ruta debe existir; de lo contrario, se lanzaráNoSuchFileException
    • Si el programa no tiene permiso de lectura sobre el directorio, se lanzaráAccessDeniedException

Valor de retorno

Stream

  • Descripción: un flujo (stream) que contiene todas las entradas (archivos y subdirectorios) del directorio
  • Propiedades：
    • Los elementos del flujo sonPathobjetos
    • El flujo está ordenado según el orden natural de las entradas del directorio (generalmente ordenadas por nombre)
    • El flujo es de carga diferida (lazy); el contenido del directorio solo se lee realmente cuando se itera
    • Es necesario cerrar correctamente el flujo para liberar recursos del sistema

Características del método

1. No recursivo

list()El método solo lista las entradas directamente ubicadas en el directorio especificado; no lista recursivamente el contenido de los subdirectorios.

2. No incluye entradas especiales

El flujo devuelto no incluye las entradas del directorio en sí (".") ni del directorio padre ("..").

3. Gestión de recursos

Dado que se devuelve un Stream, se recomienda utilizar la sentencia try-with-resources para asegurar que el flujo se cierre correctamente:

Ejemplo

try (Stream<Path> stream = Files.list(Paths.get("/path/to/dir"))) {
    stream.forEach(System.out::println);
}

Ejemplo de uso

Uso básico: listar el contenido de un directorio

Ejemplo

import java.io.IOException;
import java.nio.file.Files;
import java.nio.file.Path;
import java.nio.file.Paths;
import java.util.stream.Stream;

public class ListDirectoryExample {
    public static void main(String[] args) {
        Path dir = Paths.get("C:/example");
       
        try (Stream<Path> stream = Files.list(dir)) {
            stream.forEach(System.out::println);
        } catch (IOException e) {
            e.printStackTrace();
        }
    }
}

Uso avanzado: filtrar archivos específicos

Ejemplo

try (Stream<Path> stream = Files.list(Paths.get("/projects"))) {
    stream.filter(path -> path.toString().endsWith(".java"))
          .forEach(System.out::println);
} catch (IOException e) {
    e.printStackTrace();
}

Convertir a otras colecciones

Ejemplo

try (Stream<Path> stream = Files.list(Paths.get("/images"))) {
    List<Path> imageFiles = stream.collect(Collectors.toList());
    // Procesar la lista de archivos recopilados
} catch (IOException e) {
    e.printStackTrace();
}

Manejo de excepciones

Files.list()El método puede lanzar las siguientes excepciones:

  1. NotDirectoryException- Cuando la ruta no es un directorio
  2. NoSuchFileException- Cuando el directorio no existe
  3. SecurityException- Cuando no hay permiso para leer el directorio
  4. IOException- Cuando ocurre otro error de E/S

Consideraciones de rendimiento

  1. Carga diferida: el flujo es de carga diferida; el directorio solo se lee realmente cuando se ejecuta una operación terminal (como forEach)
  2. Consumo de recursos: para directorios con muchos archivos, usar un flujo puede evitar cargar todas las entradas en la memoria de una sola vez
  3. Procesamiento paralelo: se puede llamar aparallel()método para implementar procesamiento paralelo, pero hay que prestar atención a los problemas de seguridad de hilos

Comparación con métodos similares

Método Tipo de retorno Recursividad Incluye entradas especiales Observaciones
Files.list() Stream<Path> no no Recomendado, respetuoso con los recursos
File.listFiles() File[] no no Método IO tradicional
Files.walk() Stream<Path> Sí Sí Lista recursivamente todo el contenido
Files.newDirectoryStream() DirectoryStream<Path> no no Debe cerrarse manualmente

Buenas prácticas

  1. Usar siempre try-with-resources: asegurar que el flujo se cierre correctamente
  2. Manejar excepciones: manejar adecuadamente la posible IOException
  3. Considerar el uso de filtros: filtrar lo antes posible las entradas innecesarias en las operaciones del flujo
  4. Evitar modificar el directorio: no modificar el contenido del directorio mientras se recorre
  5. Prestar atención a los enlaces simbólicos: por defecto se siguen los enlaces simbólicos, lo que puede provocar referencias circulares

Resumen

Files.list()El método es una forma moderna de manejar el contenido de directorios en Java NIO; proporciona todas las ventajas de la API de flujo, incluyendo ejecución diferida, operaciones encadenadas y capacidad de procesamiento paralelo. Para necesidades simples de listado de directorios, comparado con el métodoFile.listFiles()tradicional, el método es más flexible y eficiente.

Java File Java java.nio.file.Files

Otras extensiones