Module org.apache.arrow.flight.core

Package org.apache.arrow.flight

Class FlightStream

java.lang.Object

org.apache.arrow.flight.FlightStream

All Implemented Interfaces:

AutoCloseable

public class FlightStream
extends Object
implements AutoCloseable

An adaptor between protobuf streams and flight data streams.

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static interface	FlightStream.Cancellable	Provides a callback to cancel a process that is in progress.
static interface	FlightStream.Requestor	Provides a interface to request more items from a stream producer.

Constructor Summary

Constructors

Constructor	Description
FlightStream(BufferAllocator allocator, int pendingTarget, FlightStream.Cancellable cancellable, FlightStream.Requestor requestor)	Constructs a new instance.

Method Summary

Modifier and Type	Method	Description
void	cancel(String message, Throwable exception)	Cancels sending the stream to a client.
void	close()	Closes the stream (freeing any existing resources).
FlightDescriptor	getDescriptor()	Get the descriptor for this stream.
DictionaryProvider	getDictionaryProvider()	Get the provider for dictionaries in this stream.
ArrowBuf	getLatestMetadata()	Get the most recent metadata sent from the server.
VectorSchemaRoot	getRoot()	Get the current vector data from the stream.
Schema	getSchema()	Get the schema for this stream.
boolean	hasRoot()	Check if there is a root (i.e.
boolean	next()	Blocking request to load next item into list.
DictionaryProvider	takeDictionaryOwnership()	Get an owned reference to the dictionaries in this stream.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Details

FlightStream

public FlightStream(BufferAllocator allocator,
 int pendingTarget,
 FlightStream.Cancellable cancellable,
 FlightStream.Requestor requestor)

Constructs a new instance.

Parameters:

allocator - The allocator to use for creating/reallocating buffers for Vectors.

pendingTarget - Target number of messages to receive.

cancellable - Used to cancel mid-stream requests.

requestor - A callback to determine how many pending items there are.

Method Details

getSchema

public Schema getSchema()

Get the schema for this stream. Blocks until the schema is available.

getDictionaryProvider

public DictionaryProvider getDictionaryProvider()

Get the provider for dictionaries in this stream.

Does NOT retain a reference to the underlying dictionaries. Dictionaries may be updated as the stream is read. This method is intended for stream processing, where the application code will not retain references to values after the stream is closed.

Throws:

IllegalStateException - if takeDictionaryOwnership() was called

See Also:

• takeDictionaryOwnership()

takeDictionaryOwnership

public DictionaryProvider takeDictionaryOwnership()

Get an owned reference to the dictionaries in this stream. Should be called after finishing reading the stream, but before closing.

If called, the client is responsible for closing the dictionaries in this provider. Can only be called once.

Returns:

The dictionary provider for the stream.

Throws:

IllegalStateException - if called more than once.

getDescriptor

public FlightDescriptor getDescriptor()

Get the descriptor for this stream. Only applicable on the server side of a DoPut operation. Will block until the client sends the descriptor.

close

public void close()
           throws Exception

Closes the stream (freeing any existing resources).

If the stream isn't complete and is cancellable, this method will cancel and drain the stream first.

Specified by:

close in interface AutoCloseable

Throws:

Exception

next

public boolean next()

Blocking request to load next item into list.

Returns:

Whether or not more data was found.

getRoot

public VectorSchemaRoot getRoot()

Get the current vector data from the stream.

The data in the root may change at any time. Clients should NOT modify the root, but instead unload the data into their own root.

Throws:

FlightRuntimeException - if there was an error reading the schema from the stream.

hasRoot

public boolean hasRoot()

Check if there is a root (i.e. whether the other end has started sending data).

Updated by calls to next().

Returns:

true if and only if the other end has started sending data.

getLatestMetadata

public ArrowBuf getLatestMetadata()

Get the most recent metadata sent from the server. This may be cleared by calls to next() if the server sends a message without metadata. This does NOT take ownership of the buffer - call retain() to create a reference if you need the buffer after a call to next().

Returns:

the application metadata. May be null.

cancel

public void cancel(String message,
 Throwable exception)

Cancels sending the stream to a client.

Callers should drain the stream (with next()) to ensure all messages sent before cancellation are received and to wait for the underlying transport to acknowledge cancellation.