/*
 * 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.flink.core.fs;

import org.apache.flink.annotation.Public;

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

/**
 * An output stream to a file that is created via a {@link FileSystem}.
 * This class extends the base {@link java.io.OutputStream} with some additional important methods.
 * 
 * <h2>Data Persistence Guarantees</h2>
 * 
 * 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 Flink's FileSystem abstraction and the {@code FSDataOutputStream}.
 * 
 * <h2>Thread Safety</h2>
 * 
 * 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
 */
@Public
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()} or {@link #sync()}.
	 * 
	 * <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;

	/**
	 * Flushes the data all the way to the persistent non-volatile storage (for example disks).
	 * The method behaves similar to the <i>fsync</i> function, forcing all data to
	 * be persistent on the devices.
	 * 
	 * <p>
	 * 
	 * @throws IOException Thrown if an I/O error occurs
	 */
	public abstract void sync() 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;
}