🔎 Chaining Work

WorkManager를 통해 여러 종속 작업들을 지정하고 실행 순서를 정의하는 작업 체인을 생성하고 대기열에 추가할 수 있음. 특정 순서로 여러 작업을 실행해야 할 때 특히 유용함.

작업 체인을 만들기 위해 WorkContinuation의 인스턴스를 반환하는 WorkManager.beginWith(OneTimeWorkRequest) 또는 WorkManager.beginWith(List<OneTimeWorkRequest>) 를 사용할 수 있음.

WorkContinuation의 then(OneTimeWorkRequest) 또는 then(List<OneTimeWorkRequest>)를 사용하여 종속 OneTimeWorkRequest 인스턴스를 추가할 수 있음.

WorkContinuation.then(...)을 호출할 때마다 WorkContinuation의 새 인스턴스가 반환됨.
OneTimeWorkRequest 인스턴스 목록을 추가하면 이러한 요청이 잠재적으로 병렬로 실행될 수 있음.

마지막으로 WorkContinuation.enqueue() 메서드를 사용하여 WorkContinuation 체인을 enqueue()할 수 있음.

WorkManager.getInstance(myContext)
   // Candidates to run in parallel
   .beginWith(listOf(plantName1, plantName2, plantName3))
   // Dependent work (only runs after all previous work in chain)
   .then(cache)
   .then(upload)
   // Call enqueue to kick things off
   .enqueue()

📖 Input Mergers

OneTimeWorkRequest 인스턴스를 연결하면 상위 작업 요청의 출력이 하위 항목에 대한 입력으로 전달됨. 따라서 위의 코드에서는 platName1, plantName2, plantName3의 출력이 캐시 요청에 대한 입력으로 전달됨.

• InputMerger를 사용하는 이유
  여러 상위 작업 요청의 입력을 관리하기 위해 WorkManager는 InputMerger를 사용.

📕 OverwritingInputMerger

OverwritingInputMerger는 기본 병합 방법. 병합에 키 충돌이 있는 경우 키의 최신 값이 결과 출력 데이터의 이전 버전을 덮어씀.

*충돌이 일어나지 않았을 때

• 충돌이 일어났을 때
  

**작업 요청이 병렬로 실행되기 때문에 실행 순서가 보장되지 않음.** 위의 예에서 plantName1은 마지막에 기록된 값에 따라 "tulip" 또는 "elm" 값을 보유할 수 있음. 키 충돌 가능성이 있고 merger의 모든 출력 데이터를 보존해야하는 경우 ArrayCreatingInputMerger를 사용하는 것이 좋을 수 있음.

📕 ArrayCreatingInputMerger

위의 예에서 모든 plant의 이름 출력을 보존하려면 ArrayCreatingInputMerger를 사용해야 함.

val cache: OneTimeWorkRequest = OneTimeWorkRequestBuilder<PlantWorker>()
   .setInputMerger(ArrayCreatingInputMerger::class)
   .setConstraints(constraints)
   .build()

ArrayCreatingInputMerger는 각 키를 배열과 쌍으로 연결함.

충돌이 일어났을 경우

📖 체이닝과 작업 상태

OneTimeWorkRequest 체인은 작업이 성공적으로 완료되면, 즉 Result.success()를 반환하면 순차적으로 실행됨. 작업 요청은 실행 중에 실패하거나 취소될 수 있어서 종속 작업 요청에 후속 영향을 미침.

첫 번째 OneTimeWorkRequest가 작업 요청 체인에서 큐에 추가되면 첫 번째 작업 요청의 작업이 완료될 때까지 모든 후속 작업 요청이 차단됨.

큐에 추가되고 모든 작업 제약조건이 충족되면 첫 번째 작업 요청이 실행되기 시작함.
작업이 루트 OneTimeWorkRequest 또는 List<OneTimeWorkRequest>에서 성공적으로 완료되면, 즉 Result.success()를 반환하면 다음 종속 작업 요청 세트가 큐에 추가됨.

각 작업 요청이 성공적으로 완료된다면 체인의 모든 작업이 완료될 때까지 작업 요청 체인의 나머지 부분 전체에 이와 동일한 패턴이 적용됨.

