1 /* 2 * Copyright (C) 2022 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 android.adservices.ondevicepersonalization; 18 19 import android.annotation.FlaggedApi; 20 import android.annotation.NonNull; 21 import android.annotation.Nullable; 22 23 import com.android.adservices.ondevicepersonalization.flags.Flags; 24 25 import java.util.Objects; 26 27 /** The input data for {@link IsolatedWorker#onTrainingExamples}. */ 28 public final class TrainingExamplesInput { 29 /** 30 * The name of the federated compute population. It should match the population name in {@link 31 * FederatedComputeInput#getPopulationName}. 32 */ 33 @NonNull private String mPopulationName = ""; 34 35 /** 36 * The name of the task within the population. It should match task plan configured at remote 37 * federated compute server. One population may have multiple tasks. The task name can be used 38 * to uniquely identify the job. 39 */ 40 @NonNull private String mTaskName = ""; 41 42 /** 43 * Token used to support the resumption of training. If client app wants to use resumption token 44 * to track what examples are already used in previous federated compute jobs, it need set 45 * {@link TrainingExampleRecord.Builder#setResumptionToken}, OnDevicePersonalization will store 46 * it and pass it here for generating new training examples. 47 */ 48 @Nullable private byte[] mResumptionToken = null; 49 50 /** 51 * The data collection name to use to create training examples. 52 */ 53 @Nullable private String mCollectionName; 54 55 /** @hide */ TrainingExamplesInput(@onNull TrainingExamplesInputParcel parcel)56 public TrainingExamplesInput(@NonNull TrainingExamplesInputParcel parcel) { 57 this( 58 parcel.getPopulationName(), 59 parcel.getTaskName(), 60 parcel.getResumptionToken(), 61 parcel.getCollectionName()); 62 } 63 64 /** 65 * Creates a new TrainingExamplesInput. 66 * 67 * @param populationName The name of the federated compute population. It should match the 68 * population name in {@link FederatedComputeInput#getPopulationName}. 69 * @param taskName The name of the task within the population. It should match task plan 70 * configured at remote federated compute server. One population may have multiple tasks. 71 * The task name can be used to uniquely identify the job. 72 * @param resumptionToken Token used to support the resumption of training. If client app wants 73 * to use resumption token to track what examples are already used in previous federated 74 * compute jobs, it need set {@link TrainingExampleRecord.Builder#setResumptionToken}, 75 * OnDevicePersonalization will store it and pass it here for generating new training 76 * examples. 77 * @param collectionName The data collection name to use to create training examples. 78 */ 79 @FlaggedApi(Flags.FLAG_DATA_CLASS_MISSING_CTORS_AND_GETTERS_ENABLED) TrainingExamplesInput( @onNull String populationName, @NonNull String taskName, @Nullable byte[] resumptionToken, @Nullable String collectionName)80 public TrainingExamplesInput( 81 @NonNull String populationName, 82 @NonNull String taskName, 83 @Nullable byte[] resumptionToken, 84 @Nullable String collectionName) { 85 this.mPopulationName = Objects.requireNonNull(populationName); 86 this.mTaskName = Objects.requireNonNull(taskName); 87 this.mResumptionToken = resumptionToken; 88 this.mCollectionName = collectionName; 89 } 90 91 /** 92 * The name of the federated compute population. It should match the population name in {@link 93 * FederatedComputeInput#getPopulationName}. 94 */ getPopulationName()95 public @NonNull String getPopulationName() { 96 return mPopulationName; 97 } 98 99 /** 100 * The name of the task within the population. It should match task plan configured at remote 101 * federated compute server. One population may have multiple tasks. The task name can be used 102 * to uniquely identify the job. 103 */ getTaskName()104 public @NonNull String getTaskName() { 105 return mTaskName; 106 } 107 108 /** 109 * Token used to support the resumption of training. If client app wants to use resumption token 110 * to track what examples are already used in previous federated compute jobs, it need set 111 * {@link TrainingExampleRecord.Builder#setResumptionToken}, OnDevicePersonalization will store 112 * it and pass it here for generating new training examples. 113 */ getResumptionToken()114 public @Nullable byte[] getResumptionToken() { 115 return mResumptionToken; 116 } 117 118 /** The data collection name to use to create training examples. */ 119 @FlaggedApi(Flags.FLAG_FCP_MODEL_VERSION_ENABLED) getCollectionName()120 public @Nullable String getCollectionName() { 121 return mCollectionName; 122 } 123 124 @Override equals(@ullable Object o)125 public boolean equals(@Nullable Object o) { 126 if (this == o) return true; 127 if (o == null || getClass() != o.getClass()) return false; 128 @SuppressWarnings("unchecked") 129 TrainingExamplesInput that = (TrainingExamplesInput) o; 130 //noinspection PointlessBooleanExpression 131 return true 132 && java.util.Objects.equals(mPopulationName, that.mPopulationName) 133 && java.util.Objects.equals(mTaskName, that.mTaskName) 134 && java.util.Arrays.equals(mResumptionToken, that.mResumptionToken) 135 && java.util.Objects.equals(mCollectionName, that.mCollectionName); 136 } 137 138 @Override hashCode()139 public int hashCode() { 140 int _hash = 1; 141 _hash = 31 * _hash + java.util.Objects.hashCode(mPopulationName); 142 _hash = 31 * _hash + java.util.Objects.hashCode(mTaskName); 143 _hash = 31 * _hash + java.util.Arrays.hashCode(mResumptionToken); 144 _hash = 31 * _hash + java.util.Objects.hashCode(mCollectionName); 145 return _hash; 146 } 147 } 148