1 /* 2 * Copyright (C) 2020 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.server.alarm; 18 19 import android.os.SystemClock; 20 import android.util.IndentingPrintWriter; 21 import android.util.proto.ProtoOutputStream; 22 23 import java.io.FileDescriptor; 24 import java.text.SimpleDateFormat; 25 import java.util.ArrayList; 26 import java.util.function.Predicate; 27 28 /** 29 * Used by {@link AlarmManagerService} to store alarms. 30 * Besides basic add and remove operations, supports querying the next upcoming alarm times, 31 * and all the alarms that are due at a given time. 32 */ 33 public interface AlarmStore { 34 35 /** 36 * Adds the given alarm. 37 * 38 * @param a The alarm to add. 39 */ add(Alarm a)40 void add(Alarm a); 41 42 /** 43 * Adds all the given alarms to this store. 44 * 45 * @param alarms The alarms to add. 46 */ addAll(ArrayList<Alarm> alarms)47 void addAll(ArrayList<Alarm> alarms); 48 49 /** 50 * Removes alarms that pass the given predicate. 51 * 52 * @param whichAlarms The predicate describing the alarms to remove. 53 * @return a list containing alarms that were removed. 54 */ remove(Predicate<Alarm> whichAlarms)55 ArrayList<Alarm> remove(Predicate<Alarm> whichAlarms); 56 57 /** 58 * Set a listener to be invoked whenever an alarm clock is removed by a call to 59 * {@link #remove(Predicate) remove} from this store. 60 */ setAlarmClockRemovalListener(Runnable listener)61 void setAlarmClockRemovalListener(Runnable listener); 62 63 /** 64 * Gets the earliest alarm with the flag {@link android.app.AlarmManager#FLAG_WAKE_FROM_IDLE} 65 * based on {@link Alarm#getWhenElapsed()}. 66 * 67 * @return An alarm object matching the description above or {@code null} if no such alarm was 68 * found. 69 */ getNextWakeFromIdleAlarm()70 Alarm getNextWakeFromIdleAlarm(); 71 72 /** 73 * Returns the total number of alarms in this store. 74 */ size()75 int size(); 76 77 /** 78 * Get the next wakeup delivery time of all alarms in this store. 79 * 80 * @return a long timestamp in the {@link SystemClock#elapsedRealtime() elapsed} 81 * timebase. 82 */ getNextWakeupDeliveryTime()83 long getNextWakeupDeliveryTime(); 84 85 /** 86 * Get the next delivery time of all alarms in this store. 87 * 88 * @return a long timestamp in the {@link SystemClock#elapsedRealtime() elapsed} 89 * timebase. May or may not be the same as {{@link #getNextWakeupDeliveryTime()}}. 90 */ getNextDeliveryTime()91 long getNextDeliveryTime(); 92 93 /** 94 * Removes all alarms that are pending delivery at the given time. 95 * 96 * @param nowElapsed The time at which delivery eligibility is evaluated. 97 * @return The list of alarms pending at the given time. 98 */ removePendingAlarms(long nowElapsed)99 ArrayList<Alarm> removePendingAlarms(long nowElapsed); 100 101 /** 102 * Adjusts alarm deliveries for all alarms according to the passed 103 * {@link AlarmDeliveryCalculator} 104 * 105 * @return {@code true} if any of the alarm deliveries changed due to this call. 106 */ updateAlarmDeliveries(AlarmDeliveryCalculator deliveryCalculator)107 boolean updateAlarmDeliveries(AlarmDeliveryCalculator deliveryCalculator); 108 109 /** 110 * Returns all the alarms in the form of a list. 111 */ asList()112 ArrayList<Alarm> asList(); 113 114 /** 115 * Dumps the state of this alarm store into the passed print writer. Also accepts the current 116 * timestamp and a {@link SimpleDateFormat} to format the timestamps as human readable delta 117 * from the current time. 118 * 119 * Primary useful for debugging. Can be called from the 120 * {@link android.os.Binder#dump(FileDescriptor PrintWriter, String[]) dump} method of the 121 * caller. 122 * 123 * @param ipw The {@link IndentingPrintWriter} to write to. 124 * @param nowElapsed the time when the dump is requested in the 125 * {@link SystemClock#elapsedRealtime() 126 * elapsed} timebase. 127 * @param sdf the date format to print timestamps in. 128 */ dump(IndentingPrintWriter ipw, long nowElapsed, SimpleDateFormat sdf)129 void dump(IndentingPrintWriter ipw, long nowElapsed, SimpleDateFormat sdf); 130 131 /** 132 * Dump the state of this alarm store as a proto buffer to the given stream. 133 */ dumpProto(ProtoOutputStream pos, long nowElapsed)134 void dumpProto(ProtoOutputStream pos, long nowElapsed); 135 136 /** 137 * @return a name for this alarm store that can be used for debugging and tests. 138 */ getName()139 String getName(); 140 141 /** 142 * Returns the number of alarms that satisfy the given condition. 143 */ getCount(Predicate<Alarm> condition)144 int getCount(Predicate<Alarm> condition); 145 146 /** 147 * A functional interface used to update the alarm. Used to describe the update in 148 * {@link #updateAlarmDeliveries(AlarmDeliveryCalculator)} 149 */ 150 @FunctionalInterface 151 interface AlarmDeliveryCalculator { 152 /** 153 * Updates the given alarm's delivery time. 154 * 155 * @param a the alarm to update. 156 * @return {@code true} if any change was made, {@code false} otherwise. 157 */ updateAlarmDelivery(Alarm a)158 boolean updateAlarmDelivery(Alarm a); 159 } 160 } 161