מעבר מ-GCMNetworkManager ל-WorkManager

במסמך הזה מוסבר איך להעביר אפליקציות לשימוש בספריית הלקוח של WorkManager כדי לבצע פעולות ברקע במקום באמצעות ספריית GCMNetworkManager. הדרך המועדפת לתזמון משימות ברקע היא להשתמש ב-WorkManager. על ידי כולל גם את ספריית WorkManager GCM, אפשר לאפשר ל-WorkManager להשתמש GCM כדי לתזמן את המשימות בעת הרצה במכשירי Android עם רמת API 22 או פחות.

העברה אל WorkManager

אם האפליקציה שלך משתמשת כרגע ב-GCMNetworkManager כדי לבצע פעולות ברקע, יש לבצע את השלבים הבאים כדי לעבור אל WorkManager.

בשלבים הבאים, אנחנו מניחים שאתם מתחילים עם קוד GCMNetworkManager, שמגדיר ומתזמנ את המשימה שלך:

val myTask = OneoffTask.Builder()
    // setService() says what class does the work
    .setService(MyUploadService::class.java)
    // Don't run the task unless device is charging
    .setRequiresCharging(true)
    // Run the task between 5 & 15 minutes from now
    .setExecutionWindow(5 * DateUtil.MINUTE_IN_SECONDS,
            15 * DateUtil.MINUTE_IN_SECONDS)
    // Define a unique tag for the task
    .setTag("test-upload")
    // ...finally, build the task and assign its value to myTask
    .build()
GcmNetworkManager.getInstance(this).schedule(myTask)

// In GcmNetworkManager, this call defines the task and its
// runtime constraints:
OneoffTask myTask = new OneoffTask.Builder()
    // setService() says what class does the work
    .setService(MyUploadService.class)
    // Don't run the task unless device is charging
    .setRequiresCharging(true)
    // Run the task between 5 & 15 minutes from now
    .setExecutionWindow(
        5 * DateUtil.MINUTE_IN_SECONDS,
        15 * DateUtil.MINUTE_IN_SECONDS)
    // Define a unique tag for the task
    .setTag("test-upload")
    // ...finally, build the task and assign its value to myTask
    .build();
GcmNetworkManager.getInstance(this).schedule(myTask);

בדוגמה הזו, אנחנו מניחים שפעולת ההעלאה בפועל מוגדרת על ידי MyUploadService:

class MyUploadService : GcmTaskService() {
    fun onRunTask(params: TaskParams): Int {
        // Do some upload work
        return GcmNetworkManager.RESULT_SUCCESS
    }
}

class MyUploadService extends GcmTaskService {
    @Override
    public int onRunTask(TaskParams params) {
        // Do some upload work
        return GcmNetworkManager.RESULT_SUCCESS;
    }
}

הכללה של ספריות WorkManager

כדי להשתמש בכיתות של WorkManager, צריך להוסיף את הספרייה של WorkManager וליצור יחסי תלות. צריך להוסיף גם את ספריית WorkManager GCM, מאפשר ל-WorkManager להשתמש ב-GCM לתזמון משימות כשהאפליקציה שלך פועלת מכשירים שלא תומכים ב-JobScheduler (כלומר, מכשירים עם רמת API 22) או פחות). לקבלת פרטים מלאים על הוספת הספריות, ראו תחילת העבודה עם WorkManager.

שינוי המניפסט

כשהטמעת את GCMNetworkManager, הוספת מופע של GcmTaskService בקובץ המניפסט של האפליקציה, כפי שמתואר בGcmNetworkManager מסמכי עזר. GcmTaskService בודק את המשימה הנכנסת ומעניק אותה למשימה המטפל. ב-WorkManager מנהל את הקצאת המשימות ל-Worker, כך שכבר לא צריכים מחלקה שעושה את זה, פשוט מסירים את GcmTaskService .

הגדרת ה-Worker

ההטמעה של GCMNetworkManager מגדירה את OneoffTask או RecurringTask, שמציין בדיוק מה צריך לעשות. צריך לשכתב את הקוד, Worker, כפי שמתועד בהגדרת היצירה שלך בקשות.

דוגמה ל-GCMNetworkManager קוד מגדיר משימה מסוג myTask. המקבילה ב-WorkManager נראית כך:

class UploadWorker(context: Context, params: WorkerParameters)
                        : Worker(context, params) {
    override fun doWork() : Result {
        // Do the upload operation ...
        myUploadOperation()

        // Indicate whether the task finished successfully with the Result
        return Result.success()
    }
}

public class UploadWorker extends Worker {

    public UploadWorker(
        @NonNull Context context,
        @NonNull WorkerParameters params) {
        super(context, params);
    }

    @Override
    public Result doWork() {
      // Do the upload operation ...

      myUploadOperation()

      // Indicate whether the task finished successfully with the Result
      return Result.success()
    }
}

יש מספר הבדלים בין משימת GCM לבין Worker:

• GCM משתמש באובייקט TaskParams כדי להעביר פרמטרים למשימה. WorkManager משתמש בנתוני קלט, שניתן לציין ב-WorkRequest, שמתוארים במשאבי העזרה של WorkManager לגבי הגדרת קלט/פלט את המשימה. בשני המקרים, תוכלו להעביר צמדי מפתח/ערך שמציינים כל את הפרמטרים הנדרשים לביצוע המשימה.
• הערך GcmTaskService מציין הצלחה או כישלון על ידי החזרת סימונים כמו GcmNetworkManager.RESULT_SUCCESS. Worker של WorkManager מסמן את התוצאות שלו באמצעות שימוש ListenableWorker.Result method, כמו ListenableWorker.Result.success(), והחזרת הערך המוחזר של אותה שיטה.
• כפי שציינו, אתם לא מגדירים את האילוצים או את התגים כאשר אתם מגדירים Worker; במקום זאת, צריך לעשות את זה בשלב הבא, כשתיצרו את WorkRequest.

