# Class PersistenciaArchivos

java.lang.Object
Persistencia.PersistenciaArchivos

All Implemented Interfaces:
  `GestorPersistencia`

public class PersistenciaArchivos extends Object implements GestorPersistencia
Implementación de `GestorPersistencia` que almacena y recupera datos mediante ficheros de texto plano en el sistema de archivos local.

Gestiona tres tipos de almacenamiento:

- Usuarios registrados → `data/usuarios.txt`
- Estadísticas de partidas → `data/estadisticas.txt`
- Estados de partidas pausadas → `data/partidas/id.dat`

Todos los ficheros utilizan formato CSV separado por punto y coma (`;`). Los directorios necesarios se crean automáticamente en el constructor si no existen previamente.

Version:
  1.0
Author:
  JP

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `private static final String`
  `CARPETA_PARTIDAS`
  Ruta de la carpeta que contiene los ficheros de partidas pausadas.
  `private static final String`
  `DATA_ESTADISTICAS`
  Ruta del fichero que almacena el historial de estadísticas.
  `private static final String`
  `DATA_USUARIOS`
  Ruta del fichero que almacena los usuarios registrados.

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `PersistenciaArchivos()`
  Construye una instancia de `PersistenciaArchivos` y garantiza que los directorios de trabajo existen antes de cualquier operación de E/S.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `agregarEstadistica(Estadistica e)`
  Añade una estadística al final del fichero de estadísticas sin sobrescribir los registros existentes (modo append).
  `ArrayList<Estadistica>`
  `cargarEstadisticas()`
  Carga todas las estadísticas almacenadas en disco y las devuelve como lista.
  `String`
  `cargarPartidaPausada(int id)`
  Carga el estado serializado de una partida pausada desde su fichero `id.dat`.
  `ArrayList<Usuario>`
  `cargarUsuarios()`
  Lee el fichero de usuarios y reconstruye la lista de objetos del modelo.
  `void`
  `eliminarPartidaPausada(int id)`
  Elimina el fichero `id.dat` de una partida pausada.
  `void`
  `guardarPartidaPausada(int id, String estado)`
  Guarda el estado serializado de una partida pausada en un fichero denominado `id.dat` dentro de `data/partidas/`.
  `void`
  `guardarUsuarios(ArrayList<Usuario> listaUsuarios)`
  Sobrescribe el fichero de usuarios con la lista completa proporcionada.
  `ArrayList<Integer>`
  `listarPartidasPausadas()`
  Lista los identificadores de todas las partidas pausadas que hay en disco.

  ### Methods inherited from class Object

  `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- ## Field Details

  - ### DATA_USUARIOS

    private static final String DATA_USUARIOS
    Ruta del fichero que almacena los usuarios registrados.
    See Also:
      - Constant Field Values

  - ### DATA_ESTADISTICAS

    private static final String DATA_ESTADISTICAS
    Ruta del fichero que almacena el historial de estadísticas.
    See Also:
      - Constant Field Values

  - ### CARPETA_PARTIDAS

    private static final String CARPETA_PARTIDAS
    Ruta de la carpeta que contiene los ficheros de partidas pausadas.
    See Also:
      - Constant Field Values

- ## Constructor Details

  - ### PersistenciaArchivos

    public PersistenciaArchivos()
    Construye una instancia de `PersistenciaArchivos` y garantiza que los directorios de trabajo existen antes de cualquier operación de E/S.

    Si `data/` o `data/partidas/` no existen, los crea. Esto evita `IOException` en la primera ejecución de la aplicación.

- ## Method Details

  - ### guardarUsuarios

    public void guardarUsuarios(ArrayList<Usuario> listaUsuarios)
    Sobrescribe el fichero de usuarios con la lista completa proporcionada.

    Cada usuario se serializa mediante su método `Usuario.toArchivo()`, que produce una línea con el formato `username;password;esAdmin`. Se llama a este método cada vez que se registra un nuevo usuario.

    Specified by:
      `guardarUsuarios` in interface `GestorPersistencia`
    Parameters:
      `listaUsuarios` - lista de `Usuario` a persistir. No debe ser `null`.

  - ### cargarUsuarios

    public ArrayList<Usuario> cargarUsuarios()
    Lee el fichero de usuarios y reconstruye la lista de objetos del modelo.

    El formato esperado por línea es `username;password;esAdmin`. Si el tercer campo es `true`, se instancia un `Administrador`; en caso contrario, un `Jugador`. Las líneas vacías o malformadas (menos de 3 campos) se ignoran silenciosamente.

    Specified by:
      `cargarUsuarios` in interface `GestorPersistencia`
    Returns:
      lista de `Usuario` cargados desde disco. Devuelve una lista vacía si el fichero no existe todavía.

  - ### agregarEstadistica

    public void agregarEstadistica(Estadistica e)
    Añade una estadística al final del fichero de estadísticas sin sobrescribir los registros existentes (modo append).

    La estadística se serializa mediante `Estadistica.toArchivo()`, que produce una línea con el formato `username;nombreJuego;puntuacion;victoria;fecha`. La fecha se escribe en formato ISO (`yyyy-MM-dd`) gracias a `LocalDate.toString()`.

    Specified by:
      `agregarEstadistica` in interface `GestorPersistencia`
    Parameters:
      `e` - `Estadistica` a persistir. No debe ser `null`.

  - ### cargarEstadisticas

    public ArrayList<Estadistica> cargarEstadisticas()
    Carga todas las estadísticas almacenadas en disco y las devuelve como lista.

    El formato esperado por línea es `username;nombreJuego;puntuacion;victoria;fecha`. La fecha se deserializa con `LocalDate.parse(CharSequence)`, que espera formato ISO (`yyyy-MM-dd`), consistente con lo que escribe `Estadistica.toArchivo()`. Las líneas vacías o con menos de 5 campos se ignoran silenciosamente.

    Specified by:
      `cargarEstadisticas` in interface `GestorPersistencia`
    Returns:
      lista de `Estadistica` cargadas desde disco. Devuelve una lista vacía si el fichero no existe todavía.

  - ### guardarPartidaPausada

    public void guardarPartidaPausada(int id, String estado)
    Guarda el estado serializado de una partida pausada en un fichero denominado `id.dat` dentro de `data/partidas/`.

    El contenido del fichero es el String devuelto por `Juego.serializarEstado()`, cuyo formato concreto depende de cada subclase de `Juego`.

    Specified by:
      `guardarPartidaPausada` in interface `GestorPersistencia`
    Parameters:
      `id` - identificador único de la partida
      `estado` - String con el estado serializado del juego

  - ### cargarPartidaPausada

    public String cargarPartidaPausada(int id)
    Carga el estado serializado de una partida pausada desde su fichero `id.dat`.

    El String devuelto se pasa directamente a `Juego.deserializarEstado()` para reconstruir el estado interno del juego al reanudar la partida.

    Specified by:
      `cargarPartidaPausada` in interface `GestorPersistencia`
    Parameters:
      `id` - identificador de la partida a cargar
    Returns:
      String con el estado serializado, o `null` si el fichero no existe

  - ### eliminarPartidaPausada

    public void eliminarPartidaPausada(int id)
    Elimina el fichero `id.dat` de una partida pausada.

    Se invoca cuando la partida se reanuda o se descarta, para no acumular ficheros huérfanos en `data/partidas/`.

    Specified by:
      `eliminarPartidaPausada` in interface `GestorPersistencia`
    Parameters:
      `id` - identificador de la partida cuyo fichero se eliminará

  - ### listarPartidasPausadas

    public ArrayList<Integer> listarPartidasPausadas()
    Lista los identificadores de todas las partidas pausadas que hay en disco.

    Recorre `data/partidas/` buscando ficheros con extensión `.dat` y extrae el id del nombre de cada fichero. Usado por `GestorPartidas` para mostrar al usuario las partidas que puede reanudar.

    Specified by:
      `listarPartidasPausadas` in interface `GestorPersistencia`
    Returns:
      lista de ids (`int`) de partidas pausadas. Devuelve una lista vacía si no hay ninguna.