1 /*
2  * Copyright 2021 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.app.appsearch;
18 
19 import android.annotation.CurrentTimeMillisLong;
20 import android.annotation.NonNull;
21 import android.app.appsearch.annotation.CanIgnoreReturnValue;
22 
23 import java.util.Objects;
24 
25 /**
26  * A request to report usage of a document owned by another app from a system UI surface.
27  *
28  * <p>Usage reported in this way is measured separately from usage reported via {@link
29  * AppSearchSession#reportUsage}.
30  *
31  * <p>See {@link GlobalSearchSession#reportSystemUsage} for a detailed description of usage
32  * reporting.
33  */
34 public final class ReportSystemUsageRequest {
35     private final String mPackageName;
36     private final String mDatabase;
37     private final String mNamespace;
38     private final String mDocumentId;
39     private final long mUsageTimestampMillis;
40 
ReportSystemUsageRequest( @onNull String packageName, @NonNull String database, @NonNull String namespace, @NonNull String documentId, long usageTimestampMillis)41     ReportSystemUsageRequest(
42             @NonNull String packageName,
43             @NonNull String database,
44             @NonNull String namespace,
45             @NonNull String documentId,
46             long usageTimestampMillis) {
47         mPackageName = Objects.requireNonNull(packageName);
48         mDatabase = Objects.requireNonNull(database);
49         mNamespace = Objects.requireNonNull(namespace);
50         mDocumentId = Objects.requireNonNull(documentId);
51         mUsageTimestampMillis = usageTimestampMillis;
52     }
53 
54     /** Returns the package name of the app which owns the document that was used. */
55     @NonNull
getPackageName()56     public String getPackageName() {
57         return mPackageName;
58     }
59 
60     /** Returns the database in which the document that was used resides. */
61     @NonNull
getDatabaseName()62     public String getDatabaseName() {
63         return mDatabase;
64     }
65 
66     /** Returns the namespace of the document that was used. */
67     @NonNull
getNamespace()68     public String getNamespace() {
69         return mNamespace;
70     }
71 
72     /** Returns the ID of document that was used. */
73     @NonNull
getDocumentId()74     public String getDocumentId() {
75         return mDocumentId;
76     }
77 
78     /**
79      * Returns the timestamp in milliseconds of the usage report (the time at which the document was
80      * used).
81      *
82      * <p>The value is in the {@link System#currentTimeMillis} time base.
83      */
84     @CurrentTimeMillisLong
getUsageTimestampMillis()85     public long getUsageTimestampMillis() {
86         return mUsageTimestampMillis;
87     }
88 
89     /** Builder for {@link ReportSystemUsageRequest} objects. */
90     public static final class Builder {
91         private final String mPackageName;
92         private final String mDatabase;
93         private final String mNamespace;
94         private final String mDocumentId;
95         private Long mUsageTimestampMillis;
96 
97         /**
98          * Creates a {@link ReportSystemUsageRequest.Builder} instance.
99          *
100          * @param packageName The package name of the app which owns the document that was used
101          *     (such as from {@link SearchResult#getPackageName}).
102          * @param databaseName The database in which the document that was used resides (such as
103          *     from {@link SearchResult#getDatabaseName}).
104          * @param namespace The namespace of the document that was used (such as from {@link
105          *     GenericDocument#getNamespace}.
106          * @param documentId The ID of document that was used (such as from {@link
107          *     GenericDocument#getId}.
108          */
Builder( @onNull String packageName, @NonNull String databaseName, @NonNull String namespace, @NonNull String documentId)109         public Builder(
110                 @NonNull String packageName,
111                 @NonNull String databaseName,
112                 @NonNull String namespace,
113                 @NonNull String documentId) {
114             mPackageName = Objects.requireNonNull(packageName);
115             mDatabase = Objects.requireNonNull(databaseName);
116             mNamespace = Objects.requireNonNull(namespace);
117             mDocumentId = Objects.requireNonNull(documentId);
118         }
119 
120         /**
121          * Sets the timestamp in milliseconds of the usage report (the time at which the document
122          * was used).
123          *
124          * <p>The value is in the {@link System#currentTimeMillis} time base.
125          *
126          * <p>If unset, this defaults to the current timestamp at the time that the {@link
127          * ReportSystemUsageRequest} is constructed.
128          */
129         @CanIgnoreReturnValue
130         @NonNull
setUsageTimestampMillis( @urrentTimeMillisLong long usageTimestampMillis)131         public ReportSystemUsageRequest.Builder setUsageTimestampMillis(
132                 @CurrentTimeMillisLong long usageTimestampMillis) {
133             mUsageTimestampMillis = usageTimestampMillis;
134             return this;
135         }
136 
137         /** Builds a new {@link ReportSystemUsageRequest}. */
138         @NonNull
build()139         public ReportSystemUsageRequest build() {
140             if (mUsageTimestampMillis == null) {
141                 mUsageTimestampMillis = System.currentTimeMillis();
142             }
143             return new ReportSystemUsageRequest(
144                     mPackageName, mDatabase, mNamespace, mDocumentId, mUsageTimestampMillis);
145         }
146     }
147 }
148