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.publisher; 18 19 import android.annotation.NonNull; 20 import android.annotation.Nullable; 21 import android.car.telemetry.TelemetryProto; 22 23 import com.android.car.telemetry.databroker.DataSubscriber; 24 import com.android.car.telemetry.sessioncontroller.SessionAnnotation; 25 26 import java.util.List; 27 28 /** 29 * Abstract class for publishers. It is 1-1 with data source and manages sending data to 30 * subscribers. Publisher stops itself when there are no subscribers. 31 * 32 * <p>Note that it doesn't map 1-1 to {@link android.car.telemetry.TelemetryProto.Publisher} 33 * configuration. Single publisher instance can send data as several 34 * {@link android.car.telemetry.TelemetryProto.Publisher} to subscribers. 35 * 36 * <p>The methods must be called from the telemetry thread. 37 */ 38 public abstract class AbstractPublisher { 39 private final PublisherListener mPublisherListener; 40 41 /** 42 * Listener for publisher updates, such as failing to connect to a underlying service or 43 * invalid Publisher configuration. 44 */ 45 public interface PublisherListener { 46 /** 47 * Called by publishers when they fail. 48 * When publishers fail, the affected configs should be disabled, because the associated 49 * scripts cannot receive data from the failed publishers. 50 */ onPublisherFailure( @onNull List<TelemetryProto.MetricsConfig> affectedConfigs, @Nullable Throwable error)51 void onPublisherFailure( 52 @NonNull List<TelemetryProto.MetricsConfig> affectedConfigs, 53 @Nullable Throwable error); 54 55 /** 56 * Called by publishers when a config satisfies terminating conditions. 57 */ onConfigFinished(@onNull TelemetryProto.MetricsConfig metricsConfig)58 void onConfigFinished(@NonNull TelemetryProto.MetricsConfig metricsConfig); 59 } 60 AbstractPublisher(@onNull PublisherListener listener)61 AbstractPublisher(@NonNull PublisherListener listener) { 62 mPublisherListener = listener; 63 } 64 65 /** 66 * Handles driving session update changes. Must be overridden by concrete publisher classes. 67 * 68 * @param annotation Contains annotating information about the state change. 69 */ handleSessionStateChange(@onNull SessionAnnotation annotation)70 protected abstract void handleSessionStateChange(@NonNull SessionAnnotation annotation); 71 72 /** 73 * Adds a subscriber that listens for data produced by this publisher. 74 * 75 * <p>DataBroker may call this method when a new {@code MetricsConfig} is added, 76 * {@code CarTelemetryService} is restarted or the device is restarted. 77 * 78 * @param subscriber a subscriber to receive data 79 * @throws IllegalArgumentException if the subscriber is invalid. 80 * @throws IllegalStateException if there are internal errors. 81 */ addDataSubscriber(@onNull DataSubscriber subscriber)82 public abstract void addDataSubscriber(@NonNull DataSubscriber subscriber); 83 84 /** 85 * Removes the subscriber from the publisher. Publisher stops if necessary. 86 * 87 * <p>It does nothing if subscriber is not found. 88 */ removeDataSubscriber(@onNull DataSubscriber subscriber)89 public abstract void removeDataSubscriber(@NonNull DataSubscriber subscriber); 90 91 /** 92 * Removes all the subscribers from the publisher. The publisher may stop. 93 * 94 * <p>This method also cleans-up internal publisher and the data source persisted state. 95 */ removeAllDataSubscribers()96 public abstract void removeAllDataSubscribers(); 97 98 /** Returns true if the publisher already has this data subscriber. */ hasDataSubscriber(@onNull DataSubscriber subscriber)99 public abstract boolean hasDataSubscriber(@NonNull DataSubscriber subscriber); 100 101 /** 102 * Notifies the PublisherListener that this publisher failed. 103 */ onPublisherFailure( @onNull List<TelemetryProto.MetricsConfig> affectedConfigs, @NonNull Throwable error)104 protected void onPublisherFailure( 105 @NonNull List<TelemetryProto.MetricsConfig> affectedConfigs, @NonNull Throwable error) { 106 mPublisherListener.onPublisherFailure(affectedConfigs, error); 107 } 108 109 /** 110 * Notifies the PublisherListener that a MetricsConfig should be marked as finished. 111 */ onConfigFinished(@onNull TelemetryProto.MetricsConfig metricsConfig)112 protected void onConfigFinished(@NonNull TelemetryProto.MetricsConfig metricsConfig) { 113 mPublisherListener.onConfigFinished(metricsConfig); 114 } 115 } 116