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 をスローする可能性があるため、すべての呼び出しで HomeException をキャッチするために try-catch ブロックを使用することをおすすめします。

HomeException を処理するときは、 error.code フィールドと error.message フィールドを確認して、何が問題であるかを確認します。サブエラーコードが存在する場合もあるため、 getSubErrorCodes() メソッドを呼び出して結果を確認します。

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

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

テーブル: HomeException codes

コード	意味
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 コマンドが呼び出されたときに、ユニットに餌が残っていない場合、このエラーがスローされることがあります。
SDK_INITIALIZATION_MISSING_INFO	SDK が必要な情報の一部なしで初期化されました。たとえば、クライアントが特定の特性 ID の TraitFactory を取得しようとしたときに、SDK の初期化時にその特性が含まれていなかった場合、このエラーがスローされます。Android でホームを初期化するをご覧ください。
UNAUTHENTICATED	呼び出し元を特定できないか、リクエストに有効な認証情報がありません。
UNAVAILABLE	サービスを利用できません。これは、バックオフで再試行することで解決できる可能性が高い一時的な状態です。非べき等オペレーションの再試行が常に安全であるとは限りません。
UNIMPLEMENTED	リクエストされたオペレーションは、このサービスで実装、サポート、有効化されていません。
UNKNOWN	不明なエラーが発生しました。UNKNOWN は、他のエラーコードで分類できないエラー条件が発生した場合に表示されます。たとえば、外部 API から受信したステータス値に根本原因に関する十分な情報がない場合などに、このエラーが返されます。
WRITE_FAILED	書き込みが実行されませんでした。詳細については、サブエラーコードをご確認ください。