net.java.sip.communicator.service.protocol
Interface ChatRoom

All Known Implementing Classes:

ChatRoomIrcImpl, ChatRoomJabberImpl, MockChatRoom

public interface ChatRoom

Represents a chat channel/room/rendez-vous point/ where multiple chat users could rally and communicate in a many-to-many fashion.

Author:

Emil Ivov, Yana Stamcheva, Valentin Martinet

Method Summary

void	addLocalUserRoleListener(ChatRoomLocalUserRoleListener listener) Adds a listener that will be notified of changes in our role in the room such as us being granded operator.
void	addMemberPresenceListener(ChatRoomMemberPresenceListener listener) Adds a listener that will be notified of changes in our participation in the room such as us being kicked, join, left...
void	addMemberPropertyChangeListener(ChatRoomMemberPropertyChangeListener listener) Adds a listener that will be notified of changes in the property of a room member such as the nickname being changed.
void	addMemberRoleListener(ChatRoomMemberRoleListener listener) Adds a listener that will be notified of changes of a member role in the room such as being granded operator.
void	addMessageListener(ChatRoomMessageListener listener) Registers listener so that it would receive events every time a new message is received on this chat room.
void	addPropertyChangeListener(ChatRoomPropertyChangeListener listener) Adds a listener that will be notified of changes in the property of the room such as the subject being change or the room state being changed.
void	banParticipant(ChatRoomMember chatRoomMember, String reason) Bans a user from the room.
Message	createMessage(byte[] content, String contentType, String contentEncoding, String subject) Create a Message instance for sending arbitrary MIME-encoding content.
Message	createMessage(String messageText) Create a Message instance for sending a simple text messages with default (text/plain) content type and encoding.
Iterator<ChatRoomMember>	getBanList() Returns an Iterator over a set of ban masks for this chat room.
ChatRoomConfigurationForm	getConfigurationForm() Returns the ChatRoomConfigurationForm containing all configuration properties for this chat room.
String	getIdentifier() Returns the identifier of this ChatRoom.
List<ChatRoomMember>	getMembers() Returns a List of ChatRoomMembers corresponding to all members currently participating in this room.
int	getMembersCount() Returns the number of participants that are currently in this chat room.
String	getName() Returns the name of this ChatRoom.
ProtocolProviderService	getParentProvider() Returns a reference to the provider that created this room.
String	getSubject() Returns the last known room subject/theme or null if the user hasn't joined the room or the room does not have a subject yet.
String	getUserNickname() Returns the local user's nickname in the context of this chat room or null if not currently joined.
ChatRoomMemberRole	getUserRole() Returns the local user's role in the context of this chat room or null if not currently joined.
void	grantAdmin(String address) Grants administrator privileges to another user.
void	grantMembership(String address) Grants membership to a user.
void	grantModerator(String nickname) Grants moderator privileges to a participant or visitor.
void	grantOwnership(String address) Grants ownership privileges to another user.
void	grantVoice(String nickname) Grants voice to a visitor in the room.
void	invite(String userAddress, String reason) Invites another user to this room.
boolean	isJoined() Returns true if the local user is currently in the multi user chat (after calling one of the join() methods).
boolean	isPersistent() Determines whether this chat room should be stored in the configuration file or not.
boolean	isSystem() Returns true if this chat room is a system room and false otherwise.
void	join() Joins this chat room with the nickname of the local user so that the user would start receiving events and messages for it.
void	join(byte[] password) Joins this chat room so that the user would start receiving events and messages for it.
void	joinAs(String nickname) Joins this chat room with the specified nickname so that the user would start receiving events and messages for it.
void	joinAs(String nickname, byte[] password) Joins this chat room with the specified nickname and password so that the user would start receiving events and messages for it.
void	kickParticipant(ChatRoomMember chatRoomMember, String reason) Kicks a visitor or participant from the room.
void	leave() Leave this chat room.
void	removelocalUserRoleListener(ChatRoomLocalUserRoleListener listener) Removes a listener that was being notified of changes in our role in this chat room such as us being granded operator.
void	removeMemberPresenceListener(ChatRoomMemberPresenceListener listener) Removes a listener that was being notified of changes in the participation of other chat room participants such as users being kicked, join, left.
void	removeMemberPropertyChangeListener(ChatRoomMemberPropertyChangeListener listener) Removes a listener that was being notified of changes in the property of a chat room member such as the nickname being changed.
void	removeMemberRoleListener(ChatRoomMemberRoleListener listener) Removes a listener that was being notified of changes of a member role in this chat room such as us being granded operator.
void	removeMessageListener(ChatRoomMessageListener listener) Removes listener so that it won't receive any further message events from this room.
void	removePropertyChangeListener(ChatRoomPropertyChangeListener listener) Removes a listener that was being notified of changes in the property of the chat room such as the subject being change or the room state being changed.
void	revokeAdmin(String address) Revokes administrator privileges from a user.
void	revokeMembership(String address) Revokes a user's membership.
void	revokeModerator(String nickname) Revokes moderator privileges from another user.
void	revokeOwnership(String address) Revokes ownership privileges from another user.
void	revokeVoice(String nickname) Revokes voice from a participant in the room.
void	sendMessage(Message message) Sends the message to this chat room.
void	setLocalUserRole(ChatRoomMemberRole role) Changes the the local user's nickname in the context of this chatroom.
void	setSubject(String subject) Sets the subject of this chat room.
void	setUserNickname(String nickname) Changes the the local user's nickname in the context of this chatroom.

