Table of Contents
Just a second...

Streams

A stream is a response object that the client passes to an asynchronous call. When the call is ready to respond it calls a method on the stream to respond to the client. The following types of stream exist: stream and contextual stream.

Figure 1. A stream A client makes a call, passing a reference to a stream object. The server responds by calling a method on the stream object. A stream object can have its methods called multiple times during its lifetime. When a stream object's onClose method is called the stream is closed and it can no longer receive responses on any of its other methods.

A stream differs from a callback, because it can receive more than one response. A stream continues to receive responses until it is closed or discarded.

The API provides following types of stream:
Value stream
Receives topic updates and topic events from subscribed topics of a specific type.
Topic stream
Receives topic updates and topic events from subscribed topics.
Fetch stream
Receives responses to fetch requests made to topics.
Message stream
Receives messages sent to the client on a topic path.
All streams in the Unified API have the following methods:
onEvent
Where Event depends on the specific stream and describes the event that occurs when the call is ready to return a response. This method is used to provide the responses from the call.
onClose
This method is used to indicate to the stream that all responses have been received from the call. After this method is called, the stream can not receive any more responses.
onDiscard
This method is used to indicate that the call has not returned a response, but that the callback is no longer required. This can happen when a call times out or a session is closed.

Contextual streams

A contextual stream works in the same way as a stream, except that when it is created an object is associated with it that provides application state information. For example, when a client requests information to populate a UI element it can associate an object that represents the UI element with the stream for the request. When the callback is called and provided with the information requested, it can use the associated context object to complete the appropriate action with that information: in this case, populating the UI element with the information.