Android でのエラー処理

Kotlin はチェック例外をサポートしていません。これにより、回復可能な例外のみを処理できるため、エラー処理が簡素化され、効率化されます。また、考えられるすべての例外を明示的に処理する必要がないため、コードが煩雑にならず、本来の目的に集中できます。

回復可能なエラーは、デベロッパーがエンドから対処できる問題です。たとえば、呼び出しで使用された ID が無効な場合、API は invalid data メッセージを含む HomeException をスローします。アプリ デベロッパーは、その ID をキャッシュから削除するか、ユーザーに「ストラクチャが見つかりません」などのメッセージを表示するかを選択できます。

回復可能な障害を処理する方法の例を次に示します。

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

Home API のメソッドは HomeException をスローする可能性があるため、try-catch ブロックを使用してすべての呼び出しで HomeException をキャッチすることをおすすめします。

HomeException を処理する際は、 error.code フィールドと error.message フィールドをチェックして、問題の内容を確認します。サブエラーコードが存在する場合もあるため、 getSubErrorCodes() メソッドを呼び出して結果を確認してください。

処理されない例外があると、アプリがクラッシュします。

次の表に、発生する可能性のある HomeException コードの意味を示します。

表: HomeException コード

コード	意味
ABORTED	オペレーションは、通常、シーケンサー チェックの失敗、またはトランザクションの中止などの同時実行の問題のために中止されています。
ALREADY_EXISTS	クライアントが作成しようとしたエンティティ（ファイルやディレクトリなど）はすでに存在します。
API_NOT_CONNECTED	クライアントが、接続に失敗した API からメソッドを呼び出そうとしました。これは、デバイスがオフラインの場合や、クライアントが呼び出そうとした API をサポートしていない場合に発生することがあります。
CANCELLED	オペレーションがキャンセルされました。通常、キャンセルは呼び出し元により行われます。
COMMAND_FAILED	コマンドを実行できませんでした。詳細については、サブエラーコードを確認してください。
CURSOR_WINDOW_NOT_SUPPORTED	CursorWindow を使用するメソッドが呼び出されましたが、CursorWindow が有効になっていないか、現在のコンテキストでサポートされていません。
DATA_LOSS	回復不能なデータ損失またはデータ破損が発生しました。
DEADLINE_EXCEEDED	オペレーションが完了する前に期限が切れました。システムの状態を変更するオペレーションの場合、オペレーションが正常に終了しても、このエラーが返されることがあります。
DECOMMISSIONING_INELIGIBLE	デバイスがデコミッションの対象ではないため、デコミッションに失敗しました。
FAILED_PRECONDITION	システムがオペレーションの実行に必要な状態ではないため、オペレーションが拒否されました。たとえば、すでに停止しているオーブンで OvenCavityOperationalStateTrait の stop コマンドが呼び出された場合、このメッセージが表示されることがあります。
INTERNAL	内部エラー。これは、基盤システムが想定しているいくつかの不変条件が破られたことを意味します。このエラーコードは、重大なエラー用に予約されています。
INVALID_ARGUMENT	クライアントが、想定される値の範囲外の引数を指定しました。
INVALID_DATA_HOLDER	データホルダーが無効です。
NOT_FOUND	リクエストされたエンティティ（ファイルやディレクトリなど）が見つかりませんでした。段階的な機能のロールアウトや文書化されていない許可リストなど、ユーザークラス全体に対してリクエストが拒否された場合は、NOT_FOUND を使用できます。ユーザーベースのアクセス制御など、ユーザーのクラス内の特定のユーザーに対してリクエストが拒否された場合は、PERMISSION_DENIED を使用する必要があります。
OUT_OF_RANGE	オペレーションが有効な範囲を超えて試行されました。たとえば、end-of-file を超えたシークまたは読み取りなどが該当します。INVALID_ARGUMENT とは異なり、このエラーは、システムの状態が変化すれば修正できる可能性のある問題を示しています。
PERMISSION_DENIED	呼び出し元に、指定されたオペレーションを実行する権限がありません。PERMISSION_DENIED は、リソースの枯渇による拒否には使用しないでください（これらのエラーには RESOURCE_EXHAUSTED を使用してください）。呼び出し元を特定できない場合は、PERMISSION_DENIED を使用しないでください（これらのエラーには UNAUTHENTICATED を使用します）。このエラーコードは、リクエストが有効であること、リクエストされたエンティティが存在すること、および他の事前条件が満たされていることを意味するものではありません。
RESOURCE_EXHAUSTED	一部のリソースが枯渇しています。ユーザーごとの割り当てに達したか、ファイル システム全体の容量が不足している可能性があります。たとえば、ペット給餌器デバイスで DispenseTrait の dispense コマンドが呼び出されたものの、ユニットに餌が残っていない場合、このエラーがスローされる可能性があります。 Home APIs プロジェクトの割り当てを超過していることが原因である可能性もあります。詳細については、割り当て管理をご覧ください。
SDK_INITIALIZATION_MISSING_INFO	SDK が、必要な情報がすべて揃っていない状態で初期化されました。 たとえば、クライアントが特定のトレイト ID の TraitFactory を取得しようとしたものの、SDK の初期化時にそのトレイトが含まれていなかった場合、このエラーがスローされます。Android で家を初期化するをご覧ください。
UNAUTHENTICATED	呼び出し元を識別できないか、リクエストに有効な認証情報がありません。
UNAVAILABLE	サービスを利用できません。これは、バックオフで再試行することで解決できる可能性が高い一時的な状態です。非べき等オペレーションの再試行が常に安全であるとは限りません。
UNIMPLEMENTED	リクエストされたオペレーションは、このサービスで実装、サポート、有効化されていません。
UNKNOWN	不明なエラーが発生しました。UNKNOWN は、他のエラーコードを使用して分類できないエラー状態が発生した場合に表示されます。たとえば、外部 API から受信したステータス値に、根本原因に関する十分な情報が含まれていない場合に、このエラーが返されることがあります。
WRITE_FAILED	書き込みを実行できませんでした。詳細については、サブエラーコードを確認してください。