Method Detail

getName

String getName()

Returns the name of this ChatRoom.

Returns:

a String containing the name of this ChatRoom.

getIdentifier

String getIdentifier()

Returns the identifier of this ChatRoom. The identifier of the chat room would have the following syntax: [chatRoomName]@[chatRoomServer]@[accountID]

Returns:

a String containing the identifier of this ChatRoom.

join

void join()
          throws OperationFailedException

Joins this chat room with the nickname of the local user so that the user would start receiving events and messages for it.

Throws:

OperationFailedException - with the corresponding code if an error occurs while joining the room.

join

void join(byte[] password)
          throws OperationFailedException

Joins this chat room so that the user would start receiving events and messages for it. The method uses the nickname of the local user and the specified password in order to enter the chatroom.

Parameters:

password - the password to use when authenticating on the chatroom.

Throws:

OperationFailedException - with the corresponding code if an error occurs while joining the room.

joinAs

void joinAs(String nickname)
            throws OperationFailedException

Joins this chat room with the specified nickname so that the user would start receiving events and messages for it. If the chatroom already contains a user with this nickname, the method would throw an OperationFailedException with code IDENTIFICATION_CONFLICT.

Parameters:

nickname - the nickname to use.

Throws:

OperationFailedException - with the corresponding code if an error occurs while joining the room.

joinAs

void joinAs(String nickname,
            byte[] password)
            throws OperationFailedException

Joins this chat room with the specified nickname and password so that the user would start receiving events and messages for it. If the chatroom already contains a user with this nickname, the method would throw an OperationFailedException with code IDENTIFICATION_CONFLICT.

Parameters:

nickname - the nickname to use.

password - a password necessary to authenticate when joining the room.

Throws:

OperationFailedException - with the corresponding code if an error occurs while joining the room.

isJoined

boolean isJoined()

Returns true if the local user is currently in the multi user chat (after calling one of the join() methods).

Returns:

true if currently we're currently in this chat room and false otherwise.

leave

void leave()

Leave this chat room. Once this method is called, the user won't be listed as a member of the chat room any more and no further chat events will be delivered. Depending on the underlying protocol and implementation leave() might cause the room to be destroyed if it has been created by the local user.

getSubject

String getSubject()

Returns the last known room subject/theme or null if the user hasn't joined the room or the room does not have a subject yet.

