1 /* 2 * Copyright 2022 Google LLC 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 package com.google.android.libraries.mobiledatadownload.internal; 17 18 import com.google.android.libraries.mobiledatadownload.internal.collect.GroupKeyAndGroup; 19 import com.google.common.util.concurrent.ListenableFuture; 20 import com.google.mobiledatadownload.internal.MetadataProto.DataFileGroupInternal; 21 import com.google.mobiledatadownload.internal.MetadataProto.GroupKey; 22 import com.google.mobiledatadownload.internal.MetadataProto.GroupKeyProperties; 23 import java.util.List; 24 import org.checkerframework.checker.nullness.compatqual.NullableType; 25 26 /** Stores and provides access to file group metadata. */ 27 public interface FileGroupsMetadata { 28 29 /** 30 * Makes any changes that should be made before accessing the internal state of this store. 31 * 32 * <p>Other methods in this class do not call or check if this method was already called before 33 * trying to access internal state. It is expected from the caller to call this before anything 34 * else. 35 */ init()36 ListenableFuture<Void> init(); 37 38 /** Returns a future resolving to the DataFileGroupInternal associated with key "groupKey". */ read(GroupKey groupKey)39 ListenableFuture<@NullableType DataFileGroupInternal> read(GroupKey groupKey); 40 41 /** 42 * Maps the key "groupKey" to the value "fileGroup" in the store. Returns future resolving to true 43 * if the operation succeeds, and false if not. 44 */ 45 // TODO(b/159828199): This method should return a Void future and signal failure using exceptions 46 // instead of a Boolean. write(GroupKey groupKey, DataFileGroupInternal fileGroup)47 ListenableFuture<Boolean> write(GroupKey groupKey, DataFileGroupInternal fileGroup); 48 49 /** 50 * Removes the DataFileGroupInternal associated with the key "groupKey" in the store. Returns 51 * future resolving to true if the operation succeeds, and false if not. 52 */ remove(GroupKey groupKey)53 ListenableFuture<Boolean> remove(GroupKey groupKey); 54 55 /** Returns a future resolving to the GroupKeyProperties associated with the key "groupKey". */ readGroupKeyProperties(GroupKey groupKey)56 ListenableFuture<@NullableType GroupKeyProperties> readGroupKeyProperties(GroupKey groupKey); 57 58 /** 59 * Maps the key "groupKey" to the value "groupKeyProperties" in the store. Returns future 60 * resolving to true if the operation succeeds, and false if not. 61 */ writeGroupKeyProperties( GroupKey groupKey, GroupKeyProperties groupKeyProperties)62 ListenableFuture<Boolean> writeGroupKeyProperties( 63 GroupKey groupKey, GroupKeyProperties groupKeyProperties); 64 65 /** Returns all keys in the store. */ getAllGroupKeys()66 ListenableFuture<List<GroupKey>> getAllGroupKeys(); 67 68 /** 69 * Retrieves all groups in metadata. Will ignore groups that are unable to parse. 70 * 71 * @return A future resolving to a list containing pairs of serialized GroupKeys and the 72 * corresponding DataFileGroups. 73 */ getAllFreshGroups()74 ListenableFuture<List<GroupKeyAndGroup>> getAllFreshGroups(); 75 76 /** 77 * Removes all entries with a key in keys from the SharedPreferencesFileGroupsMetadata's storage. 78 * This method doesn't take care of garbage collecting any files used by this group, and that is 79 * left for the caller to do. 80 * 81 * @param keys - the list of keys to remove entries for 82 * @return - true if the removals were successfully persisted to disk. 83 */ removeAllGroupsWithKeys(List<GroupKey> keys)84 ListenableFuture<Boolean> removeAllGroupsWithKeys(List<GroupKey> keys); 85 86 /** 87 * Retrieves all file groups on device that are marked as stale. 88 * 89 * @return Future resolving to a list of DataFileGroupInternal's stored in the garbage collection 90 * file or an empty list if an IO error occurs or if the file doesn't exist (because all 91 * previous groups had been deleted and no new groups had been added). 92 */ getAllStaleGroups()93 ListenableFuture<List<DataFileGroupInternal>> getAllStaleGroups(); 94 95 /** 96 * Adds file group to list of file groups to unsubscribe from when their TTLs expire. This method 97 * will set the staleExpirationDate field on the file group. 98 * 99 * @param fileGroup - a file group that is no longer needed (and should release all of its files 100 * once its TTL expires). The staleLifetimeSecs field must be set. 101 * @return future resolving to false if an IO error occurs 102 */ addStaleGroup(DataFileGroupInternal fileGroup)103 ListenableFuture<Boolean> addStaleGroup(DataFileGroupInternal fileGroup); 104 105 /** 106 * Write an array of stale file groups into garbage collector file. 107 * 108 * @param fileGroups - an array of file groups to write to garbage collection file 109 * @return future resolving to false if an IO error occurs 110 */ writeStaleGroups(List<DataFileGroupInternal> fileGroups)111 ListenableFuture<Boolean> writeStaleGroups(List<DataFileGroupInternal> fileGroups); 112 113 /** Deletes all storage for stale file groups. */ removeAllStaleGroups()114 ListenableFuture<Void> removeAllStaleGroups(); 115 116 /** Clears all storage used by the SharedPreferencesFileGroupsMetadata class. */ clear()117 ListenableFuture<Void> clear(); 118 } 119