1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/mobile/android/base/background/healthreport/HealthReportStorage.java Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,238 @@
1.4 +/* This Source Code Form is subject to the terms of the Mozilla Public
1.5 + * License, v. 2.0. If a copy of the MPL was not distributed with this
1.6 + * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
1.7 +
1.8 +package org.mozilla.gecko.background.healthreport;
1.9 +
1.10 +import org.json.JSONObject;
1.11 +
1.12 +import android.database.Cursor;
1.13 +import android.util.SparseArray;
1.14 +
1.15 +/**
1.16 + * Abstraction over storage for Firefox Health Report on Android.
1.17 + */
1.18 +public interface HealthReportStorage {
1.19 + // Right now we only care about the name of the field.
1.20 + public interface MeasurementFields {
1.21 + public class FieldSpec {
1.22 + public final String name;
1.23 + public final int type;
1.24 + public FieldSpec(String name, int type) {
1.25 + this.name = name;
1.26 + this.type = type;
1.27 + }
1.28 + }
1.29 + Iterable<FieldSpec> getFields();
1.30 + }
1.31 +
1.32 + public abstract class Field {
1.33 + protected static final int UNKNOWN_TYPE_OR_FIELD_ID = -1;
1.34 +
1.35 + protected static final int FLAG_INTEGER = 1 << 0;
1.36 + protected static final int FLAG_STRING = 1 << 1;
1.37 + protected static final int FLAG_JSON = 1 << 2;
1.38 +
1.39 + protected static final int FLAG_DISCRETE = 1 << 8;
1.40 + protected static final int FLAG_LAST = 1 << 9;
1.41 + protected static final int FLAG_COUNTER = 1 << 10;
1.42 +
1.43 + protected static final int FLAG_COUNTED = 1 << 14;
1.44 +
1.45 + public static final int TYPE_INTEGER_DISCRETE = FLAG_INTEGER | FLAG_DISCRETE;
1.46 + public static final int TYPE_INTEGER_LAST = FLAG_INTEGER | FLAG_LAST;
1.47 + public static final int TYPE_INTEGER_COUNTER = FLAG_INTEGER | FLAG_COUNTER;
1.48 +
1.49 + public static final int TYPE_STRING_DISCRETE = FLAG_STRING | FLAG_DISCRETE;
1.50 + public static final int TYPE_STRING_LAST = FLAG_STRING | FLAG_LAST;
1.51 +
1.52 + public static final int TYPE_JSON_DISCRETE = FLAG_JSON | FLAG_DISCRETE;
1.53 + public static final int TYPE_JSON_LAST = FLAG_JSON | FLAG_LAST;
1.54 +
1.55 + public static final int TYPE_COUNTED_STRING_DISCRETE = FLAG_COUNTED | TYPE_STRING_DISCRETE;
1.56 +
1.57 + protected int fieldID = UNKNOWN_TYPE_OR_FIELD_ID;
1.58 + protected int flags;
1.59 +
1.60 + protected final String measurementName;
1.61 + protected final String measurementVersion;
1.62 + protected final String fieldName;
1.63 +
1.64 + public Field(String mName, int mVersion, String fieldName, int type) {
1.65 + this.measurementName = mName;
1.66 + this.measurementVersion = Integer.toString(mVersion, 10);
1.67 + this.fieldName = fieldName;
1.68 + this.flags = type;
1.69 + }
1.70 +
1.71 + /**
1.72 + * @return the ID for this <code>Field</code>
1.73 + * @throws IllegalStateException if this field is not found in storage
1.74 + */
1.75 + public abstract int getID() throws IllegalStateException;
1.76 +
1.77 + public boolean isIntegerField() {
1.78 + return (this.flags & FLAG_INTEGER) > 0;
1.79 + }
1.80 +
1.81 + public boolean isStringField() {
1.82 + return (this.flags & FLAG_STRING) > 0;
1.83 + }
1.84 +
1.85 + public boolean isJSONField() {
1.86 + return (this.flags & FLAG_JSON) > 0;
1.87 + }
1.88 +
1.89 + public boolean isStoredAsString() {
1.90 + return (this.flags & (FLAG_JSON | FLAG_STRING)) > 0;
1.91 + }
1.92 +
1.93 + public boolean isDiscreteField() {
1.94 + return (this.flags & FLAG_DISCRETE) > 0;
1.95 + }
1.96 +
1.97 + /**
1.98 + * True if the accrued values are intended to be bucket-counted. For strings,
1.99 + * each discrete value will name a bucket, with the number of instances per
1.100 + * day being the value in the bucket.
1.101 + */
1.102 + public boolean isCountedField() {
1.103 + return (this.flags & FLAG_COUNTED) > 0;
1.104 + }
1.105 + }
1.106 +
1.107 + /**
1.108 + * Close open storage handles and otherwise finish up.
1.109 + */
1.110 + public void close();
1.111 +
1.112 + /**
1.113 + * Return the day integer corresponding to the provided time.
1.114 + *
1.115 + * @param time
1.116 + * milliseconds since Unix epoch.
1.117 + * @return an integer day.
1.118 + */
1.119 + public int getDay(long time);
1.120 +
1.121 + /**
1.122 + * Return the day integer corresponding to the current time.
1.123 + *
1.124 + * @return an integer day.
1.125 + */
1.126 + public int getDay();
1.127 +
1.128 + /**
1.129 + * Return a new {@link Environment}, suitable for being populated, hashed, and
1.130 + * registered.
1.131 + *
1.132 + * @return a new {@link Environment} instance.
1.133 + */
1.134 + public Environment getEnvironment();
1.135 +
1.136 + /**
1.137 + * @return a mapping from environment IDs to hashes, suitable for use in
1.138 + * payload generation.
1.139 + */
1.140 + public SparseArray<String> getEnvironmentHashesByID();
1.141 +
1.142 + /**
1.143 + * @return a mapping from environment IDs to registered {@link Environment}
1.144 + * records, suitable for use in payload generation.
1.145 + */
1.146 + public SparseArray<Environment> getEnvironmentRecordsByID();
1.147 +
1.148 + /**
1.149 + * @param id
1.150 + * the environment ID, as returned by {@link Environment#register()}.
1.151 + * @return a cursor for the record.
1.152 + */
1.153 + public Cursor getEnvironmentRecordForID(int id);
1.154 +
1.155 + /**
1.156 + * @param measurement
1.157 + * the name of a measurement, such as "org.mozilla.appInfo.appInfo".
1.158 + * @param measurementVersion
1.159 + * the version of a measurement, such as '3'.
1.160 + * @param fieldName
1.161 + * the name of a field, such as "platformVersion".
1.162 + *
1.163 + * @return a {@link Field} instance corresponding to the provided values.
1.164 + */
1.165 + public Field getField(String measurement, int measurementVersion,
1.166 + String fieldName);
1.167 +
1.168 + /**
1.169 + * @return a mapping from field IDs to {@link Field} instances, suitable for
1.170 + * use in payload generation.
1.171 + */
1.172 + public SparseArray<Field> getFieldsByID();
1.173 +
1.174 + public void recordDailyLast(int env, int day, int field, JSONObject value);
1.175 + public void recordDailyLast(int env, int day, int field, String value);
1.176 + public void recordDailyLast(int env, int day, int field, int value);
1.177 + public void recordDailyDiscrete(int env, int day, int field, JSONObject value);
1.178 + public void recordDailyDiscrete(int env, int day, int field, String value);
1.179 + public void recordDailyDiscrete(int env, int day, int field, int value);
1.180 + public void incrementDailyCount(int env, int day, int field, int by);
1.181 + public void incrementDailyCount(int env, int day, int field);
1.182 +
1.183 + /**
1.184 + * Return true if events exist that were recorded on or after <code>time</code>.
1.185 + */
1.186 + boolean hasEventSince(long time);
1.187 +
1.188 + /**
1.189 + * Obtain a cursor over events that were recorded since <code>time</code>.
1.190 + * This cursor exposes 'raw' events, with integer identifiers for values.
1.191 + */
1.192 + public Cursor getRawEventsSince(long time);
1.193 +
1.194 + /**
1.195 + * Obtain a cursor over events that were recorded since <code>time</code>.
1.196 + *
1.197 + * This cursor exposes 'friendly' events, with string names and full
1.198 + * measurement metadata.
1.199 + */
1.200 + public Cursor getEventsSince(long time);
1.201 +
1.202 + /**
1.203 + * Ensure that a measurement and all of its fields are registered with the DB.
1.204 + * No fields will be processed if the measurement exists with the specified
1.205 + * version.
1.206 + *
1.207 + * @param measurement
1.208 + * a measurement name, such as "org.mozila.appInfo.appInfo".
1.209 + * @param version
1.210 + * a version number, such as '3'.
1.211 + * @param fields
1.212 + * a {@link MeasurementFields} instance, consisting of a collection
1.213 + * of field names.
1.214 + */
1.215 + public void ensureMeasurementInitialized(String measurement,
1.216 + int version,
1.217 + MeasurementFields fields);
1.218 + public Cursor getMeasurementVersions();
1.219 + public Cursor getFieldVersions();
1.220 + public Cursor getFieldVersions(String measurement, int measurementVersion);
1.221 +
1.222 + public void deleteEverything();
1.223 + public void deleteEnvironments();
1.224 + public void deleteMeasurements();
1.225 + /**
1.226 + * Deletes all environments, addons, and events from the database before the given time.
1.227 + *
1.228 + * @param time milliseconds since epoch.
1.229 + * @param curEnv The ID of the current environment.
1.230 + * @return The number of environments and addon entries deleted.
1.231 + */
1.232 + public int deleteDataBefore(final long time, final int curEnv);
1.233 +
1.234 + public int getEventCount();
1.235 + public int getEnvironmentCount();
1.236 +
1.237 + public void pruneEvents(final int num);
1.238 + public void pruneEnvironments(final int num);
1.239 +
1.240 + public void enqueueOperation(Runnable runnable);
1.241 +}
