1 /*
2  * Copyright (C) 2024 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.adservices.shared.spe.framework;
18 
19 import static com.android.internal.annotations.VisibleForTesting.Visibility.PACKAGE;
20 
21 import android.annotation.IntDef;
22 import android.content.Context;
23 
24 import com.android.internal.annotations.VisibleForTesting;
25 
26 import java.lang.annotation.Retention;
27 import java.lang.annotation.RetentionPolicy;
28 import java.util.Objects;
29 
30 /**
31  * Enums used in {@link JobWorker#getExecutionFuture(Context, ExecutionRuntimeParameters)} to set
32  * the result dynamically based on the execution future, if needed.
33  *
34  * <p>In most of the time, it should set {@link #SUCCESS} in {@link
35  * JobWorker#getExecutionFuture(Context, ExecutionRuntimeParameters)}.
36  */
37 public final class ExecutionResult {
38     @IntDef(
39             value = {
40                 RESULT_CODE_SUCCESS,
41                 RESULT_CODE_FAILURE_WITHOUT_RETRY,
42                 RESULT_CODE_FAILURE_WITH_RETRY,
43                 RESULT_CODE_CANCELLED_BY_SCHEDULER
44             })
45     @Retention(RetentionPolicy.SOURCE)
46     private @interface ExecutionResultCode {}
47 
48     // Indicates the execution finishes without issue.
49     private static final int RESULT_CODE_SUCCESS = 0;
50 
51     // Indicates the execution is failed and doesn't need to do the execution again.
52     private static final int RESULT_CODE_FAILURE_WITHOUT_RETRY = 1;
53 
54     // Indicates the execution is failed and needs to do the execution again.
55     private static final int RESULT_CODE_FAILURE_WITH_RETRY = 2;
56 
57     // Indicates the execution future is cancelled by the platform scheduler for various of reasons.
58     // For example, user cancellation action, constraint not met, etc.
59     private static final int RESULT_CODE_CANCELLED_BY_SCHEDULER = 3;
60 
61     /**
62      * A {@link ExecutionResult} instance that indicates the execution finishes successfully.
63      *
64      * <p>This value should be used for most of the jobs, usually not computing the result based on
65      * the execution future. That says, if you don't know which value to use, use this one.
66      */
67     public static final ExecutionResult SUCCESS = new ExecutionResult(RESULT_CODE_SUCCESS);
68 
69     /**
70      * A {@link ExecutionResult} instance that indicates the execution is failed and doesn't need to
71      * do the execution again.
72      */
73     public static final ExecutionResult FAILURE_WITHOUT_RETRY =
74             new ExecutionResult(RESULT_CODE_FAILURE_WITHOUT_RETRY);
75 
76     /**
77      * A {@link ExecutionResult} instance that indicates the execution is failed and doesn't need to
78      * do the execution again.
79      */
80     public static final ExecutionResult FAILURE_WITH_RETRY =
81             new ExecutionResult(RESULT_CODE_FAILURE_WITH_RETRY);
82 
83     // A ExecutionResult that indicates the execution future is cancelled by the platform scheduler
84     // for various of reasons. For example, user cancellation action, constraint not met, etc.
85     //
86     // Note: This value is ONLY used by SPE (Scheduling Policy Engine) framework, and you
87     // should NEVER set this value for your job.
88     @VisibleForTesting(visibility = PACKAGE)
89     public static final ExecutionResult CANCELLED_BY_SCHEDULER =
90             new ExecutionResult(RESULT_CODE_CANCELLED_BY_SCHEDULER);
91 
92     @ExecutionResultCode private final int mExecutionResultCode;
93 
ExecutionResult(@xecutionResultCode int resultCode)94     private ExecutionResult(@ExecutionResultCode int resultCode) {
95         mExecutionResultCode = resultCode;
96     }
97 
98     @Override
equals(Object o)99     public boolean equals(Object o) {
100         if (this == o) return true;
101         if (!(o instanceof ExecutionResult that)) return false;
102         return mExecutionResultCode == that.mExecutionResultCode;
103     }
104 
105     @Override
hashCode()106     public int hashCode() {
107         return Objects.hash(mExecutionResultCode);
108     }
109 
110     @Override
toString()111     public String toString() {
112         return switch (mExecutionResultCode) {
113             case RESULT_CODE_SUCCESS -> "SUCCESS";
114             case RESULT_CODE_FAILURE_WITH_RETRY -> "FAILURE_WITH_RETRY";
115             case RESULT_CODE_FAILURE_WITHOUT_RETRY -> "FAILURE_WITHOUT_RETRY";
116             case RESULT_CODE_CANCELLED_BY_SCHEDULER -> "CANCELLED_BY_SCHEDULER";
117             default -> "Invalid Result Code: " + mExecutionResultCode;
118         };
119     }
120 }
121