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.location.listeners; 18 19 import android.annotation.Nullable; 20 21 import com.android.internal.listeners.ListenerExecutor; 22 23 import java.util.Objects; 24 import java.util.concurrent.Executor; 25 26 /** 27 * A listener registration object which holds data associated with the listener, such as an optional 28 * request, and an executor responsible for listener invocations. 29 * 30 * @param <TListener> listener type 31 */ 32 public class ListenerRegistration<TListener> implements ListenerExecutor { 33 34 private final Executor mExecutor; 35 36 private boolean mActive; 37 38 private volatile @Nullable TListener mListener; 39 ListenerRegistration(Executor executor, TListener listener)40 protected ListenerRegistration(Executor executor, TListener listener) { 41 mExecutor = Objects.requireNonNull(executor); 42 mActive = false; 43 mListener = Objects.requireNonNull(listener); 44 } 45 getExecutor()46 protected final Executor getExecutor() { 47 return mExecutor; 48 } 49 50 /** 51 * May be overridden by subclasses. Invoked when registration occurs. Invoked while holding the 52 * owning multiplexer's internal lock. 53 */ onRegister(Object key)54 protected void onRegister(Object key) {} 55 56 /** 57 * May be overridden by subclasses. Invoked when unregistration occurs. Invoked while holding 58 * the owning multiplexer's internal lock. 59 */ onUnregister()60 protected void onUnregister() {} 61 62 /** 63 * May be overridden by subclasses. Invoked when this registration becomes active. If this 64 * returns a non-null operation, that operation will be invoked for the listener. Invoked 65 * while holding the owning multiplexer's internal lock. 66 */ onActive()67 protected void onActive() {} 68 69 /** 70 * May be overridden by subclasses. Invoked when registration becomes inactive. If this returns 71 * a non-null operation, that operation will be invoked for the listener. Invoked while holding 72 * the owning multiplexer's internal lock. 73 */ onInactive()74 protected void onInactive() {} 75 isActive()76 public final boolean isActive() { 77 return mActive; 78 } 79 setActive(boolean active)80 final boolean setActive(boolean active) { 81 if (active != mActive) { 82 mActive = active; 83 return true; 84 } 85 86 return false; 87 } 88 isRegistered()89 public final boolean isRegistered() { 90 return mListener != null; 91 } 92 unregisterInternal()93 final void unregisterInternal() { 94 mListener = null; 95 onListenerUnregister(); 96 } 97 98 /** 99 * May be overridden by subclasses, however should rarely be needed. Invoked when the listener 100 * associated with this registration is unregistered, which may occur before the registration 101 * itself is unregistered. This immediately prevents the listener from being further invoked 102 * until the registration itself can be finalized and unregistered completely. 103 */ onListenerUnregister()104 protected void onListenerUnregister() {} 105 106 /** 107 * May be overridden by subclasses to handle listener operation failures. The default behavior 108 * is to further propagate any exceptions. Will always be invoked on the executor thread. 109 */ onOperationFailure(ListenerOperation<TListener> operation, Exception exception)110 protected void onOperationFailure(ListenerOperation<TListener> operation, Exception exception) { 111 throw new AssertionError(exception); 112 } 113 114 /** 115 * Executes the given listener operation, invoking 116 * {@link #onOperationFailure(ListenerOperation, Exception)} in case the listener operation 117 * fails. 118 */ executeOperation(@ullable ListenerOperation<TListener> operation)119 protected final void executeOperation(@Nullable ListenerOperation<TListener> operation) { 120 executeSafely(mExecutor, () -> mListener, operation, this::onOperationFailure); 121 } 122 123 @Override toString()124 public String toString() { 125 return "[]"; 126 } 127 128 @Override equals(Object obj)129 public final boolean equals(Object obj) { 130 // intentionally bound to reference equality so removal works as expected 131 return this == obj; 132 } 133 134 @Override hashCode()135 public final int hashCode() { 136 return super.hashCode(); 137 } 138 } 139 140