Análisis de errores comunes al serializar colecciones

1. NotSerializableException: cuando la colección no se quiere serializar

El error más frecuente y más insidioso al serializar colecciones es java.io.NotSerializableException. Se produce si al menos un elemento de la colección no implementa la interfaz Serializable.

Veamos un ejemplo ingenuo:

import java.io.*;
import java.util.*;

class Book {
    String title;
    Book(String title) { this.title = title; }
}

public class LibraryApp {
    public static void main(String[] args) throws Exception {
        List<Book> books = new ArrayList<>();
        books.add(new Book("Dombey e hijo"));

        // Intento de serializar la colección
        try (ObjectOutputStream oos = new ObjectOutputStream(new FileOutputStream("books.ser"))) {
            oos.writeObject(books); // ¡BOOM! NotSerializableException
        }
    }
}

¿Qué ocurrirá? En la etapa oos.writeObject(books) obtendrás una excepción:

java.io.NotSerializableException: Book

¿Por qué? Porque la clase Book no implementa la interfaz Serializable. Aunque la propia colección (ArrayList) sepa serializarse, ¡los elementos de la colección deben ser serializables!

Cómo diagnosticarlo

En el error siempre se indica la clase que causó el problema: búscala en el mensaje de la excepción. Si la colección es grande y el error aparece solo bajo ciertas condiciones, es posible que algún elemento se haya añadido por accidente y no implemente Serializable.

Cómo arreglarlo

Añade implements Serializable a tu clase:

class Book implements Serializable {
    String title;
    Book(String title) { this.title = title; }
}

Consejo: Si la colección contiene distintos tipos de objetos, ¡compruébalos todos para que implementen Serializable!

2. ClassCastException al deserializar: cuando los genéricos fallan

En Java, la información sobre los parámetros genéricos de las colecciones se borra tras la compilación (type erasure). Esto significa que si serializaste List<String> y deserializas como List<Integer>, el compilador no detectará el error, pero en tiempo de ejecución obtendrás una ClassCastException.

Ejemplo:

// Serialización
List<String> names = Arrays.asList("Ana", "Boris");
try (ObjectOutputStream oos = new ObjectOutputStream(new FileOutputStream("names.ser"))) {
    oos.writeObject(names);
}

// Deserialización (¡PELIGRO!)
try (ObjectInputStream ois = new ObjectInputStream(new FileInputStream("names.ser"))) {
    List<Integer> numbers = (List<Integer>) ois.readObject(); // unchecked cast
    Integer first = numbers.get(0); // ¡BOOM! ClassCastException
}

Error:

java.lang.ClassCastException: class java.lang.String cannot be cast to class java.lang.Integer

Cómo evitarlo

• No uses colecciones sin parametrizar (raw types) ni realices conversiones de tipos si no es necesario.
• Comprueba los tipos de los elementos tras deserializar si no estás seguro de su contenido.
• Documenta qué tipo de colección se serializa y cuál se espera al leer.

Ejemplo de deserialización segura:

Object obj = ois.readObject();
if (obj instanceof List<?>) {
    List<?> list = (List<?>) obj;
    if (!list.isEmpty() && list.get(0) instanceof String) {
        @SuppressWarnings("unchecked")
        List<String> safeNames = (List<String>) obj; // la advertencia se suprime, pero el tipo se ha comprobado
    }
}

3. Cambios en la estructura de las clases: serialVersionUID y compatibilidad hacia atrás

Serializaste una colección y luego decidiste añadir un campo nuevo a la clase de los elementos, cambiar el nombre de un campo o incluso modificar la estructura de la clase. Ahora, al intentar deserializar el archivo antiguo, obtendrás un error enigmático:

java.io.InvalidClassException: Book; local class incompatible: stream classdesc serialVersionUID = 1234, local class serialVersionUID = 5678

Por qué ocurre

Cada clase serializable recibe un identificador de versión único: serialVersionUID. Si la clase ha cambiado (por ejemplo, añadiste un campo), la JVM calcula un nuevo serialVersionUID, y la deserialización ve que la versión de la clase no coincide con la que había en el momento de la serialización.

Cómo evitarlo

• Declara explícitamente serialVersionUID en tus clases:

class Book implements Serializable {
    private static final long serialVersionUID = 1L;
    String title;
    // ...
}

• Mantén la compatibilidad hacia atrás: no elimines ni renombres campos si planeas leer archivos antiguos.
• Prueba la deserialización tras los cambios.

¿Qué hacer si aun así necesitas cambiar la clase?

• Considera implementar los métodos readObject/writeObject para gestionar la serialización manualmente.
• O migra los datos: lee el archivo antiguo con la versión anterior de la clase y vuelve a guardarlo en el nuevo formato.

4. Pérdida de datos al serializar colecciones inmutables

En versiones nuevas de Java aparecieron colecciones inmutables, por ejemplo, creadas con List.of(), Set.of(), Map.of(). En versiones antiguas de Java (antes de la 12) y en algunas implementaciones de terceros, la serialización de estas colecciones puede no funcionar correctamente: después de deserializar, la colección se convierte en mutable o incluso aparece un error.

Ejemplo:

List<String> list = List.of("a", "b", "c");
try (ObjectOutputStream oos = new ObjectOutputStream(new FileOutputStream("list.ser"))) {
    oos.writeObject(list);
}

En JVM antiguas, durante la deserialización aparecía un error o la colección dejaba de ser inmutable.

Cómo evitarlo

• Consulta la documentación de la versión de Java que utilices.
• Prueba la serialización y deserialización de este tipo de colecciones.
• Si necesitas preservar la inmutabilidad, tras deserializar envuelve la colección con Collections.unmodifiableList(list).

5. Serialización de campos transient y static

Qué pasa con estos campos:

• transient: los campos marcados con esta palabra clave no se serializan en absoluto. Tras la deserialización tendrán el valor por defecto (por ejemplo, null o 0).
• static: los campos de clase (y no de instancia) nunca se serializan.

Ejemplo:

class Book implements Serializable {
    String title;
    transient String cache; // no se serializa
    static String publisher = "Default"; // tampoco se serializa
}

Por qué es importante

Si almacenas valores calculados o caché dentro del objeto, márcalos como transient: esto ahorra espacio y acelera la serialización.

Cuidado: Tras la deserialización, los campos transient deben recalcularse o inicializarse de nuevo.

6. Serialización de colecciones grandes: rendimiento y tamaño de archivo

Problemas:

• Las colecciones grandes (por ejemplo, un millón de objetos) pueden dar lugar a archivos enormes, tiempos largos de escritura y lectura e incluso a falta de memoria (OutOfMemoryError).
• Al serializar un grafo de objetos (por ejemplo, colecciones complejas interrelacionadas), el tamaño del archivo puede crecer inesperadamente.

Cómo evitarlo

• Serializa la colección por partes: por ejemplo, escribe los objetos de uno en uno o en pequeños lotes.
• Usa procesamiento en streaming: en lugar de serializar toda la colección de una vez, serializa los elementos según sea necesario.
• Comprime los archivos: usa GZIPOutputStream para reducir el tamaño del archivo.

Ejemplo de serialización en streaming:

try (ObjectOutputStream oos = new ObjectOutputStream(new FileOutputStream("books.ser"))) {
    for (Book book : bigList) {
        oos.writeObject(book);
    }
}

Atención: Con este enfoque, la deserialización requiere saber cuántos objetos se han escrito (o usar un «marcador de fin» especial).