A MessageCollection retrieves data from both the local cache and Sendbird server and lets you quickly create a chat view without missing any message-related updates. This page explains how to create a chat view using the collection and serves as a migration guide.
In local caching, the MessageListParams is used instead of SyncManager's MessageFilter.
A MessageListParams instance will determine how to sort and list the retrieved messages. Then, specify the starting point of the message list in the chat view using the collection's builder.
Local cachingSyncManager
private void createMessageCollection() {
// Create a MessageListParams to be used in the MessageCollection.
MessageListParams params = new MessageListParams();
params.setReverse(false);
// You can add other query setters.
final MessageCollection collection = new MessageCollection.Builder(groupChannel, params)
.setStartingPoint(startingPoint)
.build();
Use the setMessageCollectionHandler() to determine how the client app reacts to message-related events.
A new addition to local caching is the onHugeGapDetected. If more than 300 messages are missing in the local cache compared to the remote server, Sendbird Chat SDK determines that there is a huge gap. For more information, see Gap and synchronization.
The following table shows when to call each event handler.
Handler
Called when
onMessageAdded()
- A new message is created as a real-time event. - New messages are fetched during changelog sync.
onMessageDeleted()
- A message is deleted as a real-time event. - Message deletion is detected during changelog sync. - The value of the MessageListParams setter such as custom_type changes.
onMessageUpdated()
- A message is updated as a real-time event. - Message update is detected during changelog sync. - The sending status of a pending message changes.
onChannelUpdated()
- The channel information that is included in the user's current chat view is updated as a real-time event. -Channel info update is detected during changelog sync.
onChannelDeleted()
- The current channel is deleted as a rea-time event. - Channel deletion is detected during changelog sync. - In both cases, the entire view should be disposed.
onHugeGapDetected()
- A huge gap is detected through Background sync. In this case, you need to dispose of the view and create a new MessageCollection instance.
SyncManager's onSucceededMessageEvent(), onPendingMessageEvent(), and onFailedMessageEvent() should be changed as shown in the code below.
Local cachingSyncManager
messageCollection.setMessageCollectionHandler(new MessageCollectionHandler() {
/**
* SyncManager's following events should be handled through the onMessagesAdded() in local caching:
* 1. onSucceededMessageEvent() MessageEventAction.INSERT.
* 2. onPendingMessageEvent() MessageEventAction.INSERT when sending a message.
*/
@Override
public void onMessagesAdded(@NonNull MessageContext context, @NonNull GroupChannel channel, @NonNull List<BaseMessage> messages) {
}
/**
* SyncManager's following events should be handled through the onMessagesUpdated() in local caching:
* 1. onSucceededMessageEvent() MessageEventAction.UPDATE.
* 2. onPendingMessageEvent() MessageEventAction.INSERT when resending a failed message.
* 3. onFailedMessageEvent() MessageEventAction.INSERT when sending or resending a message failed.
*/
@Override
public void onMessagesUpdated(@NonNull MessageContext context, @NonNull GroupChannel channel, @NonNull List<BaseMessage> messages) {
}
/**
* SyncManager's following events should be handled through the onMessagesDeleted() in local caching:
* 1. onSucceededMessageEvent() MessageEventAction.REMOVE.
* 2. onFailedMessageEvent() MessageEventAction.REMOVE.
*/
@Override
public void onMessagesDeleted(@NonNull MessageContext context, @NonNull GroupChannel channel, @NonNull List<BaseMessage> messages) {
}
/**
* SyncManager's onChannelUpdated() events should be handled through the onChannelUpdated() in local caching.
*/
@Override
public void onChannelUpdated(@NonNull GroupChannelContext context, @NonNull GroupChannel channel) {
}
/**
* SyncManager's onChannelRemoved() events should be handled through the onChannelDeleted() in local caching.
*/
@Override
public void onChannelDeleted(@NonNull GroupChannelContext context, @NonNull String channelUrl) {
}
/**
* The onHugeGapDetected() is called when the SDK detects more than 300 messages missing while connecting online.
* The current message collection should be disposed and a new MessageCollection is created.
*/
@Override
public void onHugeGapDetected() {
if (messageCollection != null) {
messageCollection.dispose();
}
int firstItemPosition = ((LinearLayoutManager) recyclerView.getLayoutManager()).findFirstVisibleItemPosition();
if (firstItemPosition >= 0) {
final BaseMessage message = chatAdapter.getItem(position);
messageCollection = new MessageCollection.Builder(mChannel, messageListParams)
.setStartingPoint(message != null ? message.getCreatedAt() : messageCollection.getStartingPoint())
.build();
} else {
messageCollection = new MessageCollection.Builder(mChannel, messageListParams)
.setStartingPoint(messageCollection.getStartingPoint())
.build();
}
messageCollection.setMessageCollectionHandler(messageCollectionHandler);
}
});
SyncManager's onNewMessage() which notifies the client app of new messages in a channel should also be changed as shown in the code below.
Local cachingSyncManager
SendBird.addChannelHandler("MessageCollectionNewMessage", new SendBird.ChannelHandler() {
@Override
public void onMessageReceived(BaseChannel channel, BaseMessage message) {
if (!this.channel.getUrl().equals(channel.getUrl())) {
// There's no new message for this channel.
return;
}
boolean isScrolledUp = ((LinearLayoutManager) recyclerView.getLayoutManager()).findFirstVisibleItemPosition() > 0;
if (isScrolledUp) {
showNewMessageTooltip(message);
}
}
});
SyncManager's fetchSucceededMessages() method retrieves messages from the local cache and delivers them to the MessageCollectionHandler. In local caching, the MessageCollection can retrieve and display messages through four new interfaces, hasPrevious(), hasNext(), loadPrevious(), and loadNext().
Unlike the GroupChannelCollection, pagination works in both directions for messages because messages can be shown in either chronological or reverse chronological order depending on how you set the value of the startingPoint.
Method
Description
hasPrevious()
- Checks if there are more messages to load from the previous page. - Called whenever a user scroll hits the top of the chat view.
loadPrevious()
- If hasPrevious() is true, retrieves messages from the local cache to show in the view. - Called whenever a user scroll hits the top of the chat view.
hasNext()
- Checks if there are more messages to load in the next page. - Called whenever a user scroll hits the bottom of the chat view.
loadNext()
- If hasNext() is true, retrieves messages from the local cache to show in the view. - Called whenever a user scroll hits the bottom of the chat view.
In a MessageCollection, the initialization is dictated by the MessageCollectionInitPolicy. The MessageCollectionInitPolicy determines how initialization deals with the message data retrieved from the local cache and API calls. Because we only support the InitPolicy.CACHE_AND_REPLACE_BY_API at this time, you should clear all messages in the local cache before adding messages from the remote server. Messages will first be retrieved from the cached list using the onCacheResult(). Next, the onApiResult() calls the API result list which then replaces the cached message list with messages received from the API call.
Local cachingSyncManager
// Initialize messages from the startingPoint.
messageCollection.initialize(MessageCollectionInitPolicy.CACHE_AND_REPLACE_BY_API, new MessageCollectionInitHandler() {
@Override
public void onCacheResult(@Nullable List<BaseMessage> cachedList, @Nullable SendBirdException e) {
// Messages will be retrieved from the local cache.
// They might be too outdated compared to the startingPoint.
}
@Override
public void onApiResult(@Nullable List<BaseMessage> apiResultList, @Nullable SendBirdException e) {
// Messages will be retrieved through API calls from Sendbird server.
// According to the MessageCollectionInitPolicy.CACHE_AND_REPLACE_BY_API,
// the existing data source needs to be cleared
// before adding retrieved messages to the local cache.
}
});
// Next direction
if (messageCollection.hasNext()) {
messageCollection.loadNext(new BaseChannel.GetMessagesHandler() {
@Override
public void onResult(List<BaseMessage> messages, SendBirdException e) {
// The message list returns as a callback.
}
});
}
// Previous direction
if (messageCollection.hasPrevious()) {
messageCollection.loadPrevious(new BaseChannel.GetMessagesHandler() {
@Override
public void onResult(List<BaseMessage> messages, SendBirdException e) {
// The message list returns as a callback.
}
});
}
A viewpoint is a timestamp option that sets the starting point of the current user's view. This viewpoint can be reset anytime by calling the resetViewpointTimestamp() method. SyncManager's resetViewpointTimestamp is used to reset the timestamp of the current message collection to another specified time. To reset a viewpoint timestamp in local caching, you should dispose of the current message collection and create a new one.
Local cachingSyncManager
messageCollection.dispose();
messageCollection = new MessageCollection.Builder(channel, messageListParams)
.setStartingPoint(TARGET_TIMESTAMP)
.build();
In local caching, the result of sending a message is handled internally through the MessageCollectionHandler. First, pending messages are delivered to local caching's MessageCollectionHandler.onMessagesAdded(). Whether the message succeeds or fails in sending, the result will be delivered to the MessageCollectionHandler.onMessagesUpdated(). Thus, in local caching, it is not necessary to manually input the send status using a onSent() callback from the sendUserMessage() and the sendFileMessage() as in SyncManager.
Note: Don't add the pending, succeeded or failed message objects of the sendMessage() callback to your message list data source. This can cause duplicate messages in the chat view.
In local caching, the result of resending a message is handled internally through the MessageCollectionHandler. First, pending messages are delivered to local caching's MessageCollectionHandler.onMessagesUpdated(). Whether the message has succeeded or failed in sending, the result will be delivered to the MessageCollectionHandler.onMessagesUpdated(). Thus, in local caching, it is not necessary to manually input the send status using a onSent() callback from the resendMessage() as in SyncManager.
Note: Don't add the pending, succeeded or failed message objects of the resendMessage() callback to your message list data source. This can cause duplicate messages in the chat view.
SyncManager uses the onUpdated() callback to manually update a message in the collection after updating the same message in a channel. In local caching, however, updating messages is handled internally, and the result is delivered to the MessageCollectionHandler.onMessagesUpdated().
Local cachingSyncManager
channel.updateUserMessage(message.getMessageId(), new UserMessageParams(EDITED_MESSAGE), null);
In SyncManager, the process of delivering the status of message deletion through the deleteMessage() is required. However, this process isn't needed in local caching.
Deleting a failed message.
The process is the same for both SyncManager and local caching where the failed message object is deleted explicitly from the local cache. In SyncManager, failed messages are deleted through the deleteMessage(). In local caching, the same can be done through the removeFailedMessages().
Local cachingSyncManager
// 1. Deleting a succeeded message. Delete from the channel object. The result will be delivered to
//the MessageCollectionHandler.onMessagesDeleted().
channel.deleteMessage(message, null);
// 2-1. Deleting a failed message. Delete from the collection only.
messageCollection.removeFailedMessages(Collections.singletonList(message), new RemoveFailedMessagesHandler() {
@Override
public void onResult(List<String> requestIds, SendBirdException e) {
}
});
// 2-2. Deleting all failed messages. Delete from the collection only
messageCollection.removeAllFailedMessages(new RemoveAllFailedMessagesHandler() {
@Override
public void onResult(SendBirdException e) {
// All failed messages are deleted.
}
});
SyncManager's MessageCollection has a remove() method that clears all the messages managed by the collection and stops the synchronization processes in the collection instance.
On the other hand, local caching uses the dispose() method to clear the existing chat view. You should call this method when the current user leaves the channel or you need to create a new collection because a huge gap has been detected by the onHugeGapDetected().
SyncManager's messageCollection.getMessageCount() and messageCollection.contains(message) are replaced with messageCollection.getSucceededMessages() in local caching. It is used to count the number of succeeded messages in the collection.
Local cachingSyncManager
// A messageCollection provides a getter for the current message list in the message collection.
List<BaseMessage> succeededMessageList = messageCollection.getSucceededMessages();
int messageCount = succeededMessageList.size();
boolean contains = succeededMessageList.contains(message);