E
- The type of entity accepted by this writer.@NotThreadSafe public interface DatasetWriter<E> extends Flushable, Syncable, 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 are
not expected to instantiate implementations directly. Instead, use the
containing dataset's View.newWriter()
method to get an appropriate
implementation. You should receive an instance of this interface from a
dataset, invoke write(Object)
and flush()
(or sync()
) as
necessary, and close()
when they are done, or no more data exists.
Implementations can hold system resources until the close()
method
is called, so you must follow the normal try / finally
pattern to ensure these resources are properly freed when the writer is no
longer needed. Do not rely on implementations automatically invoking the
close
method upon object finalization (implementations must not do
so). All 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, and the only method that can be subsequently
called is close
.
Implementations of DatasetWriter
are typically not 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 and should be closed.
entity
- The entity to writeDatasetRecordException
- If a record could not be written, but the writer is still valid.DatasetIOException
- To wrap an internal IOException
@Deprecated void flush()
Flushable.flush()
Force 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 will no longer require flush. Instead,
implementations that can support a durability guarantee, such as Avro,
can be Flushable
and Syncable
.
flush
in interface Flushable
DatasetOperationException
- If the operation did not succeed.DatasetIOException
- To wrap an internal IOException
@Deprecated void sync()
Syncable.sync()
Ensure that data in the underlying stream has been written to disk (optional operation).
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 will no longer require sync. Instead,
implementations that can support a durability guarantee, such as Avro,
can be Flushable
and Syncable
.
sync
in interface Syncable
DatasetOperationException
- If the operation did not succeed.DatasetIOException
- To wrap an internal IOException
void 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)
will be stored to stable storage.
No further operations of this interface (other than additional calls to this method) can be performed; however, implementations can choose to permit other method calls. See implementation documentation for details.
close
in interface AutoCloseable
close
in interface Closeable
DatasetOperationException
- If the operation did not succeed.DatasetIOException
- To wrap an internal IOException
boolean isOpen()
Copyright © 2013–2015. All rights reserved.