/*
 * Copyright 2021 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.video;

import androidx.annotation.NonNull;
import androidx.annotation.Nullable;
import androidx.core.util.Consumer;
import androidx.core.util.Preconditions;

import java.util.concurrent.Executor;

/**
 * A recording that can be started at a future time.
 */
public final class PendingRecording {

    private final Recorder mRecorder;
    private final OutputOptions mOutputOptions;
    private Consumer<VideoRecordEvent> mEventListener;
    private Executor mCallbackExecutor;

    PendingRecording(@NonNull Recorder recorder, @NonNull OutputOptions options) {
        mRecorder = recorder;
        mOutputOptions = options;
    }

    @NonNull
    Recorder getRecorder() {
        return mRecorder;
    }

    @NonNull
    OutputOptions getOutputOptions() {
        return mOutputOptions;
    }

    @Nullable
    Executor getCallbackExecutor() {
        return mCallbackExecutor;
    }

    @Nullable
    Consumer<VideoRecordEvent> getEventListener() {
        return mEventListener;
    }

    /**
     * Sets the event listener that will receive {@link VideoRecordEvent} for this recording.
     *
     * @param callbackExecutor the executor that the event listener will be run on.
     * @param listener the event listener to handle the video record event.
     * @return this pending recording
     */
    @NonNull
    public PendingRecording withEventListener(@NonNull Executor callbackExecutor,
            @NonNull Consumer<VideoRecordEvent> listener) {
        Preconditions.checkNotNull(callbackExecutor, "CallbackExecutor can't be null.");
        Preconditions.checkNotNull(listener, "Event listener can't be null");
        mCallbackExecutor = callbackExecutor;
        mEventListener = listener;
        return this;
    }

    /**
     * Starts the recording, making it an active recording.
     *
     * <p>Only a single recording can be active at a time, so if another recording is active,
     * this will throw an {@link IllegalStateException}.
     *
     * @throws IllegalStateException if the associated Recorder currently has an unfinished
     * active recording.
     */
    @NonNull
    public ActiveRecording start() {
        return mRecorder.start(this);
    }
}

@@ -889,16 +889,574 @@
 e time.%0A
+ *%0A * %3Cp%3EA pending recording allows for configuration of a recording before it is started. Once a%0A * pending recording is started with %7B@link #start()%7D, any changes to the pending recording will%0A * not affect the actual recording; any modifications to the recording will need to occur through%0A * the controls of the %7B@link ActiveRecording%7D class returned by %7B@link #start()%7D.%0A *%0A * %3Cp%3EA pending recording can be created using one of the %7B@link Recorder%7D methods for starting a%0A * recording such as %7B@link Recorder#prepareRecording(MediaStoreOutputOptions)%7D.%0A
  */%0Apubl
@@ -3158,32 +3158,956 @@
 eption%7D.%0A     *%0A
+     * %3Cp%3EIf there are no errors starting the recording, the returned %7B@link ActiveRecording%7D%0A     * can be used to %7B@link ActiveRecording#pause() pause%7D, %7B@link ActiveRecording#resume() resume%0A     * %7D, or %7B@link ActiveRecording#stop() stop%7D the recording.%0A     *%0A     * %3Cp%3EUpon successfully starting the recording, a %7B@link VideoRecordEvent.Start%7D event will%0A     * be the first event sent to the listener set in%0A     * %7B@link #withEventListener(Executor, Consumer)%7D.%0A     *%0A     * %3Cp%3EIf errors occur while starting the recording, a %7B@link VideoRecordEvent.Finalize%7D event%0A     * will be the first event sent to the listener set in%0A     * %7B@link #withEventListener(Executor, Consumer)%7D, and information about the error can be%0A     * found in that event's %7B@link VideoRecordEvent.Finalize#getError()%7D method. The returned%0A     * %7B@link ActiveRecording%7D will be in a finalized state, and all controls will be no-ops.%0A     *%0A
      * @throws I

Update PendingRecording documentation