To be notified every time the room's subject change you should add a ChatRoomChangelistener to this room. addPropertyChangeListener(ChatRoomPropertyChangeListener)

To change the room's subject use setSubject(String).

Returns:

the room subject or null if the user hasn't joined the room or the room does not have a subject yet.

setSubject

void setSubject(String subject)
                throws OperationFailedException

Sets the subject of this chat room. If the user does not have the right to change the room subject, or the protocol does not support this, or the operation fails for some other reason, the method throws an OperationFailedException with the corresponding code.

Parameters:

subject - the new subject that we'd like this room to have

Throws:

OperationFailedException - if the user doesn't have the right to change this property.

getUserNickname

String getUserNickname()

Returns the local user's nickname in the context of this chat room or null if not currently joined.

Returns:

the nickname currently being used by the local user in the context of the local chat room.

getUserRole

ChatRoomMemberRole getUserRole()

Returns the local user's role in the context of this chat room or null if not currently joined.

Returns:

the role currently being used by the local user in the context of the chat room.

setLocalUserRole

void setLocalUserRole(ChatRoomMemberRole role)
                      throws OperationFailedException

Changes the the local user's nickname in the context of this chatroom.

Parameters:

role - the new role to set for the local user.

Throws:

OperationFailedException - if an error occurs.

setUserNickname

void setUserNickname(String nickname)
                     throws OperationFailedException

Changes the the local user's nickname in the context of this chatroom.

Parameters:

nickname - the new nickname within the room.

Throws:

OperationFailedException - if the new nickname already exist in this room

addMemberPresenceListener

void addMemberPresenceListener(ChatRoomMemberPresenceListener listener)

Adds a listener that will be notified of changes in our participation in the room such as us being kicked, join, left...

Parameters:

listener - a member participation listener.

removeMemberPresenceListener

void removeMemberPresenceListener(ChatRoomMemberPresenceListener listener)

Removes a listener that was being notified of changes in the participation of other chat room participants such as users being kicked, join, left.

Parameters:

listener - a member participation listener.

addLocalUserRoleListener

void addLocalUserRoleListener(ChatRoomLocalUserRoleListener listener)

Adds a listener that will be notified of changes in our role in the room such as us being granded operator.

Parameters:

listener - a local user role listener.

removelocalUserRoleListener

void removelocalUserRoleListener(ChatRoomLocalUserRoleListener listener)

Removes a listener that was being notified of changes in our role in this chat room such as us being granded operator.

Parameters:

listener - a local user role listener.

addMemberRoleListener

void addMemberRoleListener(ChatRoomMemberRoleListener listener)

Adds a listener that will be notified of changes of a member role in the room such as being granded operator.

Parameters:

listener - a member role listener.

removeMemberRoleListener

void removeMemberRoleListener(ChatRoomMemberRoleListener listener)

Removes a listener that was being notified of changes of a member role in this chat room such as us being granded operator.

Parameters:

listener - a member role listener.

addPropertyChangeListener

void addPropertyChangeListener(ChatRoomPropertyChangeListener listener)

Adds a listener that will be notified of changes in the property of the room such as the subject being change or the room state being changed.

Parameters:

listener - a property change listener.

removePropertyChangeListener

void removePropertyChangeListener(ChatRoomPropertyChangeListener listener)

Removes a listener that was being notified of changes in the property of the chat room such as the subject being change or the room state being changed.

Parameters:

listener - a property change listener.

addMemberPropertyChangeListener

void addMemberPropertyChangeListener(ChatRoomMemberPropertyChangeListener listener)

Adds a listener that will be notified of changes in the property of a room member such as the nickname being changed.

Parameters:

listener - a room member property change listener.

removeMemberPropertyChangeListener

void removeMemberPropertyChangeListener(ChatRoomMemberPropertyChangeListener listener)

Removes a listener that was being notified of changes in the property of a chat room member such as the nickname being changed.

Parameters:

listener - a room member property change listener.

