Message History
Update time: 2021/12/03 03:06:52
CommsEase supports local storage and cloud storage of message history for future reference.
Local message history
Local search
The IM SDK provides an interface of querying local message history based on anchor to query limit number of data that is older (QUERY_OLD) than anchor (anchor message) or latest, (QUERY_NEW) and closest to anchor. The caller can specify result ranking rules with asc parameter. "time" is used as ranking field.
- API prototype
Asynchronous interface
java/**
* Query message history from the local message database based on anchor and direction.
* Query the LIMIT data closest to the anchor and older (QUERY_OLD) or newer (QUERY_NEW) than the anchor based on the direction (direct) provided.
* The caller can specify the result sorting rule based on asc parameter, and time is the sorting field.
* Note: The query results do not contain anchor.
*
* @return call tracking can set callback feature and receive query results.
*/
public InvocationFuture<List<IMMessage>> queryMessageListEx(IMMessage anchor, QueryDirectionEnum direction, int limit, boolean asc);
Synchronous interface
java/**
* Query message history from the local message database based on anchor and direction. (Synchronous feature) <br>
* Query the LIMIT data closest to the anchor and older (QUERY_OLD) or newer (QUERY_NEW) than the anchor based on the direction (direct) provided. <br>
* The caller can specify the result sorting rule based on asc parameter, and time is the sorting field. <br>
* Note: The query results do not contain anchor.
*
* @param anchor query anchor.
* @param direction query direction.
* @param limit entry limit of query results.
* @param asc sorting rules of query results. If true, the results are sorted in ascending chronological order; if false, the results are sorted in descending chronological order.
* @return call tracking can set callback feature and receive query results.
*/
List<IMMessage> queryMessageListExBlock(IMMessage anchor, QueryDirectionEnum direction, int limit, boolean asc);
- Parameters
Parameter | Description |
---|---|
anchor | Query anchor. |
direction | Query direction. |
limit | Limit for the number of query results. |
asc | Ranking rules of query results. |
Parameter anchor
is query anchor, i.e. for the message as query start point, an anchor is not included in query results. It cannot be set to null.
For the first query, null message can be generated as anchor with MessageBuilder.createEmptyMessage(...)
method. If peer-to-peer chat messages history with account accid001 must be queried and 5:00:00 PM 1/15/2019 (corresponding timestamp 1547542800000) is used as a query start point, then anchor can be configured as below:
javaIMMessage msg = MessageBuilder.createEmptyMessage("accid001", SessionTypeEnum.peer-to-peer, 1547542800000L);
direction
is query direction; QueryDirectionEnum.QUERY_OLD
is older message than anchor; QueryDirectionEnum.QUERY_NEW
is newer message than anchor. For example, 5:00:00 PM 1/15/2019 (corresponding timestamp 1547542800000) is taken as anchor:
- If the message from 4:59:00 PM to 5:00:00 PM must be queried, the direction must be set to
QueryDirectionEnum.QUERY_OLD
. - If the message from 5:00:00 PM to 5:01:00 PM must be queried, the direction must be set to
QueryDirectionEnum.QUERY_NEW
.
Parameter asc
is to rank query results by time; "true" is to rank by timestamp in ascending order; "false" is to rank by timestamp in a descending order.
- Example
java// Query messages earlier than anchor time, up to 20 messages, and sort the results in descending chronological order.
NIMClient.getService(MsgService.class).queryMessageListEx(anchor, QueryDirectionEnum.QUERY_OLD,
20, false).setCallback(new RequestCallbackWrapper<List<IMMessage>>() {
@Override
public void onResult(int code, List<IMMessage> result, Throwable exception) {
...
}
});
Querying by starting time and ending time
Similar to queryMessageListEx
, the interface adds a parameter "toTime" as deadline in query direction.
-
If the direction is QUERY_OLD, toTime must be smaller than anchor.getTime().
-
If the direction is QUERY_NEW, toTime must be larger than anchor.getTime().
The range of query results is determined by toTime and limit together, whichever occurs first. If the number of messages between anchor and toTime is larger than limit, then limit number of records will be returned. Otherwise, actual number of results will be returned.
- API prototype
java/**
* Query message history from the local message database based on the start time, end time, and query direction.
* Query the limit messages that are close to the anchor between anchor and toTime forward and backward, starting from anchor based on the direction provided.
* The query range is jointly determined by both toTime and limit, whichever comes first. If the message toTime is greater than the limit, return the limit number of records. If less than the limit, return the actual number.
* Sorting rules for query results: query results are sorted in descending chronological order when the direction is QUERY_OLD, and in ascending chronological order when the direction is QUERY_NEW.
* Note: The query results do not contain anchor.
*
* @return call tracking can set callback feature and receive query results.
*/
public InvocationFuture<List<IMMessage>> queryMessageListExTime(IMMessage anchor, long toTime, QueryDirectionEnum direction, int limit);
- Parameters
Parameter | Description |
---|---|
anchor | Query anchor. For anchor messages, see description in above queryMessageListEx method. |
toTime | Query ending time. If the direction is QUERY_OLD, then toTime must be smaller than anchor.getTime(). If the direction is QUERY_NEW, toTime must be larger than anchor.getTime(). |
direction | Query direction. |
limit | Limit for the number of query results. |
- Example
java// Taking peer-to-peer chat as an example, testAccount is a test account.
IMMessage msg = MessageBuilder.createEmptyMessage("testAccount", SessionTypeEnum.peer-to-peer, System.currentTimeMillis());
// Query data for 10s earlier than anchor, up to 10 messages.
NIMClient.getService(MsgService.class).queryMessageListExTime(msg, System.currentTimeMillis() - 10000, QueryDirectionEnum.QUERY_OLD, 10).setCallback(...);
Querying the most recent message
The API is used to query the most recent message of the specified session.
java/**
* @param account other party ID/ team ID.
* @param sessionType session type.
*/
IMMessage queryLastMessage(java.lang.String account,
SessionTypeEnum sessionType)
Querying by message uuid
- API prototype
Asynchronous interface:
java/**
* Get IMMessage by message ID at a time.
*
* @param uuids message IDs.
* @return
*/
public InvocationFuture<List<IMMessage>> queryMessageListByUuid(List<String> uuids);
Synchronous interface:
java/**
* Get IMMessage (Synchronous interface) by message ID at a time.
*
* @param uuids message uuids.
* @return
*/
public List<IMMessage> queryMessageListByUuidBlock(List<String> uuids);
- Example
java// Get IMMessage (Asynchronous interface) by message ID at a time.
List<String> uuids = new ArrayList<>();
uuids.add(message.getUuid());
NIMClient.getService(MsgService.class).queryMessageListByUuid(uuids);
Get IMMessage (Synchronous interface) by message ID at a time
NIMClient.getService(MsgService.class).queryMessageListByUuidBlock(uuids);
Querying by server ID
Get IMMessage (Synchronous interface) in batches by server ID.
Note: A ServerId may correspond to multiple messages.
java/**
* @param serverIds message server IDs.
* Returns a list consisting of messages of which ServerId is in the parameter list.
*/
java.util.List<IMMessage> queryMessageListByServerIdBlock(java.util.List<java.lang.String> serverIds);
Querying by message types
The specified type of message history is queried from a local database as per starting time, ending time, and query direction.
With anchor as starting point, limit number of messages close to the scope from anchor to toTime are queried forward or backward as per provided direction.
The query scope is determined by toTime and limit together, whichever occurs first. If the message toTime is greater than the limit, return the limit number of records. If less than the limit, return the actual number.
Ranking rules of query results: If asc is true, then results are ranked by time in ascending order; if it is false, then results are ranked by time in a descending order.
Note: The anchor is not included in query results.
- API prototype
java/**
* @param types set of queried messages, input null for all types of messages.
* @param anchor query anchor.
* @param toTime query deadline. If the direction is QUERY_OLD, toTime must be later than anchor.getTime(). If the direction is QUERY_NEW, toTime must be earlier than anchor.getTime(). 0 indicates no time limit, subject to limit.
* @param direction query direction.
* @param limit entry limit of query results.
* @param asc sorting rules of query results. If true, the results are sorted in an ascending chronological order; if false, the results are sorted in a descending chronological order.
* Return: Call tracking: you can set the callback feature, and receive the query results.
*/
InvocationFuture<java.util.List<IMMessage>> queryMessageListByTypes(java.util.List<MsgTypeEnum> types,
IMMessage anchor,
long toTime,
QueryDirectionEnum direction,
int limit,
boolean asc);
Query by message sub-types
The specified type of message history is queried from a local database as per starting time, and message type.
With anchor as a starting point, a limited number of messages are queried forward from anchor.
Notes: An anchor is not included in query results.
- API prototype
Asynchronous interface:
java/**
* Query local messages by message subtype (Asynchronous interface)
*
* @param msgTypeEnum message types.
* @param anchor search message anchor.
* @param limit entry limit of search results.
* @param subtype subtype.
* @return InvocationFuture.
*/
InvocationFuture<List<IMMessage>> queryMessageListBySubtype(MsgTypeEnum msgTypeEnum, IMMessage anchor, int limit, int subtype);
Synchronous interface:
java/**
* Query local messages by message subtype (Synchronous interface).
*
* @param msgTypeEnum message types.
* @param anchor search message anchor.
* @param limit entry limit of search results.
* @param subtype subtype.
* @return List of messages of consistent subtypes.
*/
List<IMMessage> queryMessageListBySubtypeBlock(MsgTypeEnum msgTypeEnum, IMMessage anchor, int limit, int subtype);
- Parameters
Parameter | Description |
---|---|
msgTypeEnum | Message types. |
anchor | Searched the message anchor. |
limit | Quantity limit for query results. |
subtype | Sub-type. |
- Example
javaNIMClient.getService(MsgService.class)
.queryMessageListBySubtype(getMsgTypes().get(0), msg, msgCount, subtype).setCallback(callback);
Deleting local messages
Deleting a message
Designate a message to be deleted locally.
- API prototype
java/**
* Delete a message
*
* @param message to-be-deleted messages.
* @param ignore true: No local clear history; false: Local clear history.
* When a message is pulled from the cloud and there is a record of local message deletion, the message will not be put into storage.
* Deletion tags will be overwritten by clear tags.
*/
void deleteChattingHistory(IMMessage message, boolean ignore);
- Parameters
Parameter | Description |
---|---|
message | Message history to be deleted. |
Ignore | true: No local clear history; false: Local clear history. When a message is pulled down from cloud, if there is local history of deleting the message, then the message will not be stored and delete token will be covered by a clear token. |
- Example
java// Delete a message.
NIMClient.getService(MsgService.class).deleteChattingHistory(message, false);
Deleting multiple messages
Designate multiple messages to be deleted locally.
- API prototype
java/**
* Delete multiple messages.
*
* @param msgList to-be-deleted messages.
* @param ignore true: No local clear history; false: Local clear history.
* When a message is pulled from the cloud and there is a record of local message deletion, the message will not be put into storage.
* Deletion tags will be overwritten by clear tags.
*/
void deleteChattingHistory(List<IMMessage> msgList, boolean ignore);
- Parameters
Parameter | Description |
---|---|
msgList | Message history to be deleted. |
Ignore | true: No local clear history; false: Local clear history. When a message is pulled down from cloud, if there is a local history of deleting the message, then the message will not be stored and delete token will be covered by a clear token. |
- Example
java// Delete a message.
NIMClient.getService(MsgService.class).deleteChattingHistory(msgList, false);
Deleting messages in a specified session
All messages of a certain session are removed from the local database, and it is possible to configure that the clear operation is stored in a database. If it is stored, then synchronization to a local database cannot be implemented after pulling some messages down from the cloud.
java/**
* Clear all local messages with the specified user.
*
* @param account User account.
* @param sessionType chat type.
* @param ignore true: No local clear history; false: Local clear history.
*/
void clearChattingHistory(String account, SessionTypeEnum sessionType, boolean ignore);
- Parameters
Parameter | Description |
---|---|
account | User account. |
sessionType | Chat object ID. It is user account for one-to-one chat and team ID for team chat. |
ignore | true (default): No local clear history. false: Local clear history. |
- Example
java// The clear operation is recorded locally.
NIMClient.getService(MsgService.class).clearChattingHistory(sessionId, sessionType, false);
The messages in specified time can be deleted using the following interface:
java/**
* Delete local message history based on time range (startTime, entTime), and an open interval exclude both endpoints, earlier than startTime, later than endTime.
* @param account other party ID/team ID.
* @param sessionType session type.
* @param startTime start time.
* @param endTime end time.
*/
void deleteRangeHistory(java.lang.String account,
SessionTypeEnum sessionType,
long startTime,
long endTime);
Deleting all messages
The SDK allows you to delete all messages in the database.
java/**
* Clear all messages from the message database.
* Whether to clear the local recent session list.
* If the recent contacts list is also cleared, MsgServiceObserve.observeRecentContactDeleted(Observer, boolean) notification will be triggered.
* @param clearRecent Whether to clear the local recent session list.
*/
void clearMsgDatabase(boolean clearRecent);
Message history on cloud
Querying message history on cloud
IM SDK provides the interface for querying message history on cloud. The query is made with anchor as start point (not including anchor). At most limit number of messages from anchor to toTime are queried forward or backward as per direction parameter. The query scope is determined by toTime and limit together, whichever occurs first. If the message toTime is greater than the limit, return the limit number of records. If less than the limit, return the actual number. If the query ends, size of returned result list may be smaller than limit.
For first query, anchor can be generated using MessageBuilder#createEmptyMessage
interface. Anchor is not included in query results. The final parameter of interface can be used to control that acquired message history is saved to local database. If the message history is saved to local database, when the interface for getting local message history, these messages also can be acquired.
- API prototype
java/**
* When a message is pulled from the cloud, the type of query messages can be specified, and the results are not stored in the local message database.
* <p>
* With anchor as the starting point (excluding anchor), query up to limit messages between the anchor and toTime forward or backward based on the direction parameter. <br>
* The query range is jointly determined by both toTime and limit, whichever comes first. If the message toTime is greater than the limit, return the limit number of records. If less than the limit, return the actual number.
* The size of the list of results returned may be smaller than the limit when a query is over.
*
* @param anchor message at start time is not null. <br>
* When a custom anchor is set, create an empty object by {@link MessageBuilder#createEmptyMessage(String, SessionTypeEnum, long)} <br>
* @param toTime ending time, Unit: millisecond.
* @param limit Upper limit of messages for this query (up to 100 messages).
* @ param direction query direction, QUERY_OLD query and sorting in reverse order by end time; QUERY_NEW query and sorting by starting time in positive order.
* @param msgTypes message type, array. Messages only include 0 : text, 1 : image, 2 : voice, 3 : video, 4 : location, 5 : notification, 6 : file, 10 : tip, 100 : custom, other parameters are invalid.
* @param persist roaming messages obtained by this interface are saved to the local message database or not.
* @param persistClear the cleared messages are saved to the local database or not, effective when persist==true.
* @param customFilter filter callback, ignored if it returns true, i.e. it is considered that this message is not pulled.
* @return InvocationFuture
*/
InvocationFuture<List<IMMessage>> pullMessageHistoryExType(IMMessage anchor, long toTime, int limit,
QueryDirectionEnum direction, MsgTypeEnum[] msgTypes, boolean persist,
boolean persistClear, IMMessageFilter customFilter);
- Parameters
Parameter | Description |
---|---|
anchor | The message at starting time cannot be null. When user-defined anchor is used, a null object can be created with MessageBuilder#createEmptyMessage. |
toTime | Ending time. Unit: millisecond. |
limit | Limit for the number of messages for query (max. 100). |
direction | Query direction: QUERY_OLD is to query and rank by ending time in reversed order; QUERY_NEW is to query and rank by starting time in positive sequence. |
persist | Determine that roaming message history acquired using the interface is saved to a local database. |
persistClear | Determine that cleared message is saved to a local database and take effect when persist==true. |
customFilter | Filter callback. If true is returned, then it can be neglected, i.e. as if there is not the message. |
Parameter anchor
is query anchor, i.e. for the message as a query start point, the anchor is not included in query results. It cannot be set to null.
For the first query, null message can be generated as an anchor with MessageBuilder.createEmptyMessage(...)
method. If peer-to-peer chat messages history with account accid001 must be queried and 5:00:00 PM 1/15/2019 (corresponding timestamp 1547542800000) is used as query start point, then anchor can be configured as below:
javaIMMessage msg = MessageBuilder.createEmptyMessage("accid001", SessionTypeEnum.peer-to-peer, 1547542800000L);
direction
is query direction; QueryDirectionEnum.QUERY_OLD
is older message than anchor; QueryDirectionEnum.QUERY_NEW
is newer message than anchor. For example, 5:00:00 PM 1/15/2019 (corresponding timestamp 1547542800000) is taken as an anchor:
- If the message from 4:59:00 PM to 5:00:00 PM must be queried, the direction must be set to
QueryDirectionEnum.QUERY_OLD
. - If the message from 5:00:00 PM to 5:01:00 PM must be queried, the direction must be set to
QueryDirectionEnum.QUERY_NEW
.
Parameter asc
is to rank query results by time; "true" is to rank by timestamp in ascending order; "false" is to rank by timestamp in a descending order.
- Example
java// 100 historical messages are pulled by server.
long newTime = System.currentTimeMillis();
long oldTime = newTime - 1000 * 60 * 60; // an hour ago.
IMMessage anchor = MessageBuilder.createEmptyMessage("testAccount", SessionTypeEnum.peer-to-peer, newTime);
NIMClient.getService(MsgService.class).pullMessageHistoryEx(anchor, oldTime, 100, QueryDirectionEnum.QUERY_OLD, false, false, message -> false) .setCallback(callback);
In addition, the following simple interfaces are also provided:
The message history is acquired from the server. Query direction of the interface is from back to front. With anchor as a starting point (not including anchor), at most limit number of messages are queried forward. If the query ends, size of returned result list may be smaller than the limit.
java/**
* @param anchor query anchor.
* @param limit upper limit of messages for this query (up to 100 messages).
* @param persist message history obtained by this interface is saved to the local message database or not.
* @param persistClear the cleared messages are saved to the local database or not, effective when persist==true.
*/
InvocationFuture<java.util.List<IMMessage>> pullMessageHistory(IMMessage anchor,
int limit,
boolean persist,
boolean persistClear);
Querying by message types
The message type can be specified for query when message history is acquired from the server.
- API prototype
java/**
*
* @param anchor message at start time is not null.
* @param toTime ending time. Unit: millisecond.
* @param limit upper limit of messages for this query (up to 100 messages).
* @ param direction query direction, QUERY_OLD query and sorting in reverse order by end time; QUERY_NEW query and sorting by starting time in positive order.
* @param msgTypes message type, array. Messages only include 0 : text, 1: image, 2: voice, 3: video, 4: location, 5: notification, 6: file, 10: tip, 100: custom, other parameters are invalid.
* @param persist message history obtained by this interface is saved to the local message database or not.
* @param persist Clear the cleared messages are saved to the local database or not.
* @return InvocationFuture.
*/
InvocationFuture<java.util.List<IMMessage>> pullMessageHistoryExType(IMMessage anchor,
long toTime,
int limit,
QueryDirectionEnum direction,
MsgTypeEnum[] msgTypes,
boolean persist,
boolean persistClear);
Deleting message history on cloud
Deleting message history of a session on cloud
- API prototype
java/**
* Clear message history.
*
* @param sessionId User account.
* @param sessionType chat type.
* @param sync whether synchronize message history of a session to other clients.
* @param ext extension field.
*/
void clearServerHistory(String sessionId, SessionTypeEnum sessionType, boolean sync, String ext);
- Parameters
Parameter | Description |
---|---|
sessionId | User account. |
sessionType | Session type. |
sync | Determine synchronization to other clients. |
ext | Extension field. |
- Example
javaNIMClient.getService(MsgService.class).clearServerHistory(sessionId, sessionType, true, "");
Deleting message history on cloud unilaterally
When the user deletes a message unilaterally successfully, the message cannot be acquired from the server any more under the account. Besides, if the user logs in from this client, other clients will delete the local message history. Other accounts will not be influenced by the operation. MsgServiceObserve#observeDeleteMsgSelf
callback will be triggered after the user deletes the message successfully.
- API prototype
java/**
* Delete a local message, server history and roaming unilaterally at the same time.
* @param msg message deleted from a direction.
* @param ext extension field.
*/
InvocationFuture<Long> deleteMsgSelf(IMMessage msg, String ext);
- Parameters
Parameter | Description |
---|---|
msg | Message to be deleted unilaterally |
ext | Extension field, optional |
- Example
javaNIMClient.getService(MsgService.class).deleteMsgSelf(selectedItem, "").setCallback(new RequestCallback<Long>() {
@Override
public void onSuccess(Long param) {
deleteItem(selectedItem, true);
}
@Override
public void onFailed(int code) {
ToastHelper.showToast(NimUIKit.getContext(), container.activity.getString(R.string.delete_msg_self_failed) + ", code=" + code);
}
@Override
public void onException(Throwable exception) {
NimLog.i("delete msg self", exception.getMessage());
}
});
Deleting multiple cloud message histories unilaterally
- API prototype
java/**
Multiple messages deleted from a direction are from the same session.
*
* @param msgList list of messages deleted from a direction.
* @param ext extension field.
*/
InvocationFuture<Long> deleteMsgSelf(List<IMMessage> msgList, String ext);
- Parameters
Parameter | Description |
---|---|
msgList | Message list to be deleted unilaterally. |
ext | Extension field. |
- Example
javaNIMClient.getService(MsgService.class).deleteMsgSelf(checked, "").setCallback(new RequestCallback<Long>() {
@Override
public void onSuccess(Long param) {
ToastHelper.showToast(MsgSelectActivity.this, "One-way deletion successful" + param);
mMsgAdapter.deleteItems(checked, true);
finish();
}
@Override
public void onFailed(int code) {
ToastHelper.showToast(MsgSelectActivity.this, "One-way deletion failed code=" + code);
}
@Override
public void onException(Throwable exception) {
ToastHelper.showToast(MsgSelectActivity.this, "One-way deletion error msg=" + exception.getMessage());
exception.printStackTrace();
}
});
Message search
The SDK allows you to search by keywords with lucene plugin or built-in search feature.
Local search
Searching a specific session
The SDK provides the feature of searching chat history by keywords. The user can input keywords to search message content for specified chat object. Query direction is from back to front. The anchor is used as a start point to query. At most limit number of histories matching with keywords can be returned. The interface supports searching text message only. The matching rule is that text content includes a keyword. It recently supports accurate matching only, except fuzzy matching and pinyin matching.
- API prototype
java/**
* Query message history from the local message database. The query range is determined by the sessionId and sessionType of the anchor.
* Return up to LIMIT matched keys by query direction.
* The interface Currently, only searches text messages. based on the matching rules, the text content contains keyword, and only supports exact matching, not fuzzy matching and Pinyin matching.
* Note: search results exclude anchor.
* @return InvocationFuture.
*/
InvocationFuture<java.util.List<IMMessage>> searchMessageHistory(java.lang.String keyword, java.util.List<java.lang.String> fromAccounts, IMMessage anchor, QueryDirectionEnum direction, int limit);
- Parameters
Parameter | Description |
---|---|
keyword | Search keyword of text messages. |
fromAccounts | List of message senders' accounts. |
anchor | Searched message anchor. |
direction | Query direction. |
limit | Quantity limit for query results. |
- Example
java// Search『keywords』20
NIMClient.getService(MsgService.class).searchMessageHistory("keywords", fromAccounts, anchor, direction,20)
.setCallback(new RequestCallbackWrapper<List<IMMessage>>(){... });
Global search
In addition, the SDK also provides a global search interface "MsgService#searchAllMessageHistory" for chat history by keyword. The interface method is similar to the above interface. The global search feature in indexed mode is not allowed now. For the global search interface, the developer needs to evaluate performance expenses under big data.
The message history is searched by time. Query direction of the interface is from back to front based on a certain time. At most limit number of histories matching with key are returned. The interface supports searching text message only. The matching rule is that text content includes keyword. It supports accurate matching only, except fuzzy matching and pinyin matching.
- API prototype
java/**
* Query message history from the local message database.
* The query direction of this interface takes a certain time of period as the benchmark and returns up to limit matching keys.
* The interface Currently, only searches text messages. based on the matching rules, the text content contains a keyword, and only supports exact matching, not fuzzy matching and Pinyin matching.
* @return InvocationFuture.
*/
public InvocationFuture<List<IMMessage>> searchAllMessageHistory(String keyword, List<String> fromAccounts, long time, int limit);
- Parameters
Parameter | Description |
---|---|
keyword | Search the keyword of text messages. |
fromAccounts | List of message senders' accounts. |
time | Search from back to front by the time. |
limit | Quantity limit for query results. |
- Example
javaNIMClient.getService(MsgService.class).searchAllMessageHistory(keyword, fromAccounts, time, limit)
.setCallback(new RequestCallbackWrapper<List<IMMessage>>(){... });
Querying the number of hit messages
The filtered message count can be returned by the following interface:
java/*
* @param query to-be-retrieved string.
* @param limit The maximum number of records returned.
*/
// asynchronous
InvocationFuture<java.util.List<MsgIndexRecord>> searchAllSession(java.lang.String query, int limit);
// synchronous
java.util.List<MsgIndexRecord> searchAllSessionBlock(java.lang.String query, int limit);
All filtered message histories can be returned using the following interface:
java/**
* Retrieve the specified session and return all the messages that match the retrieved string in that session.
*/
// Asynchronous.
InvocationFuture<java.util.List<MsgIndexRecord>> searchSession(java.lang.String query, SessionTypeEnum sessionType, java.lang.String sessionId);
// Synchronous.
java.util.List<MsgIndexRecord> searchSessionBlock(java.lang.String query, SessionTypeEnum sessionType, java.lang.String sessionId);
Search messages of a one-to-one chat on cloud
- API prototype
java/**
* Cloud chat history keyword query.
*
* @param otherAccid other party account.
* @param fromTime start time. Unit: millisecond.
** @param endTime ending time. Unit: millisecond.
* @param keyword search keyword.
* @param limit upper limit of messages for this query (up to 100 messages).
* @param reverse optional parameter. False indicates that the parameter is not input by false, and true indicates reverse query (in positive chronological order, positive sorting). False indicates reverse chronological order and reverse sorting by default.
*/
InvocationFuture<ArrayList<IMMessage>> searchRoamingMsg(String otherAccid, long fromTime, long endTime, String keyword, int limit, boolean reverse);
- Parameters
Parameter | Description |
---|---|
otherAccid | Account of the other party. |
fromTime | Starting time, unit: millisecond. |
endTime | End time. Unit: millisecond. |
keyword | Searched keyword. |
limit | Limit for the number of messages for query (max. 100). |
reverse | Optional parameter. If it is not specified with value, it is "false" by default. "true" indicates reverse query (query and rank by time in positive sequence). Default "false" indicates to query and rank by time in a reversed order. |
- Example
javaNIMClient.getService(MsgService.class).searchRoamingMsg(
accidEdit.getText().toString(),
startTime,
endTime,
keywordEdit.getText().toString(),
queryAmount,
true).setCallback(new RequestCallback<ArrayList<IMMessage>>() {
@Override
public void onSuccess(ArrayList<IMMessage> param) {
StringBuilder roamingmsg = new StringBuilder();
for (IMMessage RoamingMsg:param){
roamingmsg.append("sessionid:"+ RoamingMsg.getSessionId());
roamingmsg.append(" , message content:" + RoamingMsg.getContent());
roamingmsg.append(" , occurrence time :" + RoamingMsg.getTime());
roamingmsg.append(" , session type :" + RoamingMsg.getSessionType());
}
roamingMsg.setText(roamingmsg.toString());
}
@Override
public void onFailed(int code) {
Toast.makeText(SessionActivity2.this, "cloud chat record keyword query failed, code=" + code, Toast.LENGTH_SHORT).show();
}
@Override
public void onException(Throwable exception) {
Toast.makeText(SessionActivity2.this, "cloud chat record keyword query exception, msg=" + exception.getMessage(), Toast.LENGTH_SHORT).show();
}
});
Search messages of a team chat on cloud
java/**
* Team session message history on cloud keyword query.
* @param tid team ID.
* @param fromTime start time. Unit: millisecond.
** @param endTime ending time. Unit: millisecond.
* @param keyword query keywords.
* @param limit upper limit of messages for this query (up to 100 messages).
* @param reverse optional parameter. True indicates reverse query (in positive chronological order, positive sorting), and false indicates reverse chronological order and reverse sorting by default.
*/
InvocationFuture<java.util.List<IMMessage>> searchTeamMsgByKeyword(long tid,
long fromTime,
long endTime,
java.lang.String keyword,
int limit,
boolean reverse);
Search using the lucene plugin
CommsEase SDK v2.7.0 is provided with Lucene-based global search plugin which supports local global search for chat messages in a client. The current query interface can be used for the following two demands:
- Use case 1:
Search all sessions and return sessions with matched keywords, and a number of messages with matched keywords in each session. If only one message has matched the keyword in the session, then the message is returned , a number of returned sessions can be specified and all sessions can be listed at a time. The sessions are ranked by the time of the recent matched message in each session in a reverse order. It needs to support queries by multiple keywords. These keywords must be separated by space and have AND relationship.
- Use case 2:
Search a session, return all messages with matched keywords, and highlight filtered keywords, and skip to the context of the message.
CommsEase SDK provides query service for the above demands now. As long as global search plugin is integrated, the SDK will automatically synchronize all chat histories to global search indexes. The dependent Lucene source codes have been substantially simplified in v2.8.0, with size of about 1M+. The large project may still have a restriction for a number of operations 65535, which may require the support of Multi dex.
Plugin integration
See SDK integration.
Interface description
A global search interface is LuceneService. The detailed API is listed as below (Only Asynchronous interface is listed only and synchronous interface API is also provided. See client API document.) For demand 2, we recommend using query by paging interface.
java/**
* Retrieve all the sessions and return the messages matched with retrieval strings in each session and recent matched message. (Asynchronous feature)
*
* @param query to-be-retrieved string.
* @param limit The maximum number of records returned.
* @return InvocationFuture you can set the callback feature, and return the set of chat message full-text retrieval results during the callback.
*/
public InvocationFuture<List<MsgIndexRecord>> searchAllSession(String query, int limit);
/**
* Retrieve the specified session and return all the messages that match the retrieved string in that session. (Asynchronous feature).
*
* @param query to-be-retrieved string.
* @param sessionType to-be-retrieved session type (individual/team).
* @param sessionId to-be-retrieved session ID.
* @return set of chat message full-text retrieval results.
*/
public InvocationFuture<List<MsgIndexRecord>> searchSession(String query, SessionTypeEnum sessionType, String sessionId);
/**
* Specify session keyword query (return records matched by page) (asynchronous).
*
* @param query to-be-retrieved string.
* @param sessionType to-be-retrieved session type (individual/team).
* @param sessionId to-be-retrieved session ID.
* @param pageIndex page (starting from page 1).
* @param pageSize page size.
* @return InvocationFuture you can set the callback feature, and return the set of chat message full-text retrieval results during callback.
*/
public InvocationFuture<List<MsgIndexRecord>> searchSessionPage(String query, SessionTypeEnum sessionType, String sessionId, int pageIndex, int pageSize);
/**
* Specify session keyword query (query by page: return the records matched on next page based on the anchor) (asynchronous).
*
* @param query to-be-retrieved string.
* @param sessionType to-be-retrieved session type (individual/team).
* @param sessionId to-be-retrieved session ID.
* @param anchor input null on the first page, and input the last record of the previous page on next page.
* @param pageSize Page size.
* @return InvocationFuture you can set the callback feature, and return the set of chat message full-text retrieval results during a callback.
*/
public InvocationFuture<List<MsgIndexRecord>> searchSessionNextPage(String query, SessionTypeEnum sessionType, String sessionId, MsgIndexRecord anchor, int pageSize);
/**
* Specify the total number of session keyword query records matched (synchronous).
*
* @param query to-be-retrieved string.
* @param sessionType to-be-retrieved session type (individual/team).
* @param sessionId to-be-retrieved session ID.
@return total number of records matched.
*/
public int searchSessionMatchCount(String query, SessionTypeEnum sessionType, String sessionId);
/**
* Specify the total pages of session keyword query matching records (synchronous).
*
* @param query to-be-retrieved string.
* @param sessionType to-be-retrieved session type (individual/team).
* @param sessionId to-be-retrieved session ID.
* @param pageSize number of records per page.
@return total number of records matched.
*/
public int searchSessionPageCount(String query, SessionTypeEnum sessionType, String sessionId, int pageSize);
/**
* Get the size of all cached data.
* @return The number of bytes of cached data.
*/
public long getCacheSize();
/**
* Delete all cached data.
*/
public void clearCache();