1 /* 2 * Copyright (C) 2021 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.car.telemetry.databroker; 18 19 import android.annotation.NonNull; 20 import android.annotation.Nullable; 21 import android.car.telemetry.TelemetryProto; 22 import android.os.PersistableBundle; 23 24 /** Interface for the data path. Handles data forwarding from publishers to subscribers */ 25 public interface DataBroker { 26 27 /** 28 * Interface for receiving notification from DataBroker. 29 */ 30 interface DataBrokerListener { 31 /** 32 * Called when subscribers consumed an event and an interim state should be saved as a 33 * result. 34 * @param metricsConfigName that uniquely identifies the config whose script finished. 35 * @param state an interim state to be saved for the next script execution. 36 */ onEventConsumed(@onNull String metricsConfigName, @NonNull PersistableBundle state)37 void onEventConsumed(@NonNull String metricsConfigName, @NonNull PersistableBundle state); 38 39 /** 40 * Called when a MetricsConfig's lifecycle ends without a report or error. 41 * 42 * @param metricsConfigName that uniquely identifies the config whose script finished. 43 */ onReportFinished(@onNull String metricsConfigName)44 void onReportFinished(@NonNull String metricsConfigName); 45 46 /** 47 * Called when a MetricsConfig's lifecycle ends and a metrics report is produced by it. 48 * 49 * @param metricsConfigName that uniquely identifies the config whose script finished. 50 * @param report the final report produced by the MetricsConfig. 51 */ onReportFinished(@onNull String metricsConfigName, @NonNull PersistableBundle report)52 void onReportFinished(@NonNull String metricsConfigName, @NonNull PersistableBundle report); 53 54 /** 55 * Called when a MetricsConfig's lifecycle ends and an error is produced. 56 * 57 * @param metricsConfigName that uniquely identifies the config that terminated. 58 */ onReportFinished( @onNull String metricsConfigName, @NonNull TelemetryProto.TelemetryError error)59 void onReportFinished( 60 @NonNull String metricsConfigName, 61 @NonNull TelemetryProto.TelemetryError error); 62 63 /** 64 * Called when a MetricsConfig produces a metrics report without ending its lifecycle. 65 * 66 * @param metricsConfigName that uniquely identifies the config whose script produced a 67 * report. 68 * @param report the metrics report. 69 * @param state optional state to persist for the next script execution. 70 */ onMetricsReport( @onNull String metricsConfigName, @NonNull PersistableBundle report, @Nullable PersistableBundle state)71 void onMetricsReport( 72 @NonNull String metricsConfigName, 73 @NonNull PersistableBundle report, 74 @Nullable PersistableBundle state); 75 } 76 77 /** 78 * Adds an active {@link android.car.telemetry.TelemetryProto.MetricsConfig} that is pending 79 * execution. When updating the MetricsConfig to a newer version, the caller must call 80 * {@link #removeMetricsConfig(String)} first to clear the old MetricsConfig. 81 * @param metricsConfigName name of the MetricsConfig. 82 * @param metricsConfig to be added and queued for execution. 83 */ addMetricsConfig( @onNull String metricsConfigName, @NonNull TelemetryProto.MetricsConfig metricsConfig)84 void addMetricsConfig( 85 @NonNull String metricsConfigName, @NonNull TelemetryProto.MetricsConfig metricsConfig); 86 87 /** 88 * Removes a {@link android.car.telemetry.TelemetryProto.MetricsConfig} and all its 89 * relevant subscriptions. 90 * 91 * @param metricsConfigName to identify the MetricsConfig to be removed. 92 */ removeMetricsConfig(@onNull String metricsConfigName)93 void removeMetricsConfig(@NonNull String metricsConfigName); 94 95 /** 96 * Removes all {@link android.car.telemetry.TelemetryProto.MetricsConfig}s and subscriptions. 97 */ removeAllMetricsConfigs()98 void removeAllMetricsConfigs(); 99 100 /** 101 * Adds a {@link ScriptExecutionTask} to the priority queue. This method will schedule the 102 * next task if a task is not currently running. 103 * 104 * @param task The task that contains the script and published data for ScriptExecutor. 105 * @return The number of tasks that are pending execution that are produced by the calling 106 * publisher. 107 */ addTaskToQueue(@onNull ScriptExecutionTask task)108 int addTaskToQueue(@NonNull ScriptExecutionTask task); 109 110 /** 111 * Checks system health state and executes a task if condition allows. 112 */ scheduleNextTask()113 void scheduleNextTask(); 114 115 /** 116 * Sets listener for DataBroker events. 117 */ setDataBrokerListener(@onNull DataBrokerListener dataBrokerListener)118 void setDataBrokerListener(@NonNull DataBrokerListener dataBrokerListener); 119 120 /** 121 * Sets the priority which affects which subscribers can consume data. Invoked by controller to 122 * indicate system health state and which subscribers can be consumed. If controller does not 123 * set the priority, it will be defaulted to 1. A smaller priority number indicates higher 124 * priority. Range 0 - 100. A priority of 0 means the script should run regardless of system 125 * health conditions. 126 */ setTaskExecutionPriority(int priority)127 void setTaskExecutionPriority(int priority); 128 } 129