Package org.apache.arrow.flight

Interface OutboundStreamListener

All Known Subinterfaces:
FlightClient.ClientStreamListener, FlightProducer.ServerStreamListener
public interface OutboundStreamListener
An interface for writing data to a peer, client or server.

  • Method Details

    • isReady

      boolean isReady()
      A hint indicating whether the client is ready to receive data without excessive buffering.

      Writers should poll this flag before sending data to respect backpressure from the client and avoid sending data faster than the client can handle. Ignoring this flag may mean that the server will start consuming excessive amounts of memory, as it may buffer messages in memory.

    • setOnReadyHandler

      default void setOnReadyHandler(Runnable handler)
      Set a callback for when the listener is ready for new calls to putNext(), i.e. isReady() has become true.

      Note that this callback may only be called some time after isReady() becomes true, and may never be called if all executor threads on the server are busy, or the RPC method body is implemented in a blocking fashion. Note that isReady() must still be checked after the callback is run as it may have been run spuriously.

    • start

      default void start(VectorSchemaRoot root)
      Start sending data, using the schema of the given VectorSchemaRoot.

      This method must be called before all others, except putMetadata(ArrowBuf).

    • start

      default void start(VectorSchemaRoot root, DictionaryProvider dictionaries)
      Start sending data, using the schema of the given VectorSchemaRoot.

      This method must be called before all others, except putMetadata(ArrowBuf).

    • start

      void start(VectorSchemaRoot root, DictionaryProvider dictionaries, IpcOption option)
      Start sending data, using the schema of the given VectorSchemaRoot.

      This method must be called before all others, except putMetadata(ArrowBuf).

    • putNext

      void putNext()
      Send the current contents of the associated VectorSchemaRoot.

      This will not necessarily block until the message is actually sent; it may buffer messages in memory. Use isReady() to check if there is backpressure and avoid excessive buffering.

    • putNext

      void putNext(ArrowBuf metadata)
      Send the current contents of the associated VectorSchemaRoot alongside application-defined metadata.
      Parameters:
      metadata - The metadata to send. Ownership of the buffer is transferred to the Flight implementation.

    • putMetadata

      void putMetadata(ArrowBuf metadata)
      Send a pure metadata message without any associated data.

      This may be called without starting the stream.

    • error

      void error(Throwable ex)
      Indicate an error to the client. Terminates the stream; do not call completed() afterwards.

    • completed

      void completed()
      Indicate that transmission is finished.

    • setUseZeroCopy

      default void setUseZeroCopy(boolean enabled)
      Toggle whether to use the zero-copy write optimization.

      By default or when disabled, Arrow may copy data into a buffer for the underlying implementation to send. When enabled, Arrow will instead try to directly enqueue the Arrow buffer for sending. Not all implementations support this optimization, so even if enabled, you may not see a difference.

      In this mode, buffers must not be reused after they are written with putNext(). For example, you would have to call VectorSchemaRoot.allocateNew() after every call to putNext(). Hence, this is not enabled by default.

      The default value can be toggled globally by setting the JVM property arrow.flight.enable_zero_copy_write or the environment variable ARROW_FLIGHT_ENABLE_ZERO_COPY_WRITE.