작업자가 작업 요청을 처리하는 동안 오류가 발생하면 개발자가 정의한 백오프 정책에 따라 요청을 재시도할 수 있음. 체인에 속한 요청을 재시도하면 제공된 입력 데이터로 해당 요청만 재시도됨. 동시에 실행되는 모든 작업은 영향을 받지 않음.

재시도 정책이 정의되어 있지 않거나 없는 경우 또는 OneTimeWorkRequest가 Result.failure()를 반환하는 상태에 도달하면 작업 요청과 모든 종속 작업 요청이 FAILED로 표시됨

OneTimeWorkRequest가 취소되면 동일한 로직이 적용됨. 종속 작업 요청도 CANCELLED로 표시되고 작업이 실행되지 않음.
**실패하거나 취소된 작업 요청이 있는 체인에 더 많은 작업 요청을 추가하면 새로 추가된 작업 요청도 각각 FAILED 또는 CANCELLED로 표시됨.** 기존 체인의 작업을 확장하려면 ExistingWorkPolicy의 APPEND_OR_REPLACE를 참고.

---

🔎 장기 실행 worker 지원

WorkManager에는 장기 실행 Worker에 대한 지원이 내장되어 있음. 이러한 경우 WorkManager는 이 작업이 실행되는 동안 가능하면 프로세스를 활성 상태로 유지해야 한다는 신호를 OS에 제공할 수 있음. 이러한 Worker는 10분 이상 실행될 수 있음. 이것의 사용 사례로는 일괄 업로드 또는 일괄 다운로드(청크 불가), ML 모델의 로컬 크런칭, 앱 사용자에게 중요한 작업 등이 있음.

내부적으로 WorkManager는 개발자를 대신해서 포그라운드 서비스를 관리하고 실행하여 WorkRequest를 실행하며 구성 가능한 알림도 표시함.

📖 장기 실행 worker 생성 및 관리

코틀린으로 코딩할 때와 자바로 코딩할 때 다른 접근법을 사용.

1. Kotlin
   Kotlin 개발자는 CoroutineWorker를 사용해야함. setForegroundAsync()를 사용하는 대신 이 메서드의 정지 버전인 setForeground()를 사용.

class DownloadWorker(context: Context, parameters: WorkerParameters) :
   CoroutineWorker(context, parameters) {

   private val notificationManager =
       context.getSystemService(Context.NOTIFICATION_SERVICE) as
               NotificationManager

   override suspend fun doWork(): Result {
       val inputUrl = inputData.getString(KEY_INPUT_URL)
                      ?: return Result.failure()
       val outputFile = inputData.getString(KEY_OUTPUT_FILE_NAME)
                      ?: return Result.failure()
       // Mark the Worker as important
       val progress = "Starting Download"
       setForeground(createForegroundInfo(progress))
       download(inputUrl, outputFile)
       return Result.success()
   }

   private fun download(inputUrl: String, outputFile: String) {
       // Downloads a file and updates bytes read
       // Calls setForeground() periodically when it needs to update
       // the ongoing Notification
   }
   // Creates an instance of ForegroundInfo which can be used to update the
   // ongoing notification.
   private fun createForegroundInfo(progress: String): ForegroundInfo {
       val id = applicationContext.getString(R.string.notification_channel_id)
       val title = applicationContext.getString(R.string.notification_title)
       val cancel = applicationContext.getString(R.string.cancel_download)
       // This PendingIntent can be used to cancel the worker
       val intent = WorkManager.getInstance(applicationContext)
               .createCancelPendingIntent(getId())

       // Create a Notification channel if necessary
       if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O) {
           createChannel()
       }

       val notification = NotificationCompat.Builder(applicationContext, id)
           .setContentTitle(title)
           .setTicker(title)
           .setContentText(progress)
           .setSmallIcon(R.drawable.ic_work_notification)
           .setOngoing(true)
           // Add the cancel action to the notification which can
           // be used to cancel the worker
           .addAction(android.R.drawable.ic_delete, cancel, intent)
           .build()

       return ForegroundInfo(notificationId, notification)
   }

   @RequiresApi(Build.VERSION_CODES.O)
   private fun createChannel() {
       // Create a Notification channel
   }

   companion object {
       const val KEY_INPUT_URL = "KEY_INPUT_URL"
       const val KEY_OUTPUT_FILE_NAME = "KEY_OUTPUT_FILE_NAME"
   }
}

