1 /* 2 * Copyright (C) 2021 The Android Open Source Project 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17 package com.android.server.backup; 18 19 import android.annotation.IntDef; 20 21 import java.lang.annotation.Retention; 22 import java.lang.annotation.RetentionPolicy; 23 import java.util.Set; 24 25 /** 26 * OperationStorage is an abstraction around a set of active operations. 27 * 28 * Operations are registered with a token that must first be obtained from 29 * {@link UserBackupManagerService#generateRandomIntegerToken()}. When 30 * registering, the caller may also associate a set of package names with 31 * the operation. 32 * 33 * TODO(b/208442527): have the token be generated within and returned by 34 * registerOperation, as it should be an internal detail. 35 * 36 * Operations have a type and a state. Although ints, the values that can 37 * be used are defined in {@link UserBackupManagerService}. If the type of 38 * an operation is OP_BACKUP, then it represents a task running backups. The 39 * task is provided when registering the operation because it provides a 40 * handle to cancel the backup. 41 */ 42 public interface OperationStorage { 43 44 @Retention(RetentionPolicy.SOURCE) 45 @IntDef({ 46 OpState.PENDING, 47 OpState.ACKNOWLEDGED, 48 OpState.TIMEOUT 49 }) 50 public @interface OpState { 51 // The operation is in progress. 52 int PENDING = 0; 53 // The operation has been acknowledged. 54 int ACKNOWLEDGED = 1; 55 // The operation has timed out. 56 int TIMEOUT = -1; 57 } 58 59 @Retention(RetentionPolicy.SOURCE) 60 @IntDef({ 61 OpType.BACKUP_WAIT, 62 OpType.RESTORE_WAIT, 63 OpType.BACKUP, 64 }) 65 public @interface OpType { 66 // Waiting for backup agent to respond during backup operation. 67 int BACKUP_WAIT = 0; 68 // Waiting for backup agent to respond during restore operation. 69 int RESTORE_WAIT = 1; 70 // An entire backup operation spanning multiple packages. 71 int BACKUP = 2; 72 } 73 74 /** 75 * Record an ongoing operation of given type and in the given initial 76 * state. The associated task is used as a callback. 77 * 78 * @param token an operation token issued by 79 * {@link UserBackupManagerService#generateRandomIntegerToken()} 80 * @param initialState the state that the operation starts in 81 * @param task the {@link BackupRestoreTask} that is expected to 82 * remove the operation on completion, and which may 83 * be notified if the operation requires cancelling. 84 * @param type the type of the operation. 85 */ registerOperation(int token, @OpState int initialState, BackupRestoreTask task, @OpType int type)86 void registerOperation(int token, @OpState int initialState, 87 BackupRestoreTask task, @OpType int type); 88 89 /** 90 * See {@link #registerOperation()}. In addition this method accepts a set 91 * of package names which are associated with the operation. 92 * 93 * @param token See {@link #registerOperation()} 94 * @param initialState See {@link #registerOperation()} 95 * @param packageNames the package names to associate with the operation. 96 * @param task See {@link #registerOperation()} 97 * @param type See {@link #registerOperation()} 98 */ registerOperationForPackages(int token, @OpState int initialState, Set<String> packageNames, BackupRestoreTask task, @OpType int type)99 void registerOperationForPackages(int token, @OpState int initialState, 100 Set<String> packageNames, BackupRestoreTask task, @OpType int type); 101 102 /** 103 * Remove the operation identified by token. This is called when the 104 * operation is no longer in progress and should be dropped. Any association 105 * with package names provided in {@link #registerOperation()} is dropped as 106 * well. 107 * 108 * @param token the operation token specified when registering the operation. 109 */ removeOperation(int token)110 void removeOperation(int token); 111 112 /** 113 * Obtain the number of currently registered operations. 114 * 115 * @return the number of currently registered operations. 116 */ numOperations()117 int numOperations(); 118 119 /** 120 * Determine if a backup operation is in progress or not. 121 * 122 * @return true if any operation is registered of type BACKUP and in 123 * state PENDING. 124 */ isBackupOperationInProgress()125 boolean isBackupOperationInProgress(); 126 127 /** 128 * Obtain a set of operation tokens for all pending operations that were 129 * registered with an association to the specified package name. 130 * 131 * @param packageName the name of the package used at registration time 132 * 133 * @return a set of operation tokens associated to package name. 134 */ operationTokensForPackage(String packageName)135 Set<Integer> operationTokensForPackage(String packageName); 136 137 /** 138 * Obtain a set of operation tokens for all pending operations that are 139 * of the specified operation type. 140 * 141 * @param type the type of the operation provided at registration time. 142 * 143 * @return a set of operation tokens for operations of that type. 144 */ operationTokensForOpType(@pType int type)145 Set<Integer> operationTokensForOpType(@OpType int type); 146 147 /** 148 * Obtain a set of operation tokens for all pending operations that are 149 * currently in the specified operation state. 150 * 151 * @param state the state of the operation. 152 * 153 * @return a set of operation tokens for operations in that state. 154 */ operationTokensForOpState(@pState int state)155 Set<Integer> operationTokensForOpState(@OpState int state); 156 } 157