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 android.app; 18 19 import android.annotation.IntDef; 20 import android.annotation.IntRange; 21 import android.annotation.NonNull; 22 import android.annotation.Nullable; 23 import android.annotation.SystemApi; 24 25 /** 26 * Represents a query that contains information required for StatsManager to return relevant metric 27 * data. 28 * 29 * @hide 30 */ 31 @SystemApi 32 public final class StatsQuery { 33 /** 34 * Default value for SQL dialect. 35 */ 36 public static final int DIALECT_UNKNOWN = 0; 37 38 /** 39 * Query passed is of SQLite dialect. 40 */ 41 public static final int DIALECT_SQLITE = 1; 42 43 /** 44 * @hide 45 */ 46 @IntDef(prefix = {"DIALECT_"}, value = {DIALECT_UNKNOWN, DIALECT_SQLITE}) 47 @interface SqlDialect { 48 } 49 50 private final int sqlDialect; 51 private final String rawSql; 52 private final int minClientSqlVersion; 53 private final byte[] policyConfig; StatsQuery(int sqlDialect, @NonNull String rawSql, int minClientSqlVersion, @Nullable byte[] policyConfig)54 private StatsQuery(int sqlDialect, @NonNull String rawSql, int minClientSqlVersion, 55 @Nullable byte[] policyConfig) { 56 this.sqlDialect = sqlDialect; 57 this.rawSql = rawSql; 58 this.minClientSqlVersion = minClientSqlVersion; 59 this.policyConfig = policyConfig; 60 } 61 62 /** 63 * Returns the SQL dialect of the query. 64 */ getSqlDialect()65 public @SqlDialect int getSqlDialect() { 66 return sqlDialect; 67 } 68 69 /** 70 * Returns the raw SQL of the query. 71 */ 72 @NonNull getRawSql()73 public String getRawSql() { 74 return rawSql; 75 } 76 77 /** 78 * Returns the minimum SQL client library version required to execute the query. 79 */ 80 @IntRange(from = 0) getMinSqlClientVersion()81 public int getMinSqlClientVersion() { 82 return minClientSqlVersion; 83 } 84 85 /** 86 * Returns the wire-encoded StatsPolicyConfig proto that contains information to verify the 87 * query against a policy defined on the underlying data. Returns null if no policy was set. 88 */ 89 @Nullable getPolicyConfig()90 public byte[] getPolicyConfig() { 91 return policyConfig; 92 } 93 94 /** 95 * Builder for constructing a StatsQuery object. 96 * <p>Usage:</p> 97 * <code> 98 * StatsQuery statsQuery = new StatsQuery.Builder("SELECT * from table") 99 * .setSqlDialect(StatsQuery.DIALECT_SQLITE) 100 * .setMinClientSqlVersion(1) 101 * .build(); 102 * </code> 103 */ 104 public static final class Builder { 105 private int sqlDialect; 106 private String rawSql; 107 private int minSqlClientVersion; 108 private byte[] policyConfig; 109 110 /** 111 * Returns a new StatsQuery.Builder object for constructing StatsQuery for 112 * StatsManager#query 113 */ Builder(@onNull final String rawSql)114 public Builder(@NonNull final String rawSql) { 115 if (rawSql == null) { 116 throw new IllegalArgumentException("rawSql must not be null"); 117 } 118 this.rawSql = rawSql; 119 this.sqlDialect = DIALECT_SQLITE; 120 this.minSqlClientVersion = 1; 121 this.policyConfig = null; 122 } 123 124 /** 125 * Sets the SQL dialect of the query. 126 * 127 * @param sqlDialect The SQL dialect of the query. 128 */ 129 @NonNull setSqlDialect(@qlDialect final int sqlDialect)130 public Builder setSqlDialect(@SqlDialect final int sqlDialect) { 131 this.sqlDialect = sqlDialect; 132 return this; 133 } 134 135 /** 136 * Sets the minimum SQL client library version required to execute the query. 137 * 138 * @param minSqlClientVersion The minimum SQL client version required to execute the query. 139 */ 140 @NonNull setMinSqlClientVersion(@ntRangefrom = 0) final int minSqlClientVersion)141 public Builder setMinSqlClientVersion(@IntRange(from = 0) final int minSqlClientVersion) { 142 if (minSqlClientVersion < 0) { 143 throw new IllegalArgumentException("minSqlClientVersion must be a " 144 + "positive integer"); 145 } 146 this.minSqlClientVersion = minSqlClientVersion; 147 return this; 148 } 149 150 /** 151 * Sets the wire-encoded StatsPolicyConfig proto that contains information to verify the 152 * query against a policy defined on the underlying data. 153 * 154 * @param policyConfig The wire-encoded StatsPolicyConfig proto. 155 */ 156 @NonNull setPolicyConfig(@onNull final byte[] policyConfig)157 public Builder setPolicyConfig(@NonNull final byte[] policyConfig) { 158 this.policyConfig = policyConfig; 159 return this; 160 } 161 162 /** 163 * Builds a new instance of {@link StatsQuery}. 164 * 165 * @return A new instance of {@link StatsQuery}. 166 */ 167 @NonNull build()168 public StatsQuery build() { 169 return new StatsQuery(sqlDialect, rawSql, minSqlClientVersion, policyConfig); 170 } 171 } 172 } 173