2. Java
   ListenableWorker 또는 Worker를 사용하는 개발자는 ListenableFuture<Void>를 반환하는 setForegroundAsync() API를 호출할 수 있음. 또한 진행 중인 Notification을 업데이트하기 위해 setForegroundAsync()를 호출할 수도 있음.

public class DownloadWorker extends Worker {
   private static final String KEY_INPUT_URL = "KEY_INPUT_URL";
   private static final String KEY_OUTPUT_FILE_NAME = "KEY_OUTPUT_FILE_NAME";

   private NotificationManager notificationManager;

   public DownloadWorker(
       @NonNull Context context,
       @NonNull WorkerParameters parameters) {
           super(context, parameters);
           notificationManager = (NotificationManager)
               context.getSystemService(NOTIFICATION_SERVICE);
   }

   @NonNull
   @Override
   public Result doWork() {
       Data inputData = getInputData();
       String inputUrl = inputData.getString(KEY_INPUT_URL);
       String outputFile = inputData.getString(KEY_OUTPUT_FILE_NAME);
       // Mark the Worker as important
       String progress = "Starting Download";
       setForegroundAsync(createForegroundInfo(progress));
       download(inputUrl, outputFile);
       return Result.success();
   }

   private void download(String inputUrl, String outputFile) {
       // Downloads a file and updates bytes read
       // Calls setForegroundAsync(createForegroundInfo(myProgress))
       // periodically when it needs to update the ongoing Notification.
   }

   @NonNull
   private ForegroundInfo createForegroundInfo(@NonNull String progress) {
       // Build a notification using bytesRead and contentLength

       Context context = getApplicationContext();
       String id = context.getString(R.string.notification_channel_id);
       String title = context.getString(R.string.notification_title);
       String cancel = context.getString(R.string.cancel_download);
       // This PendingIntent can be used to cancel the worker
       PendingIntent intent = WorkManager.getInstance(context)
               .createCancelPendingIntent(getId());

       if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O) {
           createChannel();
       }

       Notification notification = new NotificationCompat.Builder(context, id)
               .setContentTitle(title)
               .setTicker(title)
               .setSmallIcon(R.drawable.ic_work_notification)
               .setOngoing(true)
               // Add the cancel action to the notification which can
               // be used to cancel the worker
               .addAction(android.R.drawable.ic_delete, cancel, intent)
               .build();

       return new ForegroundInfo(notificationId, notification);
   }

   @RequiresApi(Build.VERSION_CODES.O)
   private void createChannel() {
       // Create a Notification channel
   }
}

📖 장기 실행 worker에 포그라운드 서비스 유형 추가

⭐ 참고: 앱이 타겟팅하는 API 수준과 서비스가 실행하는 작업의 종류에 따라 포그라운드 서비스 유형을 선언해야 할 수 있음. 타겟팅하는 Android 버전과 관계없이 포그라운드 서비스 유형을 선언하는 것이 좋음.

앱이 Android 14 (API 수준 34) 이상을 타겟팅하는 경우 모든 장기 실행 worker의 포그라운드 서비스 유형을 지정해야함.

앱에서 Android 10 (API 수준 29) 이상을 타겟팅하고 위치에 액세스해야 하는 장기 실행 worker를 포함하는 경우 worker가 location의 포그라운드 서비스 유형을 사용함을 나타냄.

앱이 Android 11 (API 수준 30) 이상을 타겟팅하고 카메라 또는 마이크에 액세스해야 하는 장기 실행 worker를 포함하는 경우 각각 camera 또는 microphone 포그라운드 서비스 유형을 선언.

앱 매니페스트에서 포그라운드 서비스 유형 선언

앱 매니페스트에서 worker의 포그라운드 서비스 유형을 선언.

<service
   android:name="androidx.work.impl.foreground.SystemForegroundService"
   android:foregroundServiceType="location|microphone"
   tools:node="merge" />

런타임 시 포그라운드 서비스 유형 지정

setForeground() 또는 setForegroundAsync()를 호출할 때는 포그라운드 서비스 유형을 지정.

