1 /*
2  * Copyright (C) 2023 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.data.adselection;
18 
19 import android.adservices.common.FrequencyCapFilters;
20 
21 import androidx.annotation.NonNull;
22 import androidx.annotation.Nullable;
23 import androidx.room.ColumnInfo;
24 import androidx.room.Entity;
25 import androidx.room.PrimaryKey;
26 
27 import com.android.adservices.service.adselection.HistogramEvent;
28 
29 import com.google.auto.value.AutoValue;
30 
31 import java.time.Instant;
32 import java.util.Objects;
33 
34 /**
35  * POJO for a single ad event which was registered by an adtech.
36  *
37  * <p>These events are used to compute frequency histograms to be used during ad selection
38  * filtering.
39  */
40 @AutoValue
41 @AutoValue.CopyAnnotations
42 @Entity(tableName = DBHistogramEventData.TABLE_NAME, inheritSuperIndices = true)
43 public abstract class DBHistogramEventData {
44     public static final String TABLE_NAME = "fcap_histogram_data";
45 
46     /**
47      * Returns the internal row ID of the event data in the histogram event data datastore.
48      *
49      * <p>This ID is only used internally in the frequency cap histogram event data table and does
50      * not need to be stable or reproducible. It is auto-generated by Room if set to {@code null} on
51      * insertion.
52      */
53     @AutoValue.CopyAnnotations
54     @ColumnInfo(name = "row_id")
55     @PrimaryKey(autoGenerate = true)
56     @Nullable
getRowId()57     public abstract Long getRowId();
58 
59     /**
60      * Returns the numerical ID linking this event data to its associated {@link
61      * DBHistogramIdentifier}.
62      *
63      * <p>This ID is only used internally in the frequency cap histogram tables and does not need to
64      * be stable or reproducible.
65      */
66     @AutoValue.CopyAnnotations
67     @ColumnInfo(name = "foreign_key_id", index = true)
getHistogramIdentifierForeignKey()68     public abstract long getHistogramIdentifierForeignKey();
69 
70     /** Returns the enumerated type of the ad event. */
71     @AutoValue.CopyAnnotations
72     @ColumnInfo(name = "ad_event_type", index = true)
73     @FrequencyCapFilters.AdEventType
getAdEventType()74     public abstract int getAdEventType();
75 
76     /** Returns the timestamp for the event. */
77     @AutoValue.CopyAnnotations
78     @ColumnInfo(name = "timestamp", index = true)
79     @NonNull
getTimestamp()80     public abstract Instant getTimestamp();
81 
82     /** Returns the arbitrary integer the event data is keyed on. */
83     @AutoValue.CopyAnnotations
84     @ColumnInfo(name = "ad_counter_int_key", defaultValue = "0", index = true)
getAdCounterIntKey()85     public abstract int getAdCounterIntKey();
86 
87     /** Returns an AutoValue builder for a {@link DBHistogramEventData} object. */
88     @NonNull
builder()89     public static DBHistogramEventData.Builder builder() {
90         return new AutoValue_DBHistogramEventData.Builder().setRowId(null);
91     }
92 
93     /**
94      * Creates a {@link DBHistogramEventData} object using the builder.
95      *
96      * <p>Required for Room SQLite integration.
97      */
98     @NonNull
create( @ullable Long rowId, long histogramIdentifierForeignKey, @FrequencyCapFilters.AdEventType int adEventType, @NonNull Instant timestamp, int adCounterIntKey)99     public static DBHistogramEventData create(
100             @Nullable Long rowId,
101             long histogramIdentifierForeignKey,
102             @FrequencyCapFilters.AdEventType int adEventType,
103             @NonNull Instant timestamp,
104             int adCounterIntKey) {
105         return builder()
106                 .setRowId(rowId)
107                 .setHistogramIdentifierForeignKey(histogramIdentifierForeignKey)
108                 .setAdEventType(adEventType)
109                 .setTimestamp(timestamp)
110                 .setAdCounterIntKey(adCounterIntKey)
111                 .build();
112     }
113 
114     /**
115      * Creates and returns a new {@link DBHistogramEventData} object from the given foreign key ID
116      * and {@link HistogramEvent}.
117      */
118     @NonNull
fromHistogramEvent( long foreignKey, @NonNull HistogramEvent event)119     public static DBHistogramEventData fromHistogramEvent(
120             long foreignKey, @NonNull HistogramEvent event) {
121         Objects.requireNonNull(event);
122         return builder()
123                 .setHistogramIdentifierForeignKey(foreignKey)
124                 .setAdEventType(event.getAdEventType())
125                 .setTimestamp(event.getTimestamp())
126                 .setAdCounterIntKey(event.getAdCounterKey())
127                 .build();
128     }
129 
130     /** Builder class for a {@link DBHistogramEventData} object. */
131     @AutoValue.Builder
132     public abstract static class Builder {
133         /**
134          * Returns the internal row ID of the event data in the histogram event data datastore.
135          *
136          * <p>This ID is only used internally in the frequency cap histogram event data table and
137          * does not need to be stable or reproducible. It is auto-generated by Room if set to {@code
138          * null} on insertion.
139          */
140         @NonNull
setRowId(Long rowId)141         public abstract Builder setRowId(Long rowId);
142 
143         /**
144          * Sets the numerical ID linking this event data to its associated {@link
145          * DBHistogramIdentifier}.
146          *
147          * <p>This ID is only used internally in the frequency cap histogram tables and does not
148          * need to be stable or reproducible.
149          */
150         @NonNull
setHistogramIdentifierForeignKey( long histogramIdentifierForeignKey)151         public abstract Builder setHistogramIdentifierForeignKey(
152                 long histogramIdentifierForeignKey);
153 
154         /** Sets the enumerated type of the ad event. */
155         @NonNull
setAdEventType(int adEventType)156         public abstract Builder setAdEventType(int adEventType);
157 
158         /** Sets the timestamp for the event. */
159         @NonNull
setTimestamp(@onNull Instant timestamp)160         public abstract Builder setTimestamp(@NonNull Instant timestamp);
161 
162         /** Sets the arbitrary integer the event data is keyed on. */
163         @NonNull
setAdCounterIntKey(int adCounterKey)164         public abstract Builder setAdCounterIntKey(int adCounterKey);
165 
166         /**
167          * Builds and returns the {@link DBHistogramEventData} object.
168          *
169          * @throws IllegalStateException if any field is unset when the object is built
170          */
171         @NonNull
build()172         public abstract DBHistogramEventData build();
173     }
174 }
175