Interface OutputFile

All Superinterfaces:

AutoCloseable, Closeable

All Known Implementing Classes:

InMemoryOutputFile

public interface OutputFile
extends Closeable

Abstraction for writing Parquet file data.

This is the write-side counterpart to InputFile. Where reading requires random access, the Parquet container is produced front to back and never seeked backward: the footer carries every offset a reader needs and is emitted last. An OutputFile is therefore a purely sequential sink.

An OutputFile starts in an uncreated state. create() must be called before write(ByteBuffer) or position(); the writer framework (ParquetFileWriter) calls it automatically.

A file is valid only after close() returns successfully. A writer abandoned before close() produces no footer and therefore no readable file.

Method Summary

Modifier and Type	Method	Description
void	close()	Finalizes the file and publishes it at the destination.
void	create()	Performs resource acquisition (e.g. opening a file channel).
void	discard()	Discards everything written and releases resources without publishing a file at the destination.
static InMemoryOutputFile	inMemory()	Creates an uncreated OutputFile that keeps the file in memory.
static OutputFile	of(Path path)	Creates an uncreated OutputFile for a local file path.
long	position()	Returns the number of bytes written so far, which is the offset at which the next write(ByteBuffer) will begin.
void	write(ByteBuffer data)	Appends the remaining bytes of data to the file.

Method Details

create

void create()
     throws IOException

Performs resource acquisition (e.g. opening a file channel). Must be called before write(ByteBuffer) or position().

Throws:

IOException - if the resource cannot be acquired

write

void write(ByteBuffer data)
    throws IOException

Appends the remaining bytes of data to the file.

The buffer is consumed (its position advances to its limit).

Parameters:

data - the bytes to append

Throws:

IOException - if the write fails

IllegalStateException - if create() has not been called

position

long position()

Returns the number of bytes written so far, which is the offset at which the next write(ByteBuffer) will begin.

Returns:

the running byte offset

Throws:

IllegalStateException - if create() has not been called

close

void close()
    throws IOException

Finalizes the file and publishes it at the destination.

When publishing fails, close() releases the resources and discards what was written before it throws, leaving the destination as if nothing was written. A failure to discard is attached to the thrown exception as suppressed.

Specified by:

close in interface AutoCloseable

Specified by:

close in interface Closeable

Throws:

IOException - if the file cannot be published

discard

void discard()
      throws IOException

Discards everything written and releases resources without publishing a file at the destination. This is the failure counterpart to close(): close() finalizes (commits) the file, discard() throws it away. The writer calls discard() when it cannot finish a valid file, so a partially written file is never presented as valid. After discard() the destination is left as if nothing was written; calling close() afterwards is a no-op.

Throws:

IOException - if resources cannot be released

of

static OutputFile of(Path path)

Creates an uncreated OutputFile for a local file path.

Parameters:

path - the file to write

Returns:

a new uncreated OutputFile

inMemory

@Experimental
static InMemoryOutputFile inMemory()

Creates an uncreated OutputFile that keeps the file in memory. The finished file is retrieved from InMemoryOutputFile.buffer() after the writer is closed.

The buffer grows with the file, so no size has to be given up front; the length of a Parquet file is only known once it has been written.

This API is Experimental: the shape may change in future releases.

Returns:

a new uncreated in-memory OutputFile