invite

void invite(String userAddress,
            String reason)

Invites another user to this room.

If the room is password-protected, the invitee will receive a password to use to join the room. If the room is members-only, the the invitee may be added to the member list.

Parameters:

userAddress - the address of the user to invite to the room.(one may also invite users not on their contact list).

reason - a reason, subject, or welcome message that would tell the the user why they are being invited.

getMembers

List<ChatRoomMember> getMembers()

Returns a List of ChatRoomMembers corresponding to all members currently participating in this room.

Returns:

a List of ChatRoomMember instances corresponding to all room members.

getMembersCount

int getMembersCount()

Returns the number of participants that are currently in this chat room.

Returns:

the number of Contacts, currently participating in this room.

addMessageListener

void addMessageListener(ChatRoomMessageListener listener)

Registers listener so that it would receive events every time a new message is received on this chat room.

Parameters:

listener - a MessageListener that would be notified every time a new message is received on this chat room.

removeMessageListener

void removeMessageListener(ChatRoomMessageListener listener)

Removes listener so that it won't receive any further message events from this room.

Parameters:

listener - the MessageListener to remove from this room

createMessage

Message createMessage(byte[] content,
                      String contentType,
                      String contentEncoding,
                      String subject)

Create a Message instance for sending arbitrary MIME-encoding content.

Parameters:

content - content value

contentType - the MIME-type for content

contentEncoding - encoding used for content

subject - a String subject or null for now subject.

Returns:

the newly created message.

createMessage

Message createMessage(String messageText)

Create a Message instance for sending a simple text messages with default (text/plain) content type and encoding.

Parameters:

messageText - the string content of the message.

Returns:

Message the newly created message

sendMessage

void sendMessage(Message message)
                 throws OperationFailedException

Sends the message to this chat room.

Parameters:

message - the Message to send.

Throws:

OperationFailedException - if sending the message fails for some reason.

getParentProvider

ProtocolProviderService getParentProvider()

Returns a reference to the provider that created this room.

Returns:

a reference to the ProtocolProviderService instance that created this room.

getBanList

Iterator<ChatRoomMember> getBanList()
                                    throws OperationFailedException

Returns an Iterator over a set of ban masks for this chat room. The ban mask defines a group of users that will be banned. The ban list is a list of all such ban masks defined for this chat room.

Returns:

an Iterator over a set of ban masks for this chat room

Throws:

OperationFailedException - if an error occured while performing the request to the server or you don't have enough privileges to get this information

banParticipant

void banParticipant(ChatRoomMember chatRoomMember,
                    String reason)
                    throws OperationFailedException

Bans a user from the room. An administrator or owner of the room can ban users from a room. A banned user will no longer be able to join the room unless the ban has been removed. If the banned user was present in the room then he/she will be removed from the room and notified that he/she was banned along with the reason (if provided) and the user who initiated the ban.

Parameters:

chatRoomMember - the ChatRoomMember to be banned.

reason - the reason why the user was banned.

Throws:

OperationFailedException - if an error occurs while banning a user. In particular, an error can occur if a moderator or a user with an affiliation of "owner" or "admin" was tried to be banned or if the user that is banning have not enough permissions to ban.

kickParticipant

void kickParticipant(ChatRoomMember chatRoomMember,
                     String reason)
                     throws OperationFailedException

Kicks a visitor or participant from the room.

Parameters:

chatRoomMember - the ChatRoomMember to kick from the room

reason - the reason why the participant is being kicked from the room

Throws:

OperationFailedException - if an error occurs while kicking the participant. In particular, an error can occur if a moderator or a user with an affiliation of "owner" or "administrator" was intended to be kicked; or if the participant that intended to kick another participant does not have kicking privileges;

getConfigurationForm

ChatRoomConfigurationForm getConfigurationForm()
                                               throws OperationFailedException

Returns the ChatRoomConfigurationForm containing all configuration properties for this chat room. If the user doesn't have permissions to see and change chat room configuration an OperationFailedException is thrown.

