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.customaudience;
18 
19 import android.annotation.NonNull;
20 import android.annotation.Nullable;
21 import android.net.Uri;
22 import android.os.Parcel;
23 import android.os.Parcelable;
24 
25 import java.util.List;
26 import java.util.Objects;
27 
28 /**
29  * Represents data used during the ad selection process to fetch buyer bidding signals from a
30  * trusted key/value server. The fetched data is used during the ad selection process and consumed
31  * by buyer JavaScript logic running in an isolated execution environment.
32  */
33 public final class TrustedBiddingData implements Parcelable {
34     @NonNull private final Uri mTrustedBiddingUri;
35     @NonNull
36     private final List<String> mTrustedBiddingKeys;
37 
38     @NonNull
39     public static final Creator<TrustedBiddingData> CREATOR = new Creator<TrustedBiddingData>() {
40         @Override
41         public TrustedBiddingData createFromParcel(@NonNull Parcel in) {
42             Objects.requireNonNull(in);
43             return new TrustedBiddingData(in);
44         }
45 
46         @Override
47         public TrustedBiddingData[] newArray(int size) {
48             return new TrustedBiddingData[size];
49         }
50     };
51 
TrustedBiddingData(@onNull TrustedBiddingData.Builder builder)52     private TrustedBiddingData(@NonNull TrustedBiddingData.Builder builder) {
53         mTrustedBiddingUri = builder.mTrustedBiddingUri;
54         mTrustedBiddingKeys = builder.mTrustedBiddingKeys;
55     }
56 
TrustedBiddingData(@onNull Parcel in)57     private TrustedBiddingData(@NonNull Parcel in) {
58         Objects.requireNonNull(in);
59         mTrustedBiddingUri = Uri.CREATOR.createFromParcel(in);
60         mTrustedBiddingKeys = in.createStringArrayList();
61     }
62 
63     @Override
writeToParcel(@onNull Parcel dest, int flags)64     public void writeToParcel(@NonNull Parcel dest, int flags) {
65         Objects.requireNonNull(dest);
66         mTrustedBiddingUri.writeToParcel(dest, flags);
67         dest.writeStringList(mTrustedBiddingKeys);
68     }
69 
70     /** @hide */
71     @Override
describeContents()72     public int describeContents() {
73         return 0;
74     }
75 
76     /**
77      * @return the URI pointing to the trusted key-value server holding bidding signals. The URI
78      *     must use HTTPS.
79      */
80     @NonNull
getTrustedBiddingUri()81     public Uri getTrustedBiddingUri() {
82         return mTrustedBiddingUri;
83     }
84 
85     /**
86      * @return the list of keys to query from the trusted key-value server holding bidding signals
87      */
88     @NonNull
getTrustedBiddingKeys()89     public List<String> getTrustedBiddingKeys() {
90         return mTrustedBiddingKeys;
91     }
92 
93     /**
94      * @return {@code true} if two {@link TrustedBiddingData} objects contain the same information
95      */
96     @Override
equals(Object o)97     public boolean equals(Object o) {
98         if (this == o) return true;
99         if (!(o instanceof TrustedBiddingData)) return false;
100         TrustedBiddingData that = (TrustedBiddingData) o;
101         return mTrustedBiddingUri.equals(that.mTrustedBiddingUri)
102                 && mTrustedBiddingKeys.equals(that.mTrustedBiddingKeys);
103     }
104 
105     /**
106      * @return the hash of the {@link TrustedBiddingData} object's data
107      */
108     @Override
hashCode()109     public int hashCode() {
110         return Objects.hash(mTrustedBiddingUri, mTrustedBiddingKeys);
111     }
112 
113     /** Builder for {@link TrustedBiddingData} objects. */
114     public static final class Builder {
115         @Nullable private Uri mTrustedBiddingUri;
116         @Nullable private List<String> mTrustedBiddingKeys;
117 
118         // TODO(b/232883403): We may need to add @NonNUll members as args.
Builder()119         public Builder() {
120         }
121 
122         /**
123          * Sets the URI pointing to a trusted key-value server used to fetch bidding signals during
124          * the ad selection process. The URI must use HTTPS.
125          */
126         @NonNull
setTrustedBiddingUri(@onNull Uri trustedBiddingUri)127         public Builder setTrustedBiddingUri(@NonNull Uri trustedBiddingUri) {
128             Objects.requireNonNull(trustedBiddingUri);
129             mTrustedBiddingUri = trustedBiddingUri;
130             return this;
131         }
132 
133         /**
134          * Sets the list of keys to query the trusted key-value server with.
135          * <p>
136          * This list is permitted to be empty, but it must not be null.
137          */
138         @NonNull
setTrustedBiddingKeys(@onNull List<String> trustedBiddingKeys)139         public Builder setTrustedBiddingKeys(@NonNull List<String> trustedBiddingKeys) {
140             Objects.requireNonNull(trustedBiddingKeys);
141             mTrustedBiddingKeys = trustedBiddingKeys;
142             return this;
143         }
144 
145         /**
146          * Builds the {@link TrustedBiddingData} object.
147          *
148          * @throws NullPointerException if any parameters are null when built
149          */
150         @NonNull
build()151         public TrustedBiddingData build() {
152             Objects.requireNonNull(mTrustedBiddingUri);
153             // Note that the list of keys is allowed to be empty, but not null
154             Objects.requireNonNull(mTrustedBiddingKeys);
155 
156             return new TrustedBiddingData(this);
157         }
158     }
159 }
160