טיפול בשגיאות ב-Android

‫Kotlin לא תומכת בחריגים מסומנים. כך הטיפול בשגיאות פשוט ויעיל יותר, כי אפשר לבחור לטפל רק בחריגות שניתן לשחזר. מכיוון שלא צריך לטפל באופן מפורש בכל חריגה אפשרית, הקוד פחות עמוס, ולכן הוא נשאר ממוקד יותר במטרה העיקרית שלו.

כשלים שניתן לשחזר הם בעיות שהמפתח יכול לטפל בהן מהצד שלו. לדוגמה, אם מזהה שמשמש בקריאה לא תקין, ה-API מחזיר HomeException עם הודעת invalid data. מפתח האפליקציה יכול לבחור אם להסיר את המזהה הזה מהמטמון או להציג למשתמש הודעה כמו "המבנה לא נמצא".

דוגמה לטיפול בכשל שניתן לשחזור:

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

כל שיטה ב-Home APIs יכולה להפעיל 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	הפעולה נדחתה כי המערכת לא במצב שנדרש לביצוע הפעולה. לדוגמה, יכול להיות שתקבלו את ההודעה הזו אם הפקודה stop של OvenCavityOperationalStateTrait הופעלה בתנור שכבר כבוי.
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	משאב כלשהו מוצה, אולי בגלל שהגעתם למכסה לכל משתמש או שנגמר המקום במערכת הקבצים כולה. לדוגמה, השגיאה הזו יכולה להופיע אם הפקודה dispense של DispenseTrait מופעלת במכשיר להאכלת חיות מחמד, אבל לא נשאר יותר אוכל במכשיר. יכול להיות גם שחרגתם ממכסת הפרויקטים של Home APIs. למידע נוסף, קראו את המאמר ניהול מכסות.
SDK_INITIALIZATION_MISSING_INFO	ה-SDK הופעל בלי כל המידע הנדרש. לדוגמה, השגיאה הזו מופיעה אם הלקוח מנסה לקבל TraitFactory עבור מזהה תכונה נתון, אבל התכונה לא נכללה באתחול ה-SDK. איך מאתחלים את הבית ב-Android
UNAUTHENTICATED	אי אפשר לזהות את הגורם ששלח את הבקשה, או שהבקשה לא כוללת פרטי כניסה לאימות תקינים.
UNAVAILABLE	השירות לא זמין. כנראה מדובר במצב זמני, שאפשר לתקן על ידי ניסיון חוזר עם השהיה לפני ניסיון חוזר. חשוב לזכור שלא תמיד בטוח לנסות שוב פעולות שהן לא אידמפוטנטיות.
UNIMPLEMENTED	הפעולה המבוקשת לא מיושמת, נתמכת או מופעלת בשירות הזה.
UNKNOWN	שגיאה לא ידועה. הקוד UNKNOWN מופיע כשמתרחש מצב שגיאה שלא ניתן לסווג באמצעות אף אחד מקודי השגיאה האחרים. לדוגמה, השגיאה הזו עשויה לחזור כשערך סטטוס שהתקבל מ-API חיצוני לא כולל מספיק מידע לגבי שורש הבעיה.
WRITE_FAILED	פעולת הכתיבה נכשלה. כדי לקבל פרטים נוספים, אפשר לבדוק את קודי השגיאה המשניים.