In Flutter SDK, we have a concept of Live Object and Live Collection. Live Object is represented by StreamSubscription<Object> instance and Live Collection 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 the 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.
Examples: StreamSubscription<AmityPost> for single objects or LiveCollection<AmityMessage> for collections.

​
How it Works

SDK handles lots of data received from various sources. Data can be present in the 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 become 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 the Live Object and Live Collection classes. New data gets automatically collected every time when there is an update and the user need not refresh to get the recent data.

​
Data Sources

Local Cache

Data present in local storage

Server Queries

Data queried from the server

Real-time Events

Data received from real-time events

​
LiveObject

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. This function helps listen to Live Object. Whenever any property for the observed object changes, the listen callback will be triggered.

​
Example Usage

void listenPost(String postId) {
  AmitySocialClient.newPostRepository()
      .getPostStream(postId)
      .stream
      .listen((AmityPost post) {
    //handle results
  }).onError((error, stackTrace) {
    //handle error
  });
}

​
Live Collection

LiveCollection is a generic class that keeps track of a collection of objects. It is a Live Collection. In Flutter SDK, any object that is encapsulated by LiveCollection class is a live collection.

​
Stream Observer

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 the listen block.

​
Pagination

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 the next page or previous page is present. 
void loadNextPage() async {
  if (liveCollection.hasNextPage()) {
    liveCollection.loadNext();
  }
}
Once the 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.

​
ListView Integration

One typical usage of LiveCollection is in ListView. Below is an example of fetching a collection and updating its state in a Widget. 
void initState(String channelId) {
  messageLiveCollection = AmityChatClient.newMessageRepository()
      .getMessages(channelId)
      .stackFromEnd(true)
      .getLiveCollection(pageSize: 20);

  messageLiveCollection.getStreamController().stream.listen((event) {
    // update latest results here
    // setState(() {
    //   amityMessages = event;
    // });
  });

  //load first page when initiating widget
  WidgetsBinding.instance.addPostFrameCallback((timeStamp) {
    messageLiveCollection.loadNext();
  });

  scrollcontroller.addListener(paginationListener);
}

void paginationListener() {
  if ((scrollcontroller.position.pixels >=
          (scrollcontroller.position.maxScrollExtent - 100)) &&
      messageLiveCollection.hasNextPage()) {
    messageLiveCollection.loadNext();
  }
}

​
Best Practices

Dart Streams

Understanding Dart Streams and StreamSubscriptions

StreamBuilder Widget

Flutter’s StreamBuilder for reactive UI updates