/*
 * Licensed to the Apache Software Foundation (ASF) under one or more
 * contributor license agreements.  See the NOTICE file distributed with
 * this work for additional information regarding copyright ownership.
 * The ASF licenses this file to You 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 org.apache.fluss.fs;

import org.apache.fluss.annotation.PublicStable;

import java.io.IOException;
import java.io.OutputStream;

/* This file is based on source code of Apache Flink Project (https://flink.apache.org/), licensed by the Apache
 * Software Foundation (ASF) under the Apache License, Version 2.0. See the NOTICE file distributed with this work for
 * additional information regarding copyright ownership. */

/**
 * An output stream to a file that is created via a {@link FileSystem}. This class extends the base
 * {@link OutputStream} with some additional important methods.
 *
 * <h2>Data Persistence Guarantees</h2>
 *
 * <p>These streams are used to persistently store data, both for results of streaming applications
 * and for fault tolerance and recovery. It is therefore crucial that the persistence semantics of
 * these streams are well defined.
 *
 * <p>Please refer to the class-level docs of {@link FileSystem} for the definition of data
 * persistence via Fluss's FileSystem abstraction and the {@code FSDataOutputStream}.
 *
 * <h2>Thread Safety</h2>
 *
 * <p>Implementations of the {@code FSDataOutputStream} are generally not assumed to be thread safe.
 * Instances of {@code FSDataOutputStream} should not be passed between threads, because there are
 * no guarantees about the order of visibility of operations across threads.
 *
 * @see FileSystem
 * @see FSDataInputStream
 * @since 0.1
 */
@PublicStable
public abstract class FSDataOutputStream extends OutputStream {

    /**
     * Gets the position of the stream (non-negative), defined as the number of bytes from the
     * beginning of the file to the current writing position. The position corresponds to the
     * zero-based index of the next byte that will be written.
     *
     * <p>This method must report accurately report the current position of the stream. Various
     * components of the high-availability and recovery logic rely on the accurate
     *
     * @return The current position in the stream, defined as the number of bytes from the beginning
     *     of the file to the current writing position.
     * @throws IOException Thrown if an I/O error occurs while obtaining the position from the
     *     stream implementation.
     */
    public abstract long getPos() throws IOException;

    /**
     * Flushes the stream, writing any data currently buffered in stream implementation to the
     * proper output stream. After this method has been called, the stream implementation must not
     * hold onto any buffered data any more.
     *
     * <p>A completed flush does not mean that the data is necessarily persistent. Data persistence
     * can is only assumed after calls to {@link #close()}.
     *
     * <p>Implementation note: This overrides the method defined in {@link OutputStream} as abstract
     * to force implementations of the {@code FSDataOutputStream} to implement this method directly.
     *
     * @throws IOException Thrown if an I/O error occurs while flushing the stream.
     */
    public abstract void flush() throws IOException;

    /**
     * Closes the output stream. After this method returns, the implementation must guarantee that
     * all data written to the stream is persistent/visible, as defined in the {@link FileSystem
     * class-level docs}.
     *
     * <p>The above implies that the method must block until persistence can be guaranteed. For
     * example for distributed replicated file systems, the method must block until the replication
     * quorum has been reached. If the calling thread is interrupted in the process, it must fail
     * with an {@code IOException} to indicate that persistence cannot be guaranteed.
     *
     * <p>If this method throws an exception, the data in the stream cannot be assumed to be
     * persistent.
     *
     * <p>Implementation note: This overrides the method defined in {@link OutputStream} as abstract
     * to force implementations of the {@code FSDataOutputStream} to implement this method directly.
     *
     * @throws IOException Thrown, if an error occurred while closing the stream or guaranteeing
     *     that the data is persistent.
     */
    public abstract void close() throws IOException;
}
