ChatroomManager (Straas Android SDK 0.24.0 API)

java.lang.Object
- io.straas.android.sdk.messaging.ChatroomManager

```
public class ChatroomManager
extends Object
```
ChatroomManager is used to manage a chatroom or a message board.
You could call initialize() to get a ChatroomManager. This method will check your developer credential and construct a ChatroomManager if you are authorized. Then, you could call connect(String, Identity) to connect to a chatroom and start using other methods.

Nested Class Summary

Nested Classes
Modifier and Type Class and Description

static class ChatroomManager.ChatroomConfig
Configuration for ChatroomManager.

Nested Classes
Modifier and Type	Class and Description
`static class`	`ChatroomManager.ChatroomConfig` Configuration for `ChatroomManager`.

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`void`	`addAllEventListener(EventListener... listeners)`
`boolean`	`addEventListener(EventListener listener)`
`void`	`addFakeMessage(Message message)`
`com.google.android.gms.tasks.Task<Void>`	`blockUsers(List<User> users)` Block target users.
`com.google.android.gms.tasks.Task<Void>`	`connect(String chatroomName, Identity identity)` Connects to a chatroom.
`com.google.android.gms.tasks.Task<Void>`	`disconnect()` Disconnect from current server.
`com.google.android.gms.tasks.Task<AggregatedData[]>`	`getAggregatedData(MessageRequest request)` Get aggregated-data history in this chatroom.
`ChatMode`	`getChatMode()` Returns `ChatMode`.
`com.google.android.gms.tasks.Task<ChatroomInfo>`	`getChatroomInfo()` Gets `ChatroomInfo` of current chatroom.
`ChatroomState`	`getChatroomState()` Returns current chatroom state.
`User`	`getCurrentUser()` Returns current user.
`com.google.android.gms.tasks.Task<Message[]>`	`getMessages(MessageRequest request)` Get Message history in this chatroom.
`com.google.android.gms.tasks.Task<androidx.collection.SimpleArrayMap<String,ChatMetadata>>`	`getMetadata(String... keys)` Gets the meta data from current chatroom.
`Message`	`getPinnedMessage()` Returns the pinned message in current chatroom.
`com.google.android.gms.tasks.Task<Message[]>`	`getRawData(MessageRequest request)` Get `RawData` history in this chatroom.
`int`	`getSendMessageInterval()` Returns send message interval of current chatroom.
`List<Sticker>`	`getSticker()` Returns available stickers.
`androidx.collection.SimpleArrayMap<String,Integer>`	`getTotalAggregatedData()` Retrieve total aggregated data.
`int`	`getUserCount()` Returns current user count.
`com.google.android.gms.tasks.Task<User[]>`	`getUsers(UserType userType)` Gets users in this chatroom.
`static com.google.android.gms.tasks.Task<ChatroomManager>`	`initialize()` Constructs a `ChatroomManager` if you are a authorized developer.
`static com.google.android.gms.tasks.Task<ChatroomManager>`	`initialize(ChatroomManager.ChatroomConfig config)` Constructs a `ChatroomManager` if you are a authorized developer.
`com.google.android.gms.tasks.Task<Void>`	`pinMessage(Message message)` Pin a message to this chatroom, then everybody in this chatroom can get the pinned message by `getPinnedMessage()` or `EventListener.onPinnedMessageUpdated(Message)`.
`void`	`removeAllEventListener()` Remove all event listener, no one could receive future event.
`boolean`	`removeEventListener(EventListener listener)`
`com.google.android.gms.tasks.Task<Void>`	`removeMessage(Message message)` Remove message.
`boolean`	`resetIdentity(Identity identity)` Resets `Identity`.
`com.google.android.gms.tasks.Task<Void>`	`reviveUsers(List<User> users)` Revive users from blocked status.
`com.google.android.gms.tasks.Task<Void>`	`sendAggregatedData(String message)` Send a string to chatroom which will be aggregated in `onAggregatedDataAdded`.
`com.google.android.gms.tasks.Task<Void>`	`sendMessage(String message)` Sends message to chatroom.
`com.google.android.gms.tasks.Task<Void>`	`sendRawData(RawData rawData)` Send the `RawData` to chatroom.
`com.google.android.gms.tasks.Task<Void>`	`setMetadata(String key, Object value, boolean broadcast)` Sets a set of meta data to current chatroom.
`com.google.android.gms.tasks.Task<Void>`	`unpinMessage()` Unpin the message from chatroom.
`com.google.android.gms.tasks.Task<Void>`	`updateNickname(String name)` Updates current user's nick name to server.
`com.google.android.gms.tasks.Task<Void>`	`updateUserRole(User user, Role role)` Update a user's role.
`com.google.android.gms.tasks.Task<Void>`	`updateUserRoleByMemberId(String memberId, Role role)` Update a user's role by memberId.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Method Detail
  - initialize
