WorkManager — ما هو، واجهة البرمجة وجدولة المهام

كيف يعمل WorkManager؟

هندسة WorkManager مبنية حول ثلاث فئات أساسية: Worker و WorkRequest و WorkManager. Worker يحتوي على منطق المهمة، WorkRequest يصف معايير التنفيذ، و WorkManager يدير قائمة الانتظار والجدولة. تستخدم المكتبة قاعدة بيانات Room داخلية لتخزين حالة جميع المهام.

Worker و WorkRequest

Worker هي فئة مجردة بطريقة واحدة doWork يتم استدعاؤها في سلسلة خلفية. الطريقة ترجع ListenableWorker.Result — SUCCESS أو FAILURE أو RETRY. WorkRequest يربط Worker بالمعايير: المهلة، الوسم، التأخير الأولي والقيود.

class SyncWorker(
    context: Context,
    params: WorkerParameters
) : Worker(context, params) {

    override fun doWork(): Result {
        return try {
            val api = RetrofitClient.api
            val response = api.syncData()
            Result.success()
        } catch (e: Exception) {
            Result.retry()
        }
    }
}

الجدولة عبر WorkManager

WorkManager يخطط المهام بشكل موحد بغض النظر عن إصدار Android. عند استدعاء enqueue، تحفظ المكتبة المهمة في Room، وتقييم الظروف الحالية، وتختار الوقت الأمثل للتنفيذ. داخليًا، قد تستخدم JobScheduler أو AlarmManager أو المجدول الخاص بها — لا يحتاج المطور إلى القلق بشأن ذلك.

val syncRequest = OneTimeWorkRequestBuilder<SyncWorker>()
    .setInitialDelay(15, TimeUnit.MINUTES)
    .addTag("sync")
    .build()

WorkManager.getInstance(context)
    .enqueue(syncRequest)

أنواع WorkRequest

WorkManager يدعم نوعين من طلبات التنفيذ: لمرة واحدة ودورية. يعتمد اختيار النوع على السيناريو: يجب تنفيذ المهمة مرة واحدة أو التكرار بفاصل زمني محدد.

OneTimeWorkRequest

OneTimeWorkRequest مصمم للمهام التي يجب تنفيذها مرة واحدة. يمكن أن يكون إرسال سجل، مزامنة البيانات بعد التفويض، تنزيل التكوين عند التشغيل الأول. يتم تعيين التأخير عبر setInitialDelay، والقيود عبر setConstraints.

PeriodicWorkRequest

PeriodicWorkRequest مناسب للمهام المتكررة بفاصل زمني لا يقل عن 15 دقيقة. تضمن المكتبة أن الفاصل الزمني بين عمليات التشغيل لن يقل عن المحدد، ولكنه قد يكون أطول بسبب قيود الجهاز. للمهام ذات التردد الأقل من 15 دقيقة، استخدم Handler أو Timer في Foreground Service.

إعداد القيود وسلاسل المهام

القيود في WorkManager تسمح بتعيين الشروط التي يمكن بموجبها تشغيل المهمة: الاتصال بالشبكة (NetworkType)، مستوى البطارية (batteryNotLow)، حالة التخزين (StorageNotLow) ووضع الخمول (DeviceIdle). لن تبدأ المهمة حتى يتم استيفاء جميع القيود.

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

val request = OneTimeWorkRequestBuilder<ImageUploadWorker>()
    .setConstraints(constraints)
    .build()

السلاسل تسمح بتنظيم التنفيذ المتسلسل أو المتوازي للمهام. beginWith يبدأ سلسلة، ثم يضيف Worker التالي الذي سيتم تنفيذه بعد الانتهاء بنجاح من السابق. للتنفيذ المتوازي، استخدم workManager.enqueue(listOf(request1, request2)).

WorkManager.getInstance(context)
    .beginWith(compressWorker)
    .then(uploadWorker)
    .then(cleanupWorker)
    .enqueue()
    // compress -> upload -> cleanup بالتسلسل

الترحيل من JobScheduler إلى WorkManager