Returns:

the ChatRoomConfigurationForm containing all configuration properties for this chat room

Throws:

OperationFailedException - if the user doesn't have permissions to see and change chat room configuration

isSystem

boolean isSystem()

Returns true if this chat room is a system room and false otherwise.

Returns:

true if this chat room is a system room and false otherwise.

isPersistent

boolean isPersistent()

Determines whether this chat room should be stored in the configuration file or not. If the chat room is persistent it still will be shown after a restart in the chat room list. A non-persistent chat room will be only in the chat room list until the the program is running.

Returns:

true if this chat room is persistent, false otherwise

grantAdmin

void grantAdmin(String address)

Grants administrator privileges to another user. Room owners may grant administrator privileges to a member or unaffiliated user. An administrator is allowed to perform administrative functions such as banning users and edit moderator list.

Parameters:

address - the user address of the user to grant administrator privileges (e.g. "user@host.org").

grantMembership

void grantMembership(String address)

Grants membership to a user. Only administrators are able to grant membership. A user that becomes a room member will be able to enter a room of type Members-Only (i.e. a room that a user cannot enter without being on the member list).

Parameters:

address - the user address of the user to grant membership privileges (e.g. "user@host.org").

grantModerator

void grantModerator(String nickname)

Grants moderator privileges to a participant or visitor. Room administrators may grant moderator privileges. A moderator is allowed to kick users, grant and revoke voice, invite other users, modify room's subject plus all the partcipants privileges.

Parameters:

nickname - the nickname of the occupant to grant moderator privileges.

grantOwnership

void grantOwnership(String address)

Grants ownership privileges to another user. Room owners may grant ownership privileges. Some room implementations will not allow to grant ownership privileges to other users. An owner is allowed to change defining room features as well as perform all administrative functions.

Parameters:

address - the user address of the user to grant ownership privileges (e.g. "user@host.org").

grantVoice

void grantVoice(String nickname)

Grants voice to a visitor in the room. In a moderated room, a moderator may want to manage who does and does not have "voice" in the room. To have voice means that a room occupant is able to send messages to the room occupants.

Parameters:

nickname - the nickname of the visitor to grant voice in the room (e.g. "john").

revokeAdmin

void revokeAdmin(String address)

Revokes administrator privileges from a user. The occupant that loses administrator privileges will become a member. Room owners may revoke administrator privileges from a member or unaffiliated user.

Parameters:

address - the user address of the user to grant administrator privileges (e.g. "user@host.org").

revokeMembership

void revokeMembership(String address)

Revokes a user's membership. Only administrators are able to revoke membership. A user that becomes a room member will be able to enter a room of type Members-Only (i.e. a room that a user cannot enter without being on the member list). If the user is in the room and the room is of type members-only then the user will be removed from the room.

Parameters:

address - the user address of the user to revoke membership (e.g. "user@host.org").

revokeModerator

void revokeModerator(String nickname)

Revokes moderator privileges from another user. The occupant that loses moderator privileges will become a participant. Room administrators may revoke moderator privileges only to occupants whose affiliation is member or none. This means that an administrator is not allowed to revoke moderator privileges from other room administrators or owners.

Parameters:

nickname - the nickname of the occupant to revoke moderator privileges.

revokeOwnership

void revokeOwnership(String address)

Revokes ownership privileges from another user. The occupant that loses ownership privileges will become an administrator. Room owners may revoke ownership privileges. Some room implementations will not allow to grant ownership privileges to other users.

Parameters:

address - the user address of the user to revoke ownership (e.g. "user@host.org").

revokeVoice

void revokeVoice(String nickname)

Revokes voice from a participant in the room. In a moderated room, a moderator may want to revoke an occupant's privileges to speak. To have voice means that a room occupant is able to send messages to the room occupants.

Parameters:

nickname - the nickname of the participant to revoke voice (e.g. "john").