```
public static com.google.android.gms.tasks.Task<ChatroomManager> initialize()
```
    Constructs a ChatroomManager if you are a authorized developer.
    
    Returns:
    
    You could get a ChatroomManager if Task.isSuccessful().
  - initialize
```
public static com.google.android.gms.tasks.Task<ChatroomManager> initialize(@NonNull
                                                                            ChatroomManager.ChatroomConfig config)
```
    Constructs a ChatroomManager if you are a authorized developer.
    
    Parameters:
    
    config - configuration about the ChatroomManager
    
    Returns:
    
    You could get a ChatroomManager if Task.isSuccessful().
  - connect
```
public com.google.android.gms.tasks.Task<Void> connect(@NonNull
                                                       String chatroomName,
                                                       @NonNull
                                                       Identity identity)
```
    Connects to a chatroom.
    This method should only be called when the chatroom state is ChatroomState.IDLE.
    
    Parameters:
    
    chatroomName - Target chatroom name.
    
    identity - The user who connecting to a chatroom. see Identity. If Identity is a guest, this person will login as a guest named "Guest".
  - resetIdentity
```
public boolean resetIdentity(Identity identity)
```
    Resets Identity. If you receive MessagingException.UnauthorizedException when the chatroom state is ChatroomState.CONNECTED, it means the member token in Identity is expired or invalid. Then, you can use this method to put new Identity in. Notice that the new Identity and the old Identity have to represent the same person.
    This method should only be called when the chatroom state is ChatroomState.CONNECTED.
    
    Parameters:
    
    identity - New identity.
    
    Returns:
    
    True if reset succeeds.
  - getMessages
```
public com.google.android.gms.tasks.Task<Message[]> getMessages(MessageRequest request)
```
    Get Message history in this chatroom. You can set the request rule in MessageRequest.
    This method should only be called when the chatroom state is ChatroomState.CONNECTED.
    
    Parameters:
    
    request - request rule, see MessageRequest
    
    Returns:
    
    You could get the target Message if Task.isSuccessful().
  - getAggregatedData
```
public com.google.android.gms.tasks.Task<AggregatedData[]> getAggregatedData(MessageRequest request)
```
    Get aggregated-data history in this chatroom. You can set the request rule in MessageRequest.
    This method should only be called when the chatroom state is ChatroomState.CONNECTED.
    
    Parameters:
    
    request - request rule, see MessageRequest
    
    Returns:
    
    You could get the target AggregatedData arrays if Task.isSuccessful().
  - getRawData
```
public com.google.android.gms.tasks.Task<Message[]> getRawData(MessageRequest request)
```
    Get RawData history in this chatroom. You can set the request rule in MessageRequest.
    This method should only be called when the chatroom state is ChatroomState.CONNECTED.
    
    Parameters:
    
    request - request rule, see MessageRequest
    
    Returns:
    
    You could get the target Message if Task.isSuccessful().
  - getUsers
