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

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

כשלים שניתן לשחזר הם בעיות שמפתח יכול לטפל בהן מהצד שלו. לדוגמה, אם מזהה שמשמש בקריאה לא תקף, ה-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	הכתיבה נכשלה. כדי לקבל פרטים נוספים, אפשר לבדוק את קודי שגיאת המשנה.