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