```
public com.google.android.gms.tasks.Task<User[]> getUsers(UserType userType)
```
    Gets users in this chatroom. The maximum returned count is 200. Users will be returned in the order [Role.GLOBAL_MANAGER > Role.LOCAL_MANAGER > Role.MASTER > Role.MODERATOR > Role.NORMAL > Role.BLOCKED)] and user updated time.
    This method should only be called when the chatroom state is ChatroomState.CONNECTED.
    
    Parameters:
    
    userType - decides who should be returned
    
    Returns:
    
    You could get the target User if Task.isSuccessful().
  - getChatroomInfo
```
public com.google.android.gms.tasks.Task<ChatroomInfo> getChatroomInfo()
```
    Gets ChatroomInfo of current chatroom.
    This method should only be called when the chatroom state is ChatroomState.CONNECTED.
    
    Returns:
    
    You could get a ChatroomInfo if Task.isSuccessful().
  - updateNickname
```
public com.google.android.gms.tasks.Task<Void> updateNickname(String name)
```
    Updates current user's nick name to server.
    This method should only be called when the chatroom state is ChatroomState.CONNECTED and the current user is a guest.
    
    Parameters:
    
    name - New nick name.
  - updateUserRole
```
public com.google.android.gms.tasks.Task<Void> updateUserRole(User user,
                                                              Role role)
```
    Update a user's role. You can use this method only to change user from Role.NORMAL to Role.MODERATOR or from Role.MODERATOR to Role.NORMAL.
    This method should only be called when the chatroom state is ChatroomState.CONNECTED and the current user is a Role.GLOBAL_MANAGER, Role.LOCAL_MANAGER, Role.MASTER.
    
    Parameters:
    
    user - the target user
    
    role - new Role
  - updateUserRoleByMemberId
```
public com.google.android.gms.tasks.Task<Void> updateUserRoleByMemberId(String memberId,
                                                                        Role role)
```
    Update a user's role by memberId. You can use this method only to change user from Role.NORMAL to Role.MODERATOR or from Role.MODERATOR to Role.NORMAL.
    This method should only be called when the chatroom state is ChatroomState.CONNECTED and the current user is a Role.GLOBAL_MANAGER, Role.LOCAL_MANAGER, Role.MASTER.
    
    Parameters:
    
    memberId - the target user's member id
    
    role - new Role
  - blockUsers
```
public com.google.android.gms.tasks.Task<Void> blockUsers(List<User> users)
```
    Block target users. A blocked user can't send message.
    This method should only be called when the chatroom state is ChatroomState.CONNECTED and the current user is a Role.GLOBAL_MANAGER, Role.LOCAL_MANAGER, Role.MASTER, or Role.MODERATOR.
    
    Parameters:
    
    users - The target users.
  - reviveUsers
```
public com.google.android.gms.tasks.Task<Void> reviveUsers(List<User> users)
```
    Revive users from blocked status.
    This method should only be called when the chatroom state is ChatroomState.CONNECTED and the current user is a Role.GLOBAL_MANAGER, Role.LOCAL_MANAGER, Role.MASTER, or Role.MODERATOR.
    
    Parameters:
    
    users - The target users.
  - removeMessage
```
public com.google.android.gms.tasks.Task<Void> removeMessage(Message message)
```
    Remove message.
    This method should only be called when the chatroom state is ChatroomState.CONNECTED and the current user is a Role.GLOBAL_MANAGER, Role.LOCAL_MANAGER, Role.MASTER, or Role.MODERATOR.
    
    Parameters:
    
    message - The message to remove.
  - sendMessage
```
public com.google.android.gms.tasks.Task<Void> sendMessage(String message)
```
    Sends message to chatroom. This method can't be called more than once within one second, or you will receive MessagingException.PermissionException.
    This method should only be called when the chatroom state is ChatroomState.CONNECTED.
    
    Parameters:
    
    message - message, should be within 500 characters and shouldn't be empty
  - pinMessage
