1 /*
2  * Copyright 2019 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 androidx.camera.core.impl;
18 
19 import com.google.common.util.concurrent.ListenableFuture;
20 
21 import org.jspecify.annotations.NonNull;
22 import org.jspecify.annotations.Nullable;
23 
24 import java.util.concurrent.Executor;
25 
26 /**
27  * An observable stream which contains data or errors.
28  *
29  * @param <T> The type of the data in the stream.
30  */
31 public interface Observable<T> {
32 
33     /**
34      * Fetch the latest piece of data asynchronously.
35      *
36      * <p>The returned future may also complete with an exception if the observable currently
37      * contains an error. If
38      * the observable has not yet been initialized with a value, the future may contain an
39      * {@link IllegalStateException}.
40      *
41      * @return A future which will contain the latest value or an error.
42      */
fetchData()43     @NonNull ListenableFuture<T> fetchData();
44 
45     /**
46      * Adds an observer which will receive the stream of data.
47      *
48      * <p>This is an asynchronous operation. Once the observer has been added, it will
49      * immediately be called with the latest value contained in the observable if it contains a
50      * value, or will be called once a value has been set on the observable.
51      *
52      * <p>All added observers should be removed with {@link #removeObserver(Observer)} when no
53      * longer needed.
54      *
55      * <p>If the same observer is added twice, it will only be called on the last executor it was
56      * registered with.
57      * @param executor The executor which will be used to notify the observer of new data.
58      * @param observer The observer which will receive new data.
59      */
addObserver(@onNull Executor executor, @NonNull Observer<? super T> observer)60     void addObserver(@NonNull Executor executor, @NonNull Observer<? super T> observer);
61 
62     /**
63      * Removes a previously added observer.
64      *
65      * <p>Once removed, the observer will no longer receive data.
66      *
67      * <p>If the observer was not previously added, this operation will be a no-op.
68      *
69      * @param observer The observer to remove.
70      */
removeObserver(@onNull Observer<? super T> observer)71     void removeObserver(@NonNull Observer<? super T> observer);
72 
73     /**
74      * A callback that can receive new values and errors from an {@link Observable}.
75      *
76      * @param <T> The type of the data being reported.
77      */
78     interface Observer<T> {
79         /**
80          * Called when the stream emits a new piece of data.
81          *
82          * @param value The new data value
83          */
onNewData(@ullable T value)84         void onNewData(@Nullable T value);
85 
86         /**
87          * Called when the stream emits an error.
88          *
89          * @param t The error.
90          */
onError(@onNull Throwable t)91         void onError(@NonNull Throwable t);
92     }
93 }
94