תזמון בקשת העבודה

הגדרת Worker מציינת מה צריך לעשות. כדי לציין מתי היצירה צריך להגדיר WorkRequest:

1. יצירת OneTimeWorkRequest או PeriodicWorkRequest, וגם להגדיר את המגבלות הרצויות שמציינות מתי המשימה צריכה לפעול, וגם תגים לזיהוי העבודה שלך.
2. העברת הבקשה אל WorkManager.enqueue() כדי שהמשימה תהיה בתור לביצוע.

לדוגמה, בקטע הקודם ראינו איך להמיר OneoffTask לערך שווה ערך של Worker. עם זאת, Worker לא כלל אילוצי הביצוע והתג של האובייקט OneoffTask. במקום זאת, אנחנו מגדירים את אילוצים ומזהה משימה כשאנחנו יוצרים את WorkRequest. נציין גם אסור שהמשימה תפעל אלא אם יש חיבור לרשת. לא צריך לבקש באופן מפורש חיבור לרשת עם GCMNetworkManager, כברירת מחדל, ל-GCMNetworkManager נדרש חיבור לרשת, אבל WorkManager דורש חיבור לרשת. לא דורשים חיבור לרשת, אלא אם מוסיפים את האילוץ הזה באופן ספציפי. אחרי שנגדיר את ה-WorkRequest, אנחנו נוסיף אותו לתור אצל WorkManager.

val uploadConstraints = Constraints.Builder()
    .setRequiredNetworkType(NetworkType.CONNECTED)
    .setRequiresCharging(true).build()

val uploadTask = OneTimeWorkRequestBuilder<UploadWorker>()
    .setConstraints(uploadConstraints)
    .build()
WorkManager.getInstance().enqueue(uploadTask)

Constraints uploadConstraints = new Constraints.Builder()
    .setRequiredNetworkType(NetworkType.CONNECTED)
    .setRequiresCharging(true)
    .build();

OneTimeWorkRequest uploadTask =
        new OneTimeWorkRequest.Builder(UploadWorker.class)
  .setConstraints(uploadConstraints)
  .build();
WorkManager.getInstance().enqueue(uploadTask);

מיפויים של API

בקטע הזה מתואר האופן שבו חלק מהתכונות והאילוצים של GCMNetworkManager ממפים אל שווי ערך ב-WorkManager.

מיפויי מגבלות

GCMNetworkManager מאפשר להגדיר מספר אילוצים הקובעים מתי המשימה צריכה לרוץ. ברוב המקרים יש אילוץ ברור ב-WorkManager. הזה מפרטת את המקבילים האלה.

מגדירים מגבלות במשימות של GCMNetworkManager באמצעות קריאה לשיטה המתאימה אובייקט ה-builder של המשימה. לדוגמה, אפשר להגדיר דרישת רשת כך התקשרות אל Task.Builder.setRequiredNetwork().

ב-WorkManager, אובייקט Constraints.Builder ו קוראים ל-methods של האובייקט כדי להגדיר מגבלות (לדוגמה, Constraints.Builder.setRequiredNetworkType()), להשתמש ב-Builder כדי ליצור אובייקט Constraints (אילוצים), שניתן לצרף בקשת עבודה. מידע נוסף זמין במאמר הגדרת היצירה שלך בקשות.

מיפויים אחרים

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

תגים

כל המשימות של GCMNetworkManager חייבות לכלול מחרוזת תג, שאותה ניתן להגדיר באמצעות קריאה setTag() של ה-builder . משימות WorkManager מזוהות באופן ייחודי באמצעות מזהה, נוצר באופן אוטומטי על ידי WorkManager. אפשר לקבל את התעודה המזהה WorkRequest.getId() לחשבון בנוסף, בקשות עבודה יכולות לכלול אופציונלי תג אחד או יותר. כדי להגדיר תג עבור ב-WorkManager, WorkRequest.Builder.addTag() , לפני שמשתמשים ב-builder הזה כדי ליצור את WorkRequest.

ב-GCMNetworkManager ניתן לבצע קריאה setUpdateCurrent() כדי לציין אם המשימה צריכה להחליף כל משימה קיימת באותו תג. הגישה המקבילה ב-WorkManager היא להוסיף למשימה לתור באמצעות קריאה enqueueUniqueWork() או enqueueUniquePeriodicWork(); אם משתמשים בשיטות האלה, נותנים למשימה שם ייחודי, וגם מציינים מנהל העבודה צריך לטפל בבקשה אם כבר יש משימה בהמתנה עם ההגדרה שם. למידע נוסף, ראו טיפול העבודה.

פרמטרים של משימה

ניתן להעביר פרמטרים למשימת GCMNetworkManager באמצעות קריאה Task.Builder.setExtras() ונעביר ערך של Bundle שמכיל את הפרמטרים. WorkManager מאפשר לך להעביר אובייקט Data למשימה של WorkManager, שמכיל את הפרמטרים בתור מפתח/ערך זוגות של מילים. פרטים נוספים זמינים במאמר הקצאת נתוני קלט.