```
public com.google.android.gms.tasks.Task<Void> pinMessage(Message message)
```
    Pin a message to this chatroom, then everybody in this chatroom can get the pinned message by getPinnedMessage() or EventListener.onPinnedMessageUpdated(Message). A chatroom can only have a pinned message at one time, it means this method will override the last pinned message.
    This method should only be called when the chatroom state is ChatroomState.CONNECTED and the current user is a Role.GLOBAL_MANAGER, Role.LOCAL_MANAGER, Role.MASTER, or Role.MODERATOR.
    
    Parameters:
    
    message - the message you want to pin
    
    Returns:
    
    the task result
    
    See Also:
    
    unpinMessage(), getPinnedMessage(), EventListener.onPinnedMessageUpdated(Message)
  - unpinMessage
```
public com.google.android.gms.tasks.Task<Void> unpinMessage()
```
    Unpin the message from chatroom.
    This method should only be called when the chatroom state is ChatroomState.CONNECTED and the current user is a Role.GLOBAL_MANAGER, Role.LOCAL_MANAGER, Role.MASTER, or Role.MODERATOR.
    
    Returns:
    
    the task result
    
    See Also:
    
    pinMessage(Message), getPinnedMessage(), EventListener.onPinnedMessageUpdated(Message)
  - sendAggregatedData
```
public com.google.android.gms.tasks.Task<Void> sendAggregatedData(String message)
```
    Send a string to chatroom which will be aggregated in onAggregatedDataAdded.
    This method should only be called when the chatroom state is ChatroomState.CONNECTED.
    
    Parameters:
    
    message - A simple string, e.g. "like", "cry", should within 100 characters.
  - sendRawData
```
public com.google.android.gms.tasks.Task<Void> sendRawData(@NonNull
                                                           RawData rawData)
```
    Send the RawData to chatroom.
    This type of message will not be aggregated.
    This method should only be called when the chatroom state is ChatroomState.CONNECTED.
    
    Parameters:
    
    rawData - Use RawData.Builder to generate the JSON (RFC 7159) object
  - addFakeMessage
```
public void addFakeMessage(Message message)
```
  - getCurrentUser
```
public User getCurrentUser()
```
    Returns current user. If the chatroom state is not ChatroomState.CONNECTED, this method will return the cache of last connected user.
    
    Returns:
    
    current user.
  - getPinnedMessage
```
public Message getPinnedMessage()
```
    Returns the pinned message in current chatroom. If the chatroom state is not ChatroomState.CONNECTED, this method will return the cache of pinned message.
    
    Returns:
    
    pinned message
    
    See Also:
    
    pinMessage(Message), unpinMessage(), EventListener.onPinnedMessageUpdated(Message)
  - getSticker
```
public List<Sticker> getSticker()
```
    Returns available stickers. If the chatroom state is not ChatroomState.CONNECTED, this method will return cache of last connected chatroom's stickers.
    
    Returns:
    
    available stickers.
  - getUserCount
```
public int getUserCount()
```
    Returns current user count. If the chatroom state is not ChatroomState.CONNECTED, this method will return the cache of last connected chatroom's user count.
    
    Returns:
    
    User count.
  - getChatMode
```
public ChatMode getChatMode()
```
    Returns ChatMode. If the chatroom state is not ChatroomState.CONNECTED, this method will return the cache of last connected chatroom's ChatMode.
    
    Returns:
    
    ChatMode.
  - getSendMessageInterval
```
public int getSendMessageInterval()
```
    Returns send message interval of current chatroom. This value means the cool-down time in second that user can send message. If the chatroom state is not ChatroomState.CONNECTED, this method will return the cache of last connected chatroom's send message interval.
    
    Returns:
    
    Interval in second.
  - getChatroomState
```
public ChatroomState getChatroomState()
```
    Returns current chatroom state.
    
    Returns:
    
    ChatroomState.
  - disconnect
```
public com.google.android.gms.tasks.Task<Void> disconnect()
```
    Disconnect from current server. After disconnection finishes, EventListener.onDisconnected() that was set in connect(String, Identity) will be invoked.
    This method should only be called when the chatroom state is ChatroomState.CONNECTED or ChatroomState.CONNECTING.
  - addEventListener
