Manejo de errores y logging

El punto central es tener un embudo único de excepciones y separar “error que el usuario ve” de “error para el log”.

El embudo: Debug.handle(e) y Debug.log(...)

try {
   arriscado();
} catch (Exception e) {
   Debug.handle(e);        // loguea y trata de forma uniforme (embudo único)
}
Debug.log("estado:", valor);   // diagnóstico libre

Las animaciones y tasks del framework ya capturan Throwable vía Debug.handle internamente. Por qué un embudo: una excepción no manejada en la paint thread derriba el frame — canalizarla evita el crash y da un punto único para instrumentar.

Reacciona a errores específicos (no engullas todo)

try (SqliteDb db = SqliteDb.open("app.db")) {
   db.execute("INSERT INTO cliente(email) VALUES(?)", email);
} catch (SqliteException e) {
   if (e.code == Sqlite.CONSTRAINT) Hint.show("E-mail já cadastrado", 2000);   // 19
   else if (e.code == Sqlite.BUSY)  Hint.show("Banco ocupado, tente de novo", 2000);  // 5
   else Debug.handle(e);
}

SqliteException.code trae el código SQLite (Sqlite.OK/BUSY/CONSTRAINT/LOCKED/...). Lo mismo vale para otros resultados tipados (ej.: AuthResult.ERROR de la biometría).

Errores de callbacks de fondo → muéstralos en la UI con onUI

Los callbacks (red, GPS, BLE) se ejecutan fuera de la paint thread. Para avisar al usuario, hazles marshaling con onUI:

new Thread(() -> {
   try { sincronizar(); }
   catch (Exception e) {
      Component.onUI(() -> Hint.show("Falha ao sincronizar", 2000));   // Hint = no bloqueante
      Debug.handle(e);
   }
}).start();

• Hint.show(...) para avisos no bloqueantes; Alert cuando exige una decisión del usuario.
• Separa: lo que el usuario necesita ver (Hint/Alert) vs. lo que va solo al log (Debug.log/handle).

Flags de depuración

Debug.traceKeyboard, Debug.showFPS, Debug.beepOnGC ayudan a diagnosticar durante el desarrollo.

Buenas prácticas

• Un embudo (Debug.handle) para lo que no es tratable específicamente.
• Trata códigos específicos (CONSTRAINT, BUSY) con un mensaje útil al usuario.
• Error de fondo → onUI + Hint/Alert; nunca toques la UI directo en el callback.

Errores comunes

• catch (Exception e) {} vacío — engulle el problema.
• Mostrar el stack trace crudo al usuario (usa Hint/Alert con mensaje claro; el stack va al log).
• Tocar la UI desde un thread de fondo sin onUI.

Ver también

• Diálogos y modales · Trabajo en background