E - The type of entity accepted by this writer.public interface DatasetWriter<E>
extends java.io.Closeable
A stream-oriented dataset writer.
Implementations of this interface write data to a Dataset.
Writers are use-once objects that serialize entities of type E and
write them to the underlying storage system.
Normally, you do not instantiate implementations directly.
Instead, use the containing dataset's Dataset#newWriter() method
to get an appropriate implementation. newWriter returns an instance
of this interface. Invoke write(Object) and flush() (or
sync()) as required, and then close() when you are done
or no more data exists.
Implementations can hold system resources until the close() method
is called, so you must follow the standard try/finally
pattern to ensure these resources are properly freed when the writer is no
longer useful. Do not rely on implementations automatically invoking the
close method upon object finalization. Your implementations must
silently ignore multiple invocations of close() as well as a close of
an unopened writer.
If any method throws an exception other than DatasetRecordException,
the writer is no longer valid. The only method that you can call after any
other exception is close().
Implementations of DatasetWriter are not required to be thread-safe;
that is, the behavior when accessing a single instance from multiple threads
is undefined.
| Modifier and Type | Method and Description |
|---|---|
void |
close()
Close the writer and release any system resources.
|
void |
flush()
Deprecated.
will be removed after 0.18.0; use
Flushable#flush |
boolean |
isOpen() |
void |
sync()
Deprecated.
will be removed after 0.18.0; use
Syncable#sync |
void |
write(E entity)
Write an entity to the underlying dataset.
|
void write(E entity)
Write an entity to the underlying dataset.
If any exception other than DatasetRecordException is thrown, this
writer is no longer valid. The only method you can call after any other
exception is close.
entity - the entity to writeDatasetRecordException - if a record cannot be written, but the writer is still validDatasetIOException - to wrap an internal IOExceptionDatasetWriterException@Deprecated void flush()
Flushable#flushForce or commit any outstanding buffered data to the underlying stream, if supported.
Note: Some implementations do not implement this method.
In particular, Parquet format does not
implement flush(), and calling it has no effect.
After 0.18.0, DatasetWriter no longer requires flush. Instead,
implementations that can support a durability guarantee, such as Avro,
can be Flushable and Syncable.
DatasetWriterException@Deprecated void sync()
Syncable#syncEnsure that data in the underlying stream has been written to disk (optional).
Note: Some implementations do not implement this method.
In particular, Parquet format does not
implement sync() and calling it has no effect.
After 0.18.0, DatasetWriter no longer requires sync. Instead,
implementations that can support a durability guarantee, such as Avro,
can be Flushable and Syncable.
DatasetWriterExceptionvoid close()
Close the writer and release any system resources. If this method returns
without throwing an exception, then any entity that was successfully
written with write(Object) is stored to stable storage.
No further operations of this interface (other than additional calls to
close) can be performed.
close in interface java.lang.AutoCloseableclose in interface java.io.CloseableDatasetWriterExceptionboolean isOpen()