```
public boolean addEventListener(EventListener listener)
```
    Parameters:
    
    listener - Listens result of connection and other events. See EventListener.
    
    Returns:
    
    return true if listener add successfully
  - addAllEventListener
```
public void addAllEventListener(EventListener... listeners)
```
    Parameters:
    
    listeners - Listens result of connection and other events. See EventListener.
  - removeEventListener
```
public boolean removeEventListener(EventListener listener)
```
    Parameters:
    
    listener - Remove listener which doesn't want to receive future event. See EventListener.
    
    Returns:
    
    return true if listener remove successfully
  - removeAllEventListener
```
public void removeAllEventListener()
```
    Remove all event listener, no one could receive future event. See EventListener.
  - getTotalAggregatedData
```
@NonNull
public androidx.collection.SimpleArrayMap<String,Integer> getTotalAggregatedData()
```
    Retrieve total aggregated data.
    
    Returns:
    
    each key-value pair represents the number of times the data string has occurred
  - setMetadata
```
public com.google.android.gms.tasks.Task<Void> setMetadata(@NonNull
                                                           String key,
                                                           @Nullable
                                                           Object value,
                                                           boolean broadcast)
```
    Sets a set of meta data to current chatroom. See Chat Metadata.
    This method should only be called when the chatroom state is ChatroomState.CONNECTED and the current user is a Role.GLOBAL_MANAGER, Role.LOCAL_MANAGER, Role.MASTER, or Role.MODERATOR.
    
    Parameters:
    
    key - Corresponds to ChatMetadata.getKey(). Note that the key is unique of metadata in a chatroom. Key names start with _ are reserved, so these names are not supposed to be used. And the key must match regular expression ^[A-Za-z0-9][A-Za-z0-9_-@#]{0,29}$.
    
    value - Corresponds to ChatMetadata.getValue(). This will be converted to JSON (RFC 7159) type and the max size is 1k when broadcast is true and 4k when parameter broadcast is false.
    
    broadcast - Sets to true to broadcast this event, it means all users in this chatroom will receive the change by EventListener.onMetadataUpdated(SimpleArrayMap).
    
    Returns:
    
    the task result
    
    See Also:
    
    getMetadata(String[]), EventListener.onMetadataUpdated(SimpleArrayMap)
  - getMetadata
```
public com.google.android.gms.tasks.Task<androidx.collection.SimpleArrayMap<String,ChatMetadata>> getMetadata(@Nullable
                                                                                                              String... keys)
```
    Gets the meta data from current chatroom. See Chat Metadata.
    This method should only be called when the chatroom state is ChatroomState.CONNECTED.
    
    Parameters:
    
    keys - The keys of meta data you want to query. Key names start with _ are reserved, so these names are not supposed to be used. And the key must match regular expression ^[A-Za-z0-9][A-Za-z0-9_-@#]{0,29}$. Sets this to null will query all meta data of current chatroom.
    
    Returns:
    
    the specified meta data if Task.isSuccessful()
    
    See Also:
    
    setMetadata(String, Object, boolean), ChatMetadata

Class ChatroomManager

Nested Class Summary

Method Summary

Methods inherited from class java.lang.Object

Method Detail

initialize

initialize

connect

resetIdentity

getMessages

getAggregatedData

getRawData

getUsers

getChatroomInfo

updateNickname

updateUserRole

updateUserRoleByMemberId

blockUsers

reviveUsers

removeMessage

sendMessage

pinMessage

unpinMessage

sendAggregatedData

sendRawData

addFakeMessage

getCurrentUser

getPinnedMessage

getSticker

getUserCount

getChatMode

getSendMessageInterval

getChatroomState

disconnect

addEventListener

addAllEventListener

removeEventListener

removeAllEventListener

getTotalAggregatedData

setMetadata

getMetadata