⭐ 참고: Android 14 (API 수준 34)부터 setForeground() 또는 setForegroundAsync()를 호출하면 시스템에서 서비스 유형에 따라 특정 기본 요건을 확인

private fun createForegroundInfo(progress: String): ForegroundInfo {
   // ...
   return ForegroundInfo(NOTIFICATION_ID, notification,
           FOREGROUND_SERVICE_TYPE_LOCATION or
FOREGROUND_SERVICE_TYPE_MICROPHONE) }

---

Worker 중간 진행률 관찰

WorkManager는 Worker의 중간 진행 상황을 설정하고 관찰할 수 있도록 지원 제공.
앱이 포그라운드에 있는 동안 Worker가 실행중인 경우 WorkInfo의 LiveData를 반환하는 API를 사용하여 이 정보를 사용자에게 표시할 수 있음.

ListenableWorker는 중간 진행 상황을 유지할 수 있는 setProgressAsync() API를 지원.
이 API를 사용하면 개발자는 UI에서 관찰할 수 있는 중간 진행 상황을 설정할 수 있음.
진행 상황은 직렬화 가능한 속성 컨테이너인 데이터 유형으로 표시됨.

진행 정보는 ListenableWorker가 실행되는 동안에만 관찰하고 업데이트할 수 있음.
ListenableWorker의 실행이 완료된 후 진행률을 설정하려는 시도는 무시됨.

getWorkInfoBy…() 또는 getWorkInfoBy…LiveData() 메서드 중 하나를 사용하여 진행 상황 정보를 관찰할 수도 있음.

이러한 메서드는 Data를 반환하는 새로운 getProgress() 메서드가 있는 WorkInfo의 인스턴스를 반환함.

📖 Update Progress

ListenableWorker 또는 Worker를 사용하는 Java 개발자의 경우 setProgressAsync() API는 ListenableFuture<Void>를 반환함.

업데이트 프로세스에는 진행률 정보를 데이터베이스에 저장하는 작업이 포함되므로 업데이트 진행률은 비동기식.

Kotlin에서는 CoroutineWorker 객체의 setProgress() 확장 함수를 사용하여 진행 정보를 업데이트할 수 있음.

//java
import android.content.Context;
import androidx.annotation.NonNull;
import androidx.work.Data;
import androidx.work.Worker;
import androidx.work.WorkerParameters;

public class ProgressWorker extends Worker {

    private static final String PROGRESS = "PROGRESS";
    private static final long DELAY = 1000L;

    public ProgressWorker(
        @NonNull Context context,
        @NonNull WorkerParameters parameters) {
        super(context, parameters);
        // Set initial progress to 0
        setProgressAsync(new Data.Builder().putInt(PROGRESS, 0).build());
    }

    @NonNull
    @Override
    public Result doWork() {
        try {
            // Doing work.
            Thread.sleep(DELAY);
        } catch (InterruptedException exception) {
            // ... handle exception
        }
        // Set progress to 100 after you are done doing your work.
        setProgressAsync(new Data.Builder().putInt(PROGRESS, 100).build());
        return Result.success();
    }
}

//kotlin
import android.content.Context
import androidx.work.CoroutineWorker
import androidx.work.Data
import androidx.work.WorkerParameters
import kotlinx.coroutines.delay

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

    companion object {
        const val Progress = "Progress"
        private const val delayDuration = 1L
    }

    override suspend fun doWork(): Result {
        val firstUpdate = workDataOf(Progress to 0)
        val lastUpdate = workDataOf(Progress to 100)
        setProgress(firstUpdate)
        delay(delayDuration)
        setProgress(lastUpdate)
        return Result.success()
    }
}

📖 Observing Progress

진행 정보를 관찰하기 위해 getWorkInfoBy…() 또는 getWorkInfoBy…LiveData() 메서드를 사용하고 WorkInfo에 대한 참조를 가져올 수 있음.

//java
WorkManager.getInstance(getApplicationContext())
     // requestId is the WorkRequest id
     .getWorkInfoByIdLiveData(requestId)
     .observe(lifecycleOwner, new Observer<WorkInfo>() {
             @Override
             public void onChanged(@Nullable WorkInfo workInfo) {
                 if (workInfo != null) {
                     Data progress = workInfo.getProgress();
                     int value = progress.getInt(PROGRESS, 0)
                     // Do something with progress
             }
      }
});

