Obsługa błędów na Androidzie

Kotlin nie obsługuje wyjątków sprawdzanych. Upraszcza to i usprawnia obsługę błędów, ponieważ możesz wybrać obsługę tylko tych wyjątków, które można potencjalnie naprawić. Ponieważ nie musisz jawnie obsługiwać każdego możliwego wyjątku, kod jest mniej zagracony i dzięki temu bardziej skupiony na swoim głównym celu.

Błędy możliwe do naprawienia to problemy, które deweloper może rozwiązać po swojej stronie. Jeśli na przykład identyfikator użyty w wywołaniu jest nieprawidłowy, interfejs API zwraca błąd HomeException z komunikatem invalid data. Deweloper aplikacji może wtedy usunąć ten identyfikator z pamięci podręcznej lub wyświetlić użytkownikowi komunikat typu „Nie znaleziono domu”.

Przykład sposobu postępowania w przypadku błędu, który można naprawić:

val result =
   try {
     homeManager.requestPermissions()
   } catch (e: HomeException) {
     PermissionsResult(
       PermissionsResultStatus.ERROR,
       "Got HomeException with error: ${e.message}",
     )
   }

Dowolna metoda w interfejsach Home API może wywołać błąd HomeException, dlatego zalecamy używanie bloku try-catch do przechwytywania błędu HomeException we wszystkich wywołaniach.

Podczas obsługi HomeException sprawdź pola error.code i  error.message, aby dowiedzieć się, co poszło nie tak. Mogą też występować kody błędów podrzędnych, więc wywołaj metodę getSubErrorCodes() i sprawdź wynik.

Wszelkie nieobsługiwane wyjątki spowodują awarię aplikacji.

W tabeli poniżej znajdziesz znaczenie kodów HomeException, które możesz napotkać:

Tabela: kody HomeException

Kod	Znaczenie
ABORTED	Operacja została przerwana, najczęściej z powodu problemu równoczesności, np. w przypadku nieudanej kontroli sekwencera lub przerwanej transakcji.
ALREADY_EXISTS	Encja, którą klient próbował utworzyć, np. plik lub katalog, już istnieje.
API_NOT_CONNECTED	Klient próbował wywołać metodę z interfejsu API, który nie mógł się połączyć. Może się tak zdarzyć, gdy urządzenie jest offline lub nie obsługuje interfejsu API, który klient próbował wywołać.
CANCELLED	Operacja została anulowana, zwykle przez element wywołujący.
COMMAND_FAILED	Nie udało się wykonać polecenia. Więcej informacji znajdziesz w kodach błędów podrzędnych.
CURSOR_WINDOW_NOT_SUPPORTED	Wywołano metodę, która używa CursorWindow, ale CursorWindow nie jest włączony lub nie jest obsługiwany w obecnym kontekście.
DATA_LOSS	Doszło do nieodwracalnej utraty lub uszkodzenia danych.
DEADLINE_EXCEEDED	Termin upłynął, zanim operacja została ukończona. W przypadku operacji, które zmieniają stan systemu, ten błąd może zostać zwrócony nawet wówczas, gdy operacja zakończyła się pomyślnie.
DECOMMISSIONING_INELIGIBLE	Nie udało się wycofać urządzenia, ponieważ nie kwalifikuje się ono do wycofania.
FAILED_PRECONDITION	Operacja została odrzucona, ponieważ system nie znajduje się w stanie wymaganym do jej wykonania. Możesz na przykład zobaczyć ten komunikat, jeśli polecenie stop urządzenia OvenCavityOperationalStateTrait zostało wywołane na piekarniku, który został już wyłączony.
INTERNAL	Błędy wewnętrzne. Oznacza to, że niektóre niezmienniki oczekiwane przez system bazowy zostały naruszone. Ten kod błędu jest zarezerwowany dla poważnych błędów.
INVALID_ARGUMENT	Klient podał argument, który wykracza poza oczekiwany zakres wartości.
INVALID_DATA_HOLDER	Posiadacz danych jest nieprawidłowy.
NOT_FOUND	Nie znaleziono żądanego elementu, takiego jak plik lub katalog. Jeśli prośba zostanie odrzucona w przypadku całej klasy użytkowników, np. w przypadku stopniowego wdrażania funkcji lub nieudokumentowanej listy dozwolonych, można użyć szablonu NOT_FOUND. Jeśli żądanie zostanie odrzucone w przypadku niektórych użytkowników w ramach klasy użytkowników, np. kontroli dostępu opartej na użytkownikach, należy użyć PERMISSION_DENIED.
OUT_OF_RANGE	Próba wykonania operacji poza prawidłowym zakresem, np. wyszukiwanie lub odczytywanie po end-of-file. W przeciwieństwie do INVALID_ARGUMENT ten błąd wskazuje na problem, który można rozwiązać, jeśli zmieni się stan systemu.
PERMISSION_DENIED	Wywołujący nie ma uprawnień do wykonania określonej operacji. Kodu PERMISSION_DENIED nie należy używać w przypadku odrzuceń spowodowanych wyczerpaniem zasobów (w przypadku tych błędów należy użyć kodu RESOURCE_EXHAUSTED). Nie należy używać PERMISSION_DENIED, jeśli nie można zidentyfikować elementu wywołującego (w przypadku takich błędów użyj UNAUTHENTICATED). Ten kod błędu nie oznacza, że żądanie jest prawidłowe, że żądany element istnieje ani że spełnia inne warunki wstępne.
RESOURCE_EXHAUSTED	Zasoby zostały wyczerpane, być może z powodu osiągnięcia limitu na użytkownika lub braku miejsca w całym systemie plików. Ten błąd może wystąpić na przykład wtedy, gdy polecenie dispense urządzenia DispenseTrait zostanie wywołane na urządzeniu do karmienia zwierząt, ale nie ma już w nim karmy. Może to być też spowodowane przekroczeniem limitu projektu interfejsów Home API. Więcej informacji znajdziesz w artykule o zarządzaniu limitami.
SDK_INITIALIZATION_MISSING_INFO	Pakiet SDK został zainicjowany bez wszystkich wymaganych informacji. Ten błąd występuje na przykład wtedy, gdy klient próbuje uzyskać TraitFactory dla danego identyfikatora cechy, ale cecha nie została uwzględniona podczas inicjowania pakietu SDK. Zobacz Inicjowanie domu na Androidzie.
UNAUTHENTICATED	Nie można zidentyfikować elementu wywołującego lub żądanie nie ma prawidłowych danych uwierzytelniających.
UNAVAILABLE	Usługa jest niedostępna. Jest to najprawdopodobniej stan przejściowy, który można skorygować, ponawiając próbę z wycofaniem. Pamiętaj, że ponawianie operacji nieidempotentnych nie zawsze jest bezpieczne.
UNIMPLEMENTED	Żądana operacja nie jest zaimplementowana, obsługiwana ani włączona w tej usłudze.
UNKNOWN	Nieznany błąd. UNKNOWN pojawia się, gdy wystąpi błąd, którego nie można sklasyfikować za pomocą żadnego z pozostałych kodów błędu. Ten błąd może zostać zwrócony na przykład wtedy, gdy wartość stanu otrzymana z zewnętrznego interfejsu API nie zawiera wystarczających informacji o głównej przyczynie.
WRITE_FAILED	Nie udało się wykonać zapisu. Więcej informacji znajdziesz w kodach błędów podrzędnych.