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.adselection; 18 19 import android.annotation.NonNull; 20 import android.annotation.Nullable; 21 import android.net.Uri; 22 23 import com.android.internal.util.Preconditions; 24 25 import java.util.Objects; 26 27 /** 28 * This class represents a field in the {@code OutcomeReceiver}, which is an input to the {@link 29 * AdSelectionManager#selectAds} in the {@link AdSelectionManager}. This field is populated in the 30 * case of a successful {@link AdSelectionManager#selectAds} call. 31 * 32 */ 33 public class AdSelectionOutcome { 34 /** 35 * Represents an AdSelectionOutcome with empty results. 36 * 37 * @hide 38 */ 39 @NonNull public static final AdSelectionOutcome NO_OUTCOME = new AdSelectionOutcome(); 40 41 /** @hide */ 42 public static final String UNSET_AD_SELECTION_ID_MESSAGE = "Ad selection ID must be set"; 43 44 /** @hide */ 45 public static final int UNSET_AD_SELECTION_ID = 0; 46 47 private final long mAdSelectionId; 48 @NonNull private final Uri mRenderUri; 49 AdSelectionOutcome()50 private AdSelectionOutcome() { 51 mAdSelectionId = UNSET_AD_SELECTION_ID; 52 mRenderUri = Uri.EMPTY; 53 } 54 AdSelectionOutcome(long adSelectionId, @NonNull Uri renderUri)55 private AdSelectionOutcome(long adSelectionId, @NonNull Uri renderUri) { 56 Objects.requireNonNull(renderUri); 57 58 mAdSelectionId = adSelectionId; 59 mRenderUri = renderUri; 60 } 61 62 /** Returns the renderUri that the AdSelection returns. */ 63 @NonNull getRenderUri()64 public Uri getRenderUri() { 65 return mRenderUri; 66 } 67 68 /** Returns the adSelectionId that identifies the AdSelection. */ 69 @NonNull getAdSelectionId()70 public long getAdSelectionId() { 71 return mAdSelectionId; 72 } 73 74 /** 75 * Returns whether the outcome contains results or empty. Empty outcomes' {@code render uris} 76 * shouldn't be used. 77 * 78 * @hide 79 */ hasOutcome()80 public boolean hasOutcome() { 81 return !this.equals(NO_OUTCOME); 82 } 83 84 @Override equals(Object o)85 public boolean equals(Object o) { 86 if (o instanceof AdSelectionOutcome) { 87 AdSelectionOutcome adSelectionOutcome = (AdSelectionOutcome) o; 88 return mAdSelectionId == adSelectionOutcome.mAdSelectionId 89 && Objects.equals(mRenderUri, adSelectionOutcome.mRenderUri); 90 } 91 return false; 92 } 93 94 @Override hashCode()95 public int hashCode() { 96 return Objects.hash(mAdSelectionId, mRenderUri); 97 } 98 99 /** 100 * Builder for {@link AdSelectionOutcome} objects. 101 */ 102 public static final class Builder { 103 private long mAdSelectionId = UNSET_AD_SELECTION_ID; 104 @Nullable private Uri mRenderUri; 105 Builder()106 public Builder() {} 107 108 /** Sets the mAdSelectionId. */ 109 @NonNull setAdSelectionId(long adSelectionId)110 public AdSelectionOutcome.Builder setAdSelectionId(long adSelectionId) { 111 this.mAdSelectionId = adSelectionId; 112 return this; 113 } 114 115 /** Sets the RenderUri. */ 116 @NonNull setRenderUri(@onNull Uri renderUri)117 public AdSelectionOutcome.Builder setRenderUri(@NonNull Uri renderUri) { 118 Objects.requireNonNull(renderUri); 119 120 mRenderUri = renderUri; 121 return this; 122 } 123 124 /** 125 * Builds a {@link AdSelectionOutcome} instance. 126 * 127 * @throws IllegalArgumentException if the adSelectionIid is not set 128 * @throws NullPointerException if the RenderUri is null 129 */ 130 @NonNull build()131 public AdSelectionOutcome build() { 132 Objects.requireNonNull(mRenderUri); 133 134 Preconditions.checkArgument( 135 mAdSelectionId != UNSET_AD_SELECTION_ID, UNSET_AD_SELECTION_ID_MESSAGE); 136 137 return new AdSelectionOutcome(mAdSelectionId, mRenderUri); 138 } 139 } 140 } 141