io.axoniq.axonserver.connector

Interface ResultStream<T>

Type Parameters:

T - the result type returned by this ResultStream

All Superinterfaces:

AutoCloseable

All Known Subinterfaces:

EventStream

All Known Implementing Classes:

AbstractBufferedStream, BufferedEventStream, SubscriptionQueryUpdateBuffer

public interface ResultStream<T>
extends AutoCloseable

Interface describing a stream of results to a request. This stream allows for blocking retrieval of elements, as well as a non-blocking approach using notifications when messages are available.

While the ResultStream itself is safe for multi-threaded use, some methods may only provide best-effort estimates. In such case, for example, there is no guarantee that a peek() followed by a nextIfAvailable() will yield the same message.

Method Summary

Modifier and Type	Method and Description
void	close() Requests the current stream to be closed.
Optional<Throwable>	getError() Returns an optional containing the exception reported by the Server, if any.
boolean	isClosed() Indicates whether the current stream is closed for further reading.
T	next() Consumes the next available element in the stream, waiting for an element to become available, or for the buffer to be closed.
T	nextIfAvailable() Consumes the next available element in the stream, if available.
T	nextIfAvailable(long timeout, TimeUnit unit) Consumes the next available element in the stream, waiting for at most timeout (in given unit) for an element to become available.
void	onAvailable(Runnable callback) Sets the given callback to execute when data is available for reading, or the stream has been closed.
T	peek() Returns the next available element in the stream, if available, without consuming it from the stream.

Method Detail

peek

T peek()

Returns the next available element in the stream, if available, without consuming it from the stream. Will return null when no element is available, or when the stream has been closed.

Returns:

the next available element in the stream, or null if none is available, or if the stream is closed

nextIfAvailable

T nextIfAvailable()

Consumes the next available element in the stream, if available. Will return null if no element is available immediately.

Returns:

the next available element in the stream, or null if none is available, or if the stream is closed

nextIfAvailable

T nextIfAvailable(long timeout,
                  TimeUnit unit)
           throws InterruptedException

Consumes the next available element in the stream, waiting for at most timeout (in given unit) for an element to become available. If no element is available with the given timeout, or if the stream has been closed, it returns null.

Parameters:

timeout - the amount of time to wait for an element to become available

unit - the unit of time in which the timeout is expressed

Returns:

the next available element in the stream, or null if none is available

Throws:

InterruptedException - when the Thread is interrupted while waiting for an element to become available

See Also:

isClosed()

next

T next()
throws InterruptedException

Consumes the next available element in the stream, waiting for an element to become available, or for the buffer to be closed.

Returns:

the next available element in the stream, or null if none available

Throws:

InterruptedException - when the Thread is interrupted while waiting for an element to become available

StreamClosedException - when the stream is closed

See Also:

isClosed()

onAvailable

void onAvailable(Runnable callback)

Sets the given callback to execute when data is available for reading, or the stream has been closed. Note that any registration will replace the previous one.

The callback is invoked in the publisher's thread. Invocations should be as short as possible, preferably delegating to a reader thead, instead of accessing the entries directly.

Parameters:

callback - a {Runnable} to Runnable.run() when the next entry becomes available or null to disable callbacks

close

void close()

Requests the current stream to be closed. It is up to the publishing end of the stream to honor the request.

Any elements received before closing are still available for reading.

Specified by:

close in interface AutoCloseable

isClosed

boolean isClosed()

Indicates whether the current stream is closed for further reading. Note that this method will also return false in case the stream is closed by the element provider, but there are still elements awaiting consumption.

Check getError() to check whether the stream was closed because of an error

Returns:

true if the stream is closed for further reading, otherwise false

See Also:

getError()

getError

Optional<Throwable> getError()

Returns an optional containing the exception reported by the Server, if any.

Note that this method may return a non-empty response, even when isClosed() returns false, or if there are messages available for processing.

Returns:

an optional containing the exception reported by the Server, if any.