//kotlin
WorkManager.getInstance(applicationContext)
    // requestId is the WorkRequest id
    .getWorkInfoByIdLiveData(requestId)
    .observe(observer, Observer { workInfo: WorkInfo? ->
            if (workInfo != null) {
                val progress = workInfo.progress
                val value = progress.getInt(Progress, 0)
                // Do something with progress information
            }
    })

---

🔎 대기열에 추가된 작업 업데이트

WorkManager를 사용하면 이미 대기열에 추가한 WorkRequest를 업데이트할 수 있음.
제약 조건을 자주 변경하거나 작업자를 즉시 업데이트해야 하는 대규모 앱에서 종종 필요.
WorkManager 버전 2.8.0부터는 updateWork() API가 이를 수행.

updateWork() 메서드를 사용하면 새 항목을 수동으로 취소하고 대기열에 추가하는 과정을 거치지 않고도 즉시 변경 가능.

📖 작업 취소 피하기

일반적으로 기존 WorkRequest를 취소하고 새 WorkRequest를 대기열에 추가하는 것을 피해야함.
그렇게 하면 앱이 특정 작업을 반복하게 될 수 있으며 상당한 양의 추가 코드를 작성해야 할 수도 있음.

❗ WorkRequest를 취소하면 문제가 발생할 수 있는 예시
1. Back-end request
서버에 보낼 페이로드를 계산하는 동안 Worker를 취소하면 새 Worker는 처음부터 다시 시작하여 잠재적으로 비용이 많이 드는 페이로드를 다시 계산해야함.

2. Scheduling
PeriodicWorkRequest를 취소하고 새 PeriodicWorkRequest가 동일한 일정에 따라 실행되도록 하려면 새 실행 시간이 이전 작업 요청과 일치하는지 확인하기 위해 시간 오프셋을 계산해야함.

updateWork() API를 사용하면 새 요청을 취소하고 대기열에 추가하는 문제 없이 작업 요청의 제약 조건과 기타 매개변수를 업데이트할 수 있음.

작업을 취소해야 하는 경우

updateWork()를 호출하는 대신 WorkRequest를 직접 취소해야 하는 경우가 있음.
👉 대기열에 추가한 작업의 근본적 특성을 변경하려는 경우 수행해야하는 작업.

❗ 주의: updateWork()를 사용하여 WorkRequest의 Worker 유형을 변경할 수 없음. 예를 들어 OneTimeWorkRequest를 대기열에 추가하고 정기적으로 실행하려면 요청을 취소하고 새 PeriodicWorkRequest를 예약해야함.

작업을 업데이트해야 하는 경우

예:
사용자의 사진을 매일 백업하는 사진 앱이 있을 때, 이를 위해 PeriodicWorkRequest를 대기열에 추가.
WorkRequest에는 장치가 충전 중이고 Wi-Fi에 연결되어야 한다는 제약이 있음.
사용자는 급속 충전기를 이용해 하루에 20분만 기기를 충전. 이 경우 앱은 WorkRequest를 업데이트하여 충전 제한을 완화하여 기기가 완전히 충전되지 않은 경우에도 사진을 계속 업로드할 수 있음.

이 상황에서는 updateWork() 메서드를 사용하여 작업 요청의 제약 조건을 업데이트할 수 있음.

📖 작업 업데이트 방법

updateWork() 메서드는 새 WorkRequest를 취소하고 대기열에 추가할 필요 없이 기존 WorkRequest를 업데이트하는 간단한 방법을 제공.

• 업데이트 대기열에 포함된 작업을 사용하기 위한 단계
  
  1. 대기열에 추가된 작업의 기존 ID 가져오기
  업데이트하려는 WorkRequest의 ID를 가져옴. getWorkInfo API를 사용하거나 대기열에 넣기 전에 공용 속성 WorkRequest.id를 사용하여 나중에 검색할 수 있도록 초기 WorkRequest의 ID를 수동으로 유지하여 이 ID를 검색할 수 있음.
  
  2. 새 WorkRequest 만들기
  새 WorkRequest를 만들고 WorkRequest.Builder.setID()를 사용하여 기존 WorkRequest의 ID와 일치하도록 ID를 설정
  
  3. 제약 조건 설정
  WorkRequest.Builder.setConstraints()를 사용하여 WorkManager에 새 제약 조건을 전달.
  
  4.updateWork 호출
  새 WorkRequest를 updateWork()에 전달함.

