In Flutter SDK, we have a concept of Live Object and Live Collection. Live Object is represented by StreamSubscription<Object> instance and LiveCollection is represented by an instance of LiveCollection. LiveCollection is a generic class that encapsulates any other object and notifies the observer whenever any property of encapsulated object changes. Live Object helps to observe changes in a single object whereas Live Collection helps to observe changes in a list of objects. For example: StreamSubscription<AmityPost> or LiveCollection<AmityMessage>.
SDK handles lots of data received from various sources. Data can be present in local cache. It might also be queried from the server or received from some real-time events. What this means is that the same data is constantly updating. The data that you are accessing at the moment can get updated by other sources and becomes out of sync. Live Object and Live Collection help in syncing the data so you will always get the most recent one. Whenever the data updates, you will be notified through helper methods in Live Object and Live Collection classes.
New data gets automatically collected everytime when there is an update and user need not refresh to get the recent data.
StreamSubscription<Object> is a native flutter class that keeps track of a single object. It is a live object. In Flutter AmitySDK, any object which provides Stream is a Live Object.
Examples:
This function help listen to Live Object. Whenever any property for the observed object changes, the listen callback will be triggered.
LiveCollection is a generic class that keeps track of a collection of objects. It is a Live Collection. In Flutter SDK, any object which is encapsulated by LiveCollection class is a live collection.
Examples:
MessageLiveCollection
ChannelLiveCollection
LiveCollection exposes these methods:
asStream
onError
These methods help observe a Live Collection. Whenever any property for any object within the collection changes, the observer is triggered, as well as observing any errors from the collection.
asStream method can get triggered multiple times throughout the lifetime of the application as long as its associated Stream<List<Object>> is retained in memory.
asStream method will be called from the main thread so you can perform any UI update-related task within the listen block itself.
If the requested data collection is stored locally on the device, the block will be called immediately with the local version of the data.
In parallel, a request is made to the server to fetch the latest version of the data. Once the data is returned, the listen block will be triggered again.
Any future changes to the data from any sources can trigger in the listen block.
AmityCollection in SDK returns a maximum of pageSize items per page. It has loadNext() method to fetch more data. It also exposes hasNext property to check if next page or previous page is present.
Once next page is available, the same listen block gets triggered and you can access the collection as shown above. If you want to shrink the collection to the original first page, you can do so by calling reset() method on the same collection.
One typical usage of LiveCollection is in ListView. Below is an example of fetching a collection and updating its state it in a Widget.