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 an AutoValue builder for a {@link DBHistogramEventData} object. */ 83 @NonNull builder()84 public static DBHistogramEventData.Builder builder() { 85 return new AutoValue_DBHistogramEventData.Builder().setRowId(null); 86 } 87 88 /** 89 * Creates a {@link DBHistogramEventData} object using the builder. 90 * 91 * <p>Required for Room SQLite integration. 92 */ 93 @NonNull create( @ullable Long rowId, long histogramIdentifierForeignKey, @FrequencyCapFilters.AdEventType int adEventType, @NonNull Instant timestamp)94 public static DBHistogramEventData create( 95 @Nullable Long rowId, 96 long histogramIdentifierForeignKey, 97 @FrequencyCapFilters.AdEventType int adEventType, 98 @NonNull Instant timestamp) { 99 return builder() 100 .setRowId(rowId) 101 .setHistogramIdentifierForeignKey(histogramIdentifierForeignKey) 102 .setAdEventType(adEventType) 103 .setTimestamp(timestamp) 104 .build(); 105 } 106 107 /** 108 * Creates and returns a new {@link DBHistogramEventData} object from the given foreign key ID 109 * and {@link HistogramEvent}. 110 */ 111 @NonNull fromHistogramEvent( long foreignKey, @NonNull HistogramEvent event)112 public static DBHistogramEventData fromHistogramEvent( 113 long foreignKey, @NonNull HistogramEvent event) { 114 Objects.requireNonNull(event); 115 return builder() 116 .setHistogramIdentifierForeignKey(foreignKey) 117 .setAdEventType(event.getAdEventType()) 118 .setTimestamp(event.getTimestamp()) 119 .build(); 120 } 121 122 /** Builder class for a {@link DBHistogramEventData} object. */ 123 @AutoValue.Builder 124 public abstract static class Builder { 125 /** 126 * Returns the internal row ID of the event data in the histogram event data datastore. 127 * 128 * <p>This ID is only used internally in the frequency cap histogram event data table and 129 * does not need to be stable or reproducible. It is auto-generated by Room if set to {@code 130 * null} on insertion. 131 */ 132 @NonNull setRowId(Long rowId)133 public abstract Builder setRowId(Long rowId); 134 135 /** 136 * Sets the numerical ID linking this event data to its associated {@link 137 * DBHistogramIdentifier}. 138 * 139 * <p>This ID is only used internally in the frequency cap histogram tables and does not 140 * need to be stable or reproducible. 141 */ 142 @NonNull setHistogramIdentifierForeignKey( long histogramIdentifierForeignKey)143 public abstract Builder setHistogramIdentifierForeignKey( 144 long histogramIdentifierForeignKey); 145 146 /** Sets the enumerated type of the ad event. */ 147 @NonNull setAdEventType(int adEventType)148 public abstract Builder setAdEventType(int adEventType); 149 150 /** Sets the timestamp for the event. */ 151 @NonNull setTimestamp(@onNull Instant timestamp)152 public abstract Builder setTimestamp(@NonNull Instant timestamp); 153 154 /** 155 * Builds and returns the {@link DBHistogramEventData} object. 156 * 157 * @throws IllegalStateException if any field is unset when the object is built 158 */ 159 @NonNull build()160 public abstract DBHistogramEventData build(); 161 } 162 } 163