com/android/server/alarm/AlarmStore.java

/*
 * Copyright (C) 2020 The Android Open Source Project
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package com.android.server.alarm;

import android.os.SystemClock;
import android.util.IndentingPrintWriter;
import android.util.proto.ProtoOutputStream;

import java.io.FileDescriptor;
import java.text.SimpleDateFormat;
import java.util.ArrayList;
import java.util.function.Predicate;

/**
 * Used by {@link AlarmManagerService} to store alarms.
 * Besides basic add and remove operations, supports querying the next upcoming alarm times,
 * and all the alarms that are due at a given time.
 */
public interface AlarmStore {

    /**
     * Adds the given alarm.
     *
     * @param a The alarm to add.
     */
    void add(Alarm a);

    /**
     * Adds all the given alarms to this store.
     *
     * @param alarms The alarms to add.
     */
    void addAll(ArrayList<Alarm> alarms);

    /**
     * Removes alarms that pass the given predicate.
     *
     * @param whichAlarms The predicate describing the alarms to remove.
     * @return a list containing alarms that were removed.
     */
    ArrayList<Alarm> remove(Predicate<Alarm> whichAlarms);

    /**
     * Set a listener to be invoked whenever an alarm clock is removed by a call to
     * {@link #remove(Predicate) remove} from this store.
     */
    void setAlarmClockRemovalListener(Runnable listener);

    /**
     * Gets the earliest alarm with the flag {@link android.app.AlarmManager#FLAG_WAKE_FROM_IDLE}
     * based on {@link Alarm#getWhenElapsed()}.
     *
     * @return An alarm object matching the description above or {@code null} if no such alarm was
     * found.
     */
    Alarm getNextWakeFromIdleAlarm();

    /**
     * Returns the total number of alarms in this store.
     */
    int size();

    /**
     * Get the next wakeup delivery time of all alarms in this store.
     *
     * @return a long timestamp in the {@link SystemClock#elapsedRealtime() elapsed}
     * timebase.
     */
    long getNextWakeupDeliveryTime();

    /**
     * Get the next delivery time of all alarms in this store.
     *
     * @return a long timestamp in the {@link SystemClock#elapsedRealtime() elapsed}
     * timebase. May or may not be the same as {{@link #getNextWakeupDeliveryTime()}}.
     */
    long getNextDeliveryTime();

    /**
     * Removes all alarms that are pending delivery at the given time.
     *
     * @param nowElapsed The time at which delivery eligibility is evaluated.
     * @return The list of alarms pending at the given time.
     */
    ArrayList<Alarm> removePendingAlarms(long nowElapsed);

    /**
     * Adjusts alarm deliveries for all alarms according to the passed
     * {@link AlarmDeliveryCalculator}
     *
     * @return {@code true} if any of the alarm deliveries changed due to this call.
     */
    boolean updateAlarmDeliveries(AlarmDeliveryCalculator deliveryCalculator);

    /**
     * Returns all the alarms in the form of a list.
     */
    ArrayList<Alarm> asList();

    /**
     * Dumps the state of this alarm store into the passed print writer. Also accepts the current
     * timestamp and a {@link SimpleDateFormat} to format the timestamps as human readable delta
     * from the current time.
     *
     * Primary useful for debugging. Can be called from the
     * {@link android.os.Binder#dump(FileDescriptor PrintWriter, String[]) dump} method of the
     * caller.
     *
     * @param ipw        The {@link IndentingPrintWriter} to write to.
     * @param nowElapsed the time when the dump is requested in the
     *                   {@link SystemClock#elapsedRealtime()
     *                   elapsed} timebase.
     * @param sdf        the date format to print timestamps in.
     */
    void dump(IndentingPrintWriter ipw, long nowElapsed, SimpleDateFormat sdf);

    /**
     * Dump the state of this alarm store as a proto buffer to the given stream.
     */
    void dumpProto(ProtoOutputStream pos, long nowElapsed);

    /**
     * @return a name for this alarm store that can be used for debugging and tests.
     */
    String getName();

    /**
     * Returns the number of alarms that satisfy the given condition.
     */
    int getCount(Predicate<Alarm> condition);

    /**
     * A functional interface used to update the alarm. Used to describe the update in
     * {@link #updateAlarmDeliveries(AlarmDeliveryCalculator)}
     */
    @FunctionalInterface
    interface AlarmDeliveryCalculator {
        /**
         * Updates the given alarm's delivery time.
         *
         * @param a the alarm to update.
         * @return {@code true} if any change was made, {@code false} otherwise.
         */
        boolean updateAlarmDelivery(Alarm a);
    }
}