Class LiveStream

java.lang.Object
com.surrealdb.LiveStream
All Implemented Interfaces:
AutoCloseable
public class LiveStream extends Object implements AutoCloseable
Blocking iterator over live query notifications returned by Surreal.selectLive(String).

Typical usage: 

try (LiveStream stream = surreal.selectLive("person")) {
    while (true) {
        Optional<LiveNotification> n = stream.next();
        if (!n.isPresent()) break;   // stream closed
        process(n.get());
    }
}

Thread safety: next() may be called from one thread while close() is called from another. The close() call will unblock any thread currently waiting inside next(). The native handle is declared volatile so that the zeroing performed by close() is immediately visible to concurrent next() callers. Concurrent calls to next() from multiple threads are serialized by a mutex in the native layer.

  • Method Details

    • next

      public Optional<LiveNotification> next()
      Blocks until the next notification is available, or the stream ends.

      Returns Optional.empty() when the stream has been closed (either explicitly via close() or because the server ended the live query). If the underlying live query encounters an error, a SurrealException is thrown.

      Returns:
      the next notification, or empty if the stream has ended
      Throws:
      SurrealException - if the live query encounters an error

    • close

      public void close()
      Releases the live query and stops receiving notifications.

      If another thread is blocked inside next(), it will be unblocked and will return Optional.empty(). This method is idempotent: calling it more than once has no effect.

      Specified by:
      close in interface AutoCloseable