JobScheduler تم تقديمه في Android 5 (API 21) كخدمة نظام لجدولة المهام الخلفية. جاء WorkManager ليحل محله، مقدمًا واجهة برمجة متعددة المنصات مع ترحيل تلقائي وإمكانيات إضافية: السلاسل، ضمان التنفيذ، الوسوم، مراقبة الحالة عبر LiveData.

عند الترحيل من JobScheduler إلى WorkManager، ستحتاج إلى تحويل JobService إلى Worker، واستبدال JobInfo بـ WorkRequest، و Context.getSystemService بواجهة WorkManager. يتولى WorkManager تلقائيًا مشاكل التوافق ويعالج وضع Doze Mode بشكل أكثر صحة من التنفيذ اليدوي لـ JobScheduler. خطوات الترحيل: 1) إنشاء فئة Worker، 2) بناء WorkRequest بنفس الشروط، 3) إزالة JobService و JobInfo من الكود والملف البياني.

UniqueWork للمهام الفريدة

يدعم WorkManager مفهوم المهام الفريدة من خلال ExistingWorkPolicy. إذا كانت مهمة بالاسم المحدد موجودة بالفعل، تحدد السياسة السلوك: KEEP (عدم إنشاء مهمة جديدة)، REPLACE (استبدال الموجودة)، APPEND (إضافة إلى نهاية السلسلة) و APPEND_OR_REPLACE. UniqueWorkRequest مناسب للمهام التي لا يجب أن تتكرر: مزامنة قاعدة البيانات، تنزيل التكوين، إرسال حزمة التحليلات.

WorkManager.getInstance(context)
    .enqueueUniqueWork(
        "sync_data",
        ExistingWorkPolicy.KEEP,
        syncRequest
    )

معالجة التقدم والنتائج الوسيطة

يدعم CoroutineWorker آلية setProgress، مما يسمح بتمرير نتائج التنفيذ الوسيطة. هذا مفيد للعمليات الطويلة: تنزيل ملف كبير، معالجة صور مجمعة، ترحيل قاعدة البيانات. يمكن لواجهة المستخدم الاشتراك في التحديثات عبر getWorkInfosByTagLiveData وعرض التقدم في الوقت الفعلي. طريقة ForegroundInfo متاحة أيضًا لتشغيل Worker كـ Foreground Service مع إشعار إذا كانت المهمة يجب أن تكون مرئية للمستخدم.

class ProgressWorker(
    context: Context,
    params: WorkerParameters
) : CoroutineWorker(context, params) {

    override suspend fun doWork(): Result {
        val total = 100
        for (i in 1..total) {
            setProgress(
                workDataOf("progress" to i)
            )
        }
        return Result.success()
    }
}

InputData و OutputData لنقل البيانات

يدعم WorkManager نقل البيانات بين Workers عبر InputData و OutputData. يتم إنشاء InputData أثناء بناء WorkRequest عبر Data.Builder ويتم تمريره إلى Worker عبر inputData. بعد التنفيذ، ينشئ Worker OutputData عبر workDataOf أو Data.Builder ويعيده مع Result.success(outputData). Worker التالي في السلسلة يستقبل outputData من السابق كـ inputData خاص به. يتم تخزين البيانات بتنسيق مفتاح-قيمة مع دعم الأنواع الأساسية: String, Int, Long, Boolean, Double. الحد الأقصى لحجم Data هو 10 كيلوبايت.

من الناحية العملية، تستخدم العديد من المشاريع WorkManager كالمجدول الوحيد للمهام الخلفية. توصي Google بترحيل جميع JobService الموجودة إلى WorkManager، خاصة في التطبيقات التي تدعم Android 4.4 (API 19) وما دونه، حيث يكون JobScheduler غير متاح ويستخدم WorkManager آلية احتياطية عبر AlarmManager و BroadcastReceiver. للاختبار، يوفر WorkManager TestListenableWorkerBuilder و TestWorkerBuilder، مما يسمح باختبار Workers في اختبارات JUnit بدون مجدول حقيقي.