טיפול בשגיאות ב-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	השירות לא זמין. הסיבה היא כנראה מצב זמני שאפשר לתקן אותו באמצעות ניסיון חוזר עם השהיה לפני ניסיון חוזר (backoff). שימו לב שלא תמיד בטוח לנסות שוב פעולות שהן לא אידמפוטנטיות.
UNIMPLEMENTED	הפעולה המבוקשת לא יושמה, לא נתמכת או לא מופעלת בשירות הזה.
UNKNOWN	שגיאה לא ידועה. השגיאה UNKNOWN מופיעה כשמתרחש תנאי שגיאה שלא ניתן לסווג באמצעות אף אחד מקודי השגיאה האחרים. לדוגמה, השגיאה הזו עשויה להיות מוחזרת כשערך סטטוס שמתקבל מ-API חיצוני לא כולל מספיק מידע לגבי הגורם הבסיסי.
WRITE_FAILED	הפעולה 'כתיבה' נכשלה. כדאי לבדוק את קודי השגיאה המשניים כדי לקבל פרטים נוספים.