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 package com.android.systemui.statusbar.notification.collection
17 
18 import com.android.systemui.dagger.SysUISingleton
19 import com.android.systemui.statusbar.notification.collection.listbuilder.OnAfterRenderEntryListener
20 import com.android.systemui.statusbar.notification.collection.listbuilder.OnAfterRenderGroupListener
21 import com.android.systemui.statusbar.notification.collection.listbuilder.OnAfterRenderListListener
22 import com.android.systemui.statusbar.notification.collection.listbuilder.OnBeforeFinalizeFilterListener
23 import com.android.systemui.statusbar.notification.collection.listbuilder.OnBeforeRenderListListener
24 import com.android.systemui.statusbar.notification.collection.listbuilder.OnBeforeSortListener
25 import com.android.systemui.statusbar.notification.collection.listbuilder.OnBeforeTransformGroupsListener
26 import com.android.systemui.statusbar.notification.collection.listbuilder.pluggable.Invalidator
27 import com.android.systemui.statusbar.notification.collection.listbuilder.pluggable.NotifComparator
28 import com.android.systemui.statusbar.notification.collection.listbuilder.pluggable.NotifFilter
29 import com.android.systemui.statusbar.notification.collection.listbuilder.pluggable.NotifPromoter
30 import com.android.systemui.statusbar.notification.collection.listbuilder.pluggable.NotifSectioner
31 import com.android.systemui.statusbar.notification.collection.listbuilder.pluggable.NotifStabilityManager
32 import com.android.systemui.statusbar.notification.collection.notifcollection.CommonNotifCollection
33 import com.android.systemui.statusbar.notification.collection.notifcollection.InternalNotifUpdater
34 import com.android.systemui.statusbar.notification.collection.notifcollection.NotifCollectionListener
35 import com.android.systemui.statusbar.notification.collection.notifcollection.NotifDismissInterceptor
36 import com.android.systemui.statusbar.notification.collection.notifcollection.NotifLifetimeExtender
37 import com.android.systemui.statusbar.notification.collection.render.RenderStageManager
38 import javax.inject.Inject
39 
40 /**
41  * The system that constructs the "shade list", the filtered, grouped, and sorted list of
42  * notifications that are currently being displayed to the user in the notification shade.
43  *
44  * The pipeline proceeds through a series of stages in order to produce the final list (see below).
45  * Each stage exposes hooks and listeners to allow other code to participate.
46  *
47  * This list differs from the canonical one we receive from system server in a few ways:
48  * - Filtered: Some notifications are filtered out. For example, we filter out notifications whose
49  *   views haven't been inflated yet. We also filter out some notifications if we're on the lock
50  *   screen and notifications for other users. To participate, see
51  *   [.addPreGroupFilter] and similar methods.
52  * - Grouped: Notifications that are part of the same group are clustered together into a single
53  *   GroupEntry. These groups are then transformed in order to remove children or completely split
54  *   them apart. To participate, see [.addPromoter].
55  * - Sorted: All top-level notifications are sorted. To participate, see
56  *   [.setSections] and [.setComparators]
57  *
58  * The exact order of all hooks is as follows:
59  *  0. Collection listeners are fired ([.addCollectionListener]).
60  *  1. Pre-group filters are fired on each notification ([.addPreGroupFilter]).
61  *  2. Initial grouping is performed (NotificationEntries will have their parents set
62  *     appropriately).
63  *  3. OnBeforeTransformGroupListeners are fired ([.addOnBeforeTransformGroupsListener])
64  *  4. NotifPromoters are called on each notification with a parent ([.addPromoter])
65  *  5. OnBeforeSortListeners are fired ([.addOnBeforeSortListener])
66  *  6. Top-level entries are assigned sections by NotifSections ([.setSections])
67  *  7. Top-level entries within the same section are sorted by NotifComparators ([.setComparators])
68  *  8. OnBeforeFinalizeFilterListeners are fired ([.addOnBeforeFinalizeFilterListener])
69  *  9. Finalize filters are fired on each notification ([.addFinalizeFilter])
70  *  10. OnBeforeRenderListListeners are fired ([.addOnBeforeRenderListListener])
71  *  11. The list is handed off to the view layer to be rendered
72  *  12. OnAfterRenderListListeners are fired ([.addOnAfterRenderListListener])
73  *  13. OnAfterRenderGroupListeners are fired ([.addOnAfterRenderGroupListener])
74  *  13. OnAfterRenderEntryListeners are fired ([.addOnAfterRenderEntryListener])
75  */
76 @SysUISingleton
77 class NotifPipeline @Inject constructor(
78     private val mNotifCollection: NotifCollection,
79     private val mShadeListBuilder: ShadeListBuilder,
80     private val mRenderStageManager: RenderStageManager
81 ) : CommonNotifCollection {
82     /**
83      * Returns the list of all known notifications, i.e. the notifications that are currently posted
84      * to the phone. In general, this tracks closely to the list maintained by NotificationManager,
85      * but it can diverge slightly due to lifetime extenders.
86      *
87      * The returned collection is read-only, unsorted, unfiltered, and ungrouped.
88      */
getAllNotifsnull89     override fun getAllNotifs(): Collection<NotificationEntry> {
90         return mNotifCollection.allNotifs
91     }
92 
addCollectionListenernull93     override fun addCollectionListener(listener: NotifCollectionListener) {
94         mNotifCollection.addCollectionListener(listener)
95     }
96 
removeCollectionListenernull97     override fun removeCollectionListener(listener: NotifCollectionListener) {
98         mNotifCollection.removeCollectionListener(listener)
99     }
100 
101     /**
102      * Returns the NotificationEntry associated with [key].
103      */
getEntrynull104     override fun getEntry(key: String): NotificationEntry? {
105         return mNotifCollection.getEntry(key)
106     }
107 
108     /**
109      * Registers a lifetime extender. Lifetime extenders can cause notifications that have been
110      * dismissed or retracted by system server to be temporarily retained in the collection.
111      */
addNotificationLifetimeExtendernull112     fun addNotificationLifetimeExtender(extender: NotifLifetimeExtender) {
113         mNotifCollection.addNotificationLifetimeExtender(extender)
114     }
115 
116     /**
117      * Registers a dismiss interceptor. Dismiss interceptors can cause notifications that have been
118      * dismissed by the user to be retained (won't send a dismissal to system server).
119      */
addNotificationDismissInterceptornull120     fun addNotificationDismissInterceptor(interceptor: NotifDismissInterceptor) {
121         mNotifCollection.addNotificationDismissInterceptor(interceptor)
122     }
123 
124     /**
125      * Registers a filter with the pipeline before grouping, promoting and sorting occurs. Filters
126      * are called on each notification in the order that they were registered. If any filter
127      * returns true, the notification is removed from the pipeline (and no other filters are
128      * called on that notif).
129      */
addPreGroupFilternull130     fun addPreGroupFilter(filter: NotifFilter) {
131         mShadeListBuilder.addPreGroupFilter(filter)
132     }
133 
134     /**
135      * Called after notifications have been filtered and after the initial grouping has been
136      * performed but before NotifPromoters have had a chance to promote children out of groups.
137      */
addOnBeforeTransformGroupsListenernull138     fun addOnBeforeTransformGroupsListener(listener: OnBeforeTransformGroupsListener) {
139         mShadeListBuilder.addOnBeforeTransformGroupsListener(listener)
140     }
141 
142     /**
143      * Registers a promoter with the pipeline. Promoters are able to promote child notifications to
144      * top-level, i.e. move a notification that would be a child of a group and make it appear
145      * ungrouped. Promoters are called on each child notification in the order that they are
146      * registered. If any promoter returns true, the notification is removed from the group (and no
147      * other promoters are called on it).
148      */
addPromoternull149     fun addPromoter(promoter: NotifPromoter) {
150         mShadeListBuilder.addPromoter(promoter)
151     }
152 
153     /**
154      * Called after notifs have been filtered and groups have been determined but before sections
155      * have been determined or the notifs have been sorted.
156      */
addOnBeforeSortListenernull157     fun addOnBeforeSortListener(listener: OnBeforeSortListener) {
158         mShadeListBuilder.addOnBeforeSortListener(listener)
159     }
160 
161     /**
162      * Sections that are used to sort top-level entries.  If two entries have the same section,
163      * NotifComparators are consulted. Sections from this list are called in order for each
164      * notification passed through the pipeline. The first NotifSection to return true for
165      * [NotifSectioner.isInSection] sets the entry as part of its Section.
166      */
setSectionsnull167     fun setSections(sections: List<NotifSectioner>) {
168         mShadeListBuilder.setSectioners(sections)
169     }
170 
171     /**
172      * StabilityManager that is used to determine whether to suppress group and section changes.
173      * This should only be set once.
174      */
setVisualStabilityManagernull175     fun setVisualStabilityManager(notifStabilityManager: NotifStabilityManager) {
176         mShadeListBuilder.setNotifStabilityManager(notifStabilityManager)
177     }
178 
179     /**
180      * Comparators that are used to sort top-level entries that share the same section. The
181      * comparators are executed in order until one of them returns a non-zero result. If all return
182      * zero, the pipeline falls back to sorting by rank (and, failing that, Notification.when).
183      */
setComparatorsnull184     fun setComparators(comparators: List<NotifComparator>) {
185         mShadeListBuilder.setComparators(comparators)
186     }
187 
188     /**
189      * Called after notifs have been filtered once, grouped, and sorted but before the final
190      * filtering.
191      */
addOnBeforeFinalizeFilterListenernull192     fun addOnBeforeFinalizeFilterListener(listener: OnBeforeFinalizeFilterListener) {
193         mShadeListBuilder.addOnBeforeFinalizeFilterListener(listener)
194     }
195 
196     /**
197      * Registers a filter with the pipeline to filter right before rendering the list (after
198      * pre-group filtering, grouping, promoting and sorting occurs). Filters are
199      * called on each notification in the order that they were registered. If any filter returns
200      * true, the notification is removed from the pipeline (and no other filters are called on that
201      * notif).
202      */
addFinalizeFilternull203     fun addFinalizeFilter(filter: NotifFilter) {
204         mShadeListBuilder.addFinalizeFilter(filter)
205     }
206 
207     /**
208      * Called at the end of the pipeline after the notif list has been finalized but before it has
209      * been handed off to the view layer.
210      */
addOnBeforeRenderListListenernull211     fun addOnBeforeRenderListListener(listener: OnBeforeRenderListListener) {
212         mShadeListBuilder.addOnBeforeRenderListListener(listener)
213     }
214 
215     /** Registers an invalidator that can be used to invalidate the entire notif list. */
addPreRenderInvalidatornull216     fun addPreRenderInvalidator(invalidator: Invalidator) {
217         mShadeListBuilder.addPreRenderInvalidator(invalidator)
218     }
219 
220     /**
221      * Called at the end of the pipeline after the notif list has been handed off to the view layer.
222      */
addOnAfterRenderListListenernull223     fun addOnAfterRenderListListener(listener: OnAfterRenderListListener) {
224         mRenderStageManager.addOnAfterRenderListListener(listener)
225     }
226 
227     /**
228      * Called at the end of the pipeline after a group has been handed off to the view layer.
229      */
addOnAfterRenderGroupListenernull230     fun addOnAfterRenderGroupListener(listener: OnAfterRenderGroupListener) {
231         mRenderStageManager.addOnAfterRenderGroupListener(listener)
232     }
233 
234     /**
235      * Called at the end of the pipeline after an entry has been handed off to the view layer.
236      * This will be called for every top level entry, every group summary, and every group child.
237      */
addOnAfterRenderEntryListenernull238     fun addOnAfterRenderEntryListener(listener: OnAfterRenderEntryListener) {
239         mRenderStageManager.addOnAfterRenderEntryListener(listener)
240     }
241 
242     /**
243      * Get an object which can be used to update a notification (internally to the pipeline)
244      * in response to a user action.
245      *
246      * @param name the name of the component that will update notifiations
247      * @return an updater
248      */
getInternalNotifUpdaternull249     fun getInternalNotifUpdater(name: String?): InternalNotifUpdater {
250         return mNotifCollection.getInternalNotifUpdater(name)
251     }
252 }
253