• 예시
  updateWork() 메서드를 사용하여 사진을 업로드하는 데 사용되는 WorkRequest의 배터리 제약 조건을 변경하는 방법을 보여주는 예제.

suspend fun updatePhotoUploadWork() {
    // Get instance of WorkManager.
    val workManager = WorkManager.getInstance(context)

    // Retrieve the work request ID. In this example, the work being updated is unique
    // work so we can retrieve the ID using the unique work name.
    val photoUploadWorkInfoList = workManager.getWorkInfosForUniqueWork(
        PHOTO_UPLOAD_WORK_NAME
    ).await()

    val existingWorkRequestId = photoUploadWorkInfoList.firstOrNull()?.id ?: return

    // Update the constraints of the WorkRequest to not require a charging device.
    val newConstraints = Constraints.Builder()
        // Add other constraints as required here.
        .setRequiresCharging(false)
        .build()

    // Create new WorkRequest from existing Worker, new constraints, and the id of the old WorkRequest.
    val updatedWorkRequest: WorkRequest =
        OneTimeWorkRequestBuilder<MyWorker>()
            .setConstraints(newConstraints)
            .setId(existingWorkRequestId)
            .build()

    // Pass the new WorkRequest to updateWork().
    workManager.updateWork(updatedWorkRequest)
}

• 결과 처리하기
  updateWork()는 ListenableFuture<UpdateResult>를 반환함.
  지정된 UpdateResult에는 WorkManager가 변경 사항을 적용할 수 있는지 여부를 설명하는 여러 값 중 하나가 있을 수 있음.
  변경 사항을 적용할 수 있었던 시기도 표시됨.

📖 작업 추적하기

WorkRequest를 업데이트할 때마다 generation이 1씩 증가. 이를 통해 현재 큐에 추가된 WorkRequest를 정확하게 추적할 수 있음.
generation를 사용하면 작업 요청을 관찰, 추적, 테스트할 때 더 세밀하게 제어할 수 있음.

• WorkRequest의 generation을 얻기 위한 단계

1. WorkInfo
   WorkManager.getWorkInfoById()를 호출하여 WorkRequest에 해당하는 WorkInfo 인스턴스를 검색. WorkInfo를 반환하는 여러 메서드 중 하나를 호출할 수 있음.

2. getGeneration
   WorkInfo 인스턴스에서 getGeneration()을 호출. 반환된 Int는 WorkRequest generation에 해당.
   generation에 필드나 속성은 없고 WorkInfo.getGeneration() 메서드만 있음.

• 예시

// Get instance of WorkManager.
val workManager = WorkManager.getInstance(context)

// Retrieve WorkInfo instance.
val workInfo = workManager.getWorkInfoById(oldWorkRequestId)

// Call getGeneration to retrieve the generation.
val generation = workInfo.getGeneration()

📝 참고: updateWork()가 반환하는 UpdateResult에는 WorkRequest 생성이 포함되지 않음.

📖 작업 업데이트 정책

주기적 작업 업데이트에 권장되는 솔루션은 ExistingPeriodicWorkPolicy.REPLACE 정책을 사용하여 PeriodicWorkRequest를 대기열에 추가하는 것(동일한 고유 ID를 가진 보류 중인 PeriodicWorkRequest가 있는 경우 새 WorkRequest는 이를 취소하고 삭제함)이었으나

ExistingPeriodicWorkPolicy.UPDATE를 사용하는 워크플로를 위해 더 이상 사용되지 않음.

PeriodicWorkRequest와 함께 enqueueUniquePeriodicWork를 사용하는 경우 ExistingPeriodicWorkPolicy.UPDATE 정책을 사용하여 새 PeriodicWorkRequest를 초기화할 수 있음.

동일한 unique name을 가진 보류 중인 PeriodicWorkRequest가 있는 경우 WorkManager는 이를 새 사양으로 업데이트함.

이 워크플로를 따르면 updateWork()를 사용할 필요가 없음.

WorkManger 스레딩 페이지