Observable.java
/*
* Copyright 2019 The Android Open Source Project
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package androidx.camera.core.impl;
import androidx.annotation.NonNull;
import androidx.annotation.Nullable;
import androidx.annotation.RequiresApi;
import com.google.common.util.concurrent.ListenableFuture;
import java.util.concurrent.Executor;
/**
* An observable stream which contains data or errors.
*
* @param <T> The type of the data in the stream.
*/
@RequiresApi(21) // TODO(b/200306659): Remove and replace with annotation on package-info.java
public interface Observable<T> {
/**
* Fetch the latest piece of data asynchronously.
*
* <p>The returned future may also complete with an exception if the observable currently
* contains an error. If
* the observable has not yet been initialized with a value, the future may contain an
* {@link IllegalStateException}.
*
* @return A future which will contain the latest value or an error.
*/
@NonNull
ListenableFuture<T> fetchData();
/**
* Adds an observer which will receive the stream of data.
*
* <p>This is an asynchronous operation. Once the observer has been added, it will
* immediately be called with the latest value contained in the observable if it contains a
* value, or will be called once a value has been set on the observable.
*
* <p>All added observers should be removed with {@link #removeObserver(Observer)} when no
* longer needed.
*
* <p>If the same observer is added twice, it will only be called on the last executor it was
* registered with.
* @param executor The executor which will be used to notify the observer of new data.
* @param observer The observer which will receive new data.
*/
void addObserver(@NonNull Executor executor, @NonNull Observer<? super T> observer);
/**
* Removes a previously added observer.
*
* <p>Once removed, the observer will no longer receive data.
*
* <p>If the observer was not previously added, this operation will be a no-op.
*
* @param observer The observer to remove.
*/
void removeObserver(@NonNull Observer<? super T> observer);
/**
* A callback that can receive new values and errors from an {@link Observable}.
*
* @param <T> The type of the data being reported.
*/
interface Observer<T> {
/**
* Called when the stream emits a new piece of data.
*
* @param value The new data value
*/
void onNewData(@Nullable T value);
/**
* Called when the stream emits an error.
*
* @param t The error.
*/
void onError(@NonNull Throwable t);
}
}