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

ב-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, כדאי לבדוק את השדות code ו-message כדי להבין מה השתבש.

חריגות שלא מטופלות יגרמו לקריסה של האפליקציה.

בטבלה הבאה מפורטות המשמעויות של קודי HomeException שעשויים להופיע:

טבלה: HomeException codes

קוד	משמעות
ABORTED	הפעולה בוטלה. השגיאה הזו מופיעה בדרך כלל כשיש בעיה של בו-זמניות, כמו כשל בבדיקת רצף או ביטול טרנזקציה.
ALREADY_EXISTS	המשאב או הישות שניסיתם ליצור כבר קיימים. לדוגמה, לוח זמנים בעל שם לתרמוסטט.
API_NOT_CONNECTED	הלקוח ניסה להפעיל שיטה מ-API שלא הצליח להתחבר. מצב כזה יכול לקרות אם המכשיר במצב אופליין או שאין בו תמיכה ב-API שאתם מנסים לקרוא אליו.
CANCELLED	הפעולה בוטלה, בדרך כלל על ידי מבצע הקריאה החוזרת.
DATA_LOSS	אובדן נתונים או פגיעה בנתונים שלא ניתן לשחזר.
DEADLINE_EXCEEDED	מועד היעד פג לפני שהפעולה הושלמה. בפעולות שמחליפות את מצב המערכת, ייתכן שהשגיאה הזו תוחזר גם אם הפעולה הושלמה בהצלחה.
FAILED_PRECONDITION	הפעולה נדחתה כי המערכת לא במצב שנדרש לביצוע הפעולה. לדוגמה, יכול להיות שתקבלו את ההודעה הזו אם תפעילו את הפקודה stop בתנור שכבר הפסיק לפעול.
INTERNAL	שגיאות פנימיות. המשמעות היא שחלק מהקבועים שלא משתנים (invariants) שצפויים במערכת הבסיסית הופרו. קוד השגיאה הזה שמור לשגיאות חמורות.
INVALID_ARGUMENT	הוספתם ארגומנט מחוץ לטווח הערכים הצפוי.
NOT_FOUND	ציינת ישות או משאב שלא ניתן למצוא. לדוגמה, ציון מזהה טראק לא קיים בקריאה ל- activateAudioTrack במכשיר של נגן מדיה.
OUT_OF_RANGE	פרמטר חרג מהטווח החוקי, על סמך המצב הנוכחי של המערכת. ההודעה הזו מופיעה כשהערך נמצא בטווח הערכים שקריאת ה-API יכולה לקבל, אבל הוא לא הגיוני בהקשר הנוכחי.
PERMISSION_DENIED	אין לכם הרשאה לבצע את הפעולה שצוינה. קוד השגיאה הזה לא צריך להיחשב כסימן לכך שהבקשה תקינה מבחינות אחרות.
RESOURCE_EXHAUSTED	משאב מסוים מוצה. לדוגמה, האירוע הזה יכול להתרחש כששולחים קריאה ל- dispense במכשיר למזון לחיות מחמד ואין יותר מזון ביחידה.
SDK_INITIALIZATION_MISSING_INFO	ה-SDK לא הופעל במלואו. לדוגמה, ההודעה הזו תוצג אם תנסו לקבל TraitFactory למאפיין שלא נרשם. מידע נוסף זמין במאמר הפעלה.
UNAUTHENTICATED	לא ניתן לזהות את מבצע הקריאה החוזרת או שהבקשה לא כוללת פרטי כניסה תקינים לאימות.
UNAVAILABLE	השירות לא זמין. סביר להניח שמדובר במצב זמני, שאפשר לתקן על ידי ניסיון חוזר עם זמן המתנה. חשוב לזכור שלא תמיד בטוח לנסות שוב פעולות לא חד-ערכיות.
UNIMPLEMENTED	הפעולה המבוקשת לא מיושמת, לא נתמכת או לא מופעלת בשירות הזה.
UNKNOWN	שגיאה לא ידועה. באופן כללי, השגיאה UNKNOWN מופיעה כשמתרחש תנאי שגיאה שלא ניתן לסווג באמצעות אחד מקודי השגיאה האחרים. לדוגמה, השגיאה הזו עשויה להופיע כשערך סטטוס מתקבל מ-API חיצוני בלי מספיק מידע לגבי שורש הבעיה.