org.jivesoftware.smackx.muc
Class MultiUserChat

java.lang.Object
  org.jivesoftware.smackx.muc.MultiUserChat

public class MultiUserChat
extends Object

A MultiUserChat is a conversation that takes place among many users in a virtual room. A room could have many occupants with different affiliation and roles. Possible affiliatons are "owner", "admin", "member", and "outcast". Possible roles are "moderator", "participant", and "visitor". Each role and affiliation guarantees different privileges (e.g. Send messages to all occupants, Kick participants and visitors, Grant voice, Edit member list, etc.).

Author:

Gaston Dombiak, Larry Kirschner

Constructor Summary

MultiUserChat(XMPPConnection connection, String room)
Creates a new multi user chat with the specified connection and room name.

Method Summary

static void	addInvitationListener(XMPPConnection conn, InvitationListener listener) Adds a listener to invitation notifications.
void	addInvitationRejectionListener(InvitationRejectionListener listener) Adds a listener to invitation rejections notifications.
void	addMessageListener(PacketListener listener) Adds a packet listener that will be notified of any new messages in the group chat.
void	addParticipantListener(PacketListener listener) Adds a packet listener that will be notified of any new Presence packets sent to the group chat.
void	addParticipantStatusListener(ParticipantStatusListener listener) Adds a listener that will be notified of changes in occupants status in the room such as the user being kicked, banned, or granted admin permissions.
void	addPresenceInterceptor(PacketInterceptor presenceInterceptor) Adds a new PacketInterceptor that will be invoked every time a new presence is going to be sent by this MultiUserChat to the server.
void	addSubjectUpdatedListener(SubjectUpdatedListener listener) Adds a listener to subject change notifications.
void	addUserStatusListener(UserStatusListener listener) Adds a listener that will be notified of changes in your status in the room such as the user being kicked, banned, or granted admin permissions.
void	banUser(String jid, String reason) Bans a user from the room.
void	banUsers(Collection<String> jids) Bans users from the room.
void	changeAvailabilityStatus(String status, Presence.Mode mode) Changes the occupant's availability status within the room.
void	changeNickname(String nickname) Changes the occupant's nickname to a new nickname within the room.
void	changeSubject(String subject) Changes the subject within the room.
void	create(String nickname) Creates the room according to some default configuration, assign the requesting user as the room owner, and add the owner to the room but not allow anyone else to enter the room (effectively "locking" the room).
Message	createMessage() Creates a new Message to send to the chat room.
Chat	createPrivateChat(String occupant, MessageListener listener) Returns a new Chat for sending private messages to a given room occupant.
static void	decline(XMPPConnection conn, String room, String inviter, String reason) Informs the sender of an invitation that the invitee declines the invitation.
void	destroy(String reason, String alternateJID) Sends a request to the server to destroy the room.
void	finalize()
Collection<Affiliate>	getAdmins() Returns a collection of Affiliate with the room administrators.
Form	getConfigurationForm() Returns the room's configuration form that the room's owner can use or null if no configuration is possible.
static Collection<HostedRoom>	getHostedRooms(XMPPConnection connection, String serviceName) Returns a collection of HostedRooms where each HostedRoom has the XMPP address of the room and the room's name.
static Iterator<String>	getJoinedRooms(XMPPConnection connection, String user) Returns an Iterator on the rooms where the requested user has joined.
Collection<Affiliate>	getMembers() Returns a collection of Affiliate with the room members.
Collection<Occupant>	getModerators() Returns a collection of Occupant with the room moderators.
String	getNickname() Returns the nickname that was used to join the room, or null if not currently joined.
Occupant	getOccupant(String user) Returns the Occupant information for a particular occupant, or null if the user is not in the room.
Presence	getOccupantPresence(String user) Returns the presence info for a particular user, or null if the user is not in the room.
Iterator<String>	getOccupants() Returns an Iterator (of Strings) for the list of fully qualified occupants in the group chat.
int	getOccupantsCount() Returns the number of occupants in the group chat.
Collection<Affiliate>	getOutcasts() Returns a collection of Affiliate with the room outcasts.
Collection<Affiliate>	getOwners() Returns a collection of Affiliate with the room owners.
Collection<Occupant>	getParticipants() Returns a collection of Occupant with the room participants.
Form	getRegistrationForm() Returns the room's registration form that an unaffiliated user, can use to become a member of the room or null if no registration is possible.
String	getReservedNickname() Returns the reserved room nickname for the user in the room.
String	getRoom() Returns the name of the room this MultiUserChat object represents.
static RoomInfo	getRoomInfo(XMPPConnection connection, String room) Returns the discovered information of a given room without actually having to join the room.
static Collection<String>	getServiceNames(XMPPConnection connection) Returns a collection with the XMPP addresses of the Multi-User Chat services.
String	getSubject() Returns the last known room's subject or null if the user hasn't joined the room or the room does not have a subject yet.
void	grantAdmin(Collection<String> jids) Grants administrator privileges to other users.
void	grantAdmin(String jid) Grants administrator privileges to another user.
void	grantMembership(Collection<String> jids) Grants membership to other users.
void	grantMembership(String jid) Grants membership to a user.
void	grantModerator(Collection<String> nicknames) Grants moderator privileges to participants or visitors.
void	grantModerator(String nickname) Grants moderator privileges to a participant or visitor.
void	grantOwnership(Collection<String> jids) Grants ownership privileges to other users.
void	grantOwnership(String jid) Grants ownership privileges to another user.
void	grantVoice(Collection<String> nicknames) Grants voice to visitors in the room.
void	grantVoice(String nickname) Grants voice to a visitor in the room.
void	invite(Message message, String user, String reason) Invites another user to the room in which one is an occupant using a given Message.
void	invite(String user, String reason) Invites another user to the room in which one is an occupant.
boolean	isJoined() Returns true if currently in the multi user chat (after calling the join(String) method).
static boolean	isServiceEnabled(XMPPConnection connection, String user) Returns true if the specified user supports the Multi-User Chat protocol.
void	join(String nickname) Joins the chat room using the specified nickname.
void	join(String nickname, String password) Joins the chat room using the specified nickname and password.
void	join(String nickname, String password, DiscussionHistory history, long timeout) Joins the chat room using the specified nickname and password.
void	kickParticipant(String nickname, String reason) Kicks a visitor or participant from the room.
void	leave() Leave the chat room.
Message	nextMessage() Returns the next available message in the chat.
Message	nextMessage(long timeout) Returns the next available message in the chat.
Message	pollMessage() Polls for and returns the next message, or null if there isn't a message immediately available.
static void	removeInvitationListener(XMPPConnection conn, InvitationListener listener) Removes a listener to invitation notifications.
void	removeInvitationRejectionListener(InvitationRejectionListener listener) Removes a listener from invitation rejections notifications.
void	removeMessageListener(PacketListener listener) Removes a packet listener that was being notified of any new messages in the multi user chat.
void	removeParticipantListener(PacketListener listener) Remoces a packet listener that was being notified of any new Presence packets sent to the group chat.
void	removeParticipantStatusListener(ParticipantStatusListener listener) Removes a listener that was being notified of changes in occupants status in the room such as the user being kicked, banned, or granted admin permissions.
void	removePresenceInterceptor(PacketInterceptor presenceInterceptor) Removes a PacketInterceptor that was being invoked every time a new presence was being sent by this MultiUserChat to the server.
void	removeSubjectUpdatedListener(SubjectUpdatedListener listener) Removes a listener from subject change notifications.
void	removeUserStatusListener(UserStatusListener listener) Removes a listener that was being notified of changes in your status in the room such as the user being kicked, banned, or granted admin permissions.
void	revokeAdmin(Collection<String> jids) Revokes administrator privileges from users.
void	revokeAdmin(String jid) Revokes administrator privileges from a user.
void	revokeMembership(Collection<String> jids) Revokes users' membership.
void	revokeMembership(String jid) Revokes a user's membership.
void	revokeModerator(Collection<String> nicknames) Revokes moderator privileges from other users.
void	revokeModerator(String nickname) Revokes moderator privileges from another user.
void	revokeOwnership(Collection<String> jids) Revokes ownership privileges from other users.
void	revokeOwnership(String jid) Revokes ownership privileges from another user.
void	revokeVoice(Collection<String> nicknames) Revokes voice from participants in the room.
void	revokeVoice(String nickname) Revokes voice from a participant in the room.
void	sendConfigurationForm(Form form) Sends the completed configuration form to the server.
void	sendMessage(Message message) Sends a Message to the chat room.
void	sendMessage(String text) Sends a message to the chat room.
void	sendRegistrationForm(Form form) Sends the completed registration form to the server.

Methods inherited from class java.lang.Object

clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

MultiUserChat

public MultiUserChat(XMPPConnection connection,
                     String room)

Creates a new multi user chat with the specified connection and room name. Note: no information is sent to or received from the server until you attempt to join the chat room. On some server implementations, the room will not be created until the first person joins it.

Most XMPP servers use a sub-domain for the chat service (eg chat.example.com for the XMPP server example.com). You must ensure that the room address you're trying to connect to includes the proper chat sub-domain.

Parameters:

connection - the XMPP connection.

room - the name of the room in the form "roomName@service", where "service" is the hostname at which the multi-user chat service is running. Make sure to provide a valid JID.

Method Detail

isServiceEnabled

public static boolean isServiceEnabled(XMPPConnection connection,
                                       String user)

Returns true if the specified user supports the Multi-User Chat protocol.

Parameters:

connection - the connection to use to perform the service discovery.

user - the user to check. A fully qualified xmpp ID, e.g. jdoe@example.com.

Returns:

a boolean indicating whether the specified user supports the MUC protocol.

getJoinedRooms

public static Iterator<String> getJoinedRooms(XMPPConnection connection,
                                              String user)

Returns an Iterator on the rooms where the requested user has joined. The Iterator will contain Strings where each String represents a room (e.g. room@muc.jabber.org).

Parameters:

connection - the connection to use to perform the service discovery.

user - the user to check. A fully qualified xmpp ID, e.g. jdoe@example.com.

Returns:

an Iterator on the rooms where the requested user has joined.

getRoomInfo

public static RoomInfo getRoomInfo(XMPPConnection connection,
                                   String room)
                            throws XMPPException

Returns the discovered information of a given room without actually having to join the room. The server will provide information only for rooms that are public.

Parameters:

connection - the XMPP connection to use for discovering information about the room.

room - the name of the room in the form "roomName@service" of which we want to discover its information.

Returns:

the discovered information of a given room without actually having to join the room.

Throws:

XMPPException - if an error occured while trying to discover information of a room.

getServiceNames

public static Collection<String> getServiceNames(XMPPConnection connection)
                                          throws XMPPException

Returns a collection with the XMPP addresses of the Multi-User Chat services.

Parameters:

connection - the XMPP connection to use for discovering Multi-User Chat services.

Returns:

a collection with the XMPP addresses of the Multi-User Chat services.

Throws:

XMPPException - if an error occured while trying to discover MUC services.

getHostedRooms

public static Collection<HostedRoom> getHostedRooms(XMPPConnection connection,
                                                    String serviceName)
                                             throws XMPPException

Returns a collection of HostedRooms where each HostedRoom has the XMPP address of the room and the room's name. Once discovered the rooms hosted by a chat service it is possible to discover more detailed room information or join the room.

Parameters:

connection - the XMPP connection to use for discovering hosted rooms by the MUC service.

serviceName - the service that is hosting the rooms to discover.

Returns:

a collection of HostedRooms.

Throws:

XMPPException - if an error occured while trying to discover the information.

getRoom

public String getRoom()

Returns the name of the room this MultiUserChat object represents.

Returns:

the multi user chat room name.

create

public void create(String nickname)
            throws XMPPException

Creates the room according to some default configuration, assign the requesting user as the room owner, and add the owner to the room but not allow anyone else to enter the room (effectively "locking" the room). The requesting user will join the room under the specified nickname as soon as the room has been created.

To create an "Instant Room", that means a room with some default configuration that is available for immediate access, the room's owner should send an empty form after creating the room. sendConfigurationForm(Form)

To create a "Reserved Room", that means a room manually configured by the room creator before anyone is allowed to enter, the room's owner should complete and send a form after creating the room. Once the completed configutation form is sent to the server, the server will unlock the room. sendConfigurationForm(Form)

Parameters:

nickname - the nickname to use.

Throws:

XMPPException - if the room couldn't be created for some reason (e.g. room already exists; user already joined to an existant room or 405 error if the user is not allowed to create the room)

join

public void join(String nickname)
          throws XMPPException

Joins the chat room using the specified nickname. If already joined using another nickname, this method will first leave the room and then re-join using the new nickname. The default timeout of Smack for a reply from the group chat server that the join succeeded will be used. After joining the room, the room will decide the amount of history to send.

Parameters:

nickname - the nickname to use.

Throws:

XMPPException - if an error occurs joining the room. In particular, a 401 error can occur if no password was provided and one is required; or a 403 error can occur if the user is banned; or a 404 error can occur if the room does not exist or is locked; or a 407 error can occur if user is not on the member list; or a 409 error can occur if someone is already in the group chat with the same nickname.

join

public void join(String nickname,
                 String password)
          throws XMPPException

Joins the chat room using the specified nickname and password. If already joined using another nickname, this method will first leave the room and then re-join using the new nickname. The default timeout of Smack for a reply from the group chat server that the join succeeded will be used. After joining the room, the room will decide the amount of history to send.

A password is required when joining password protected rooms. If the room does not require a password there is no need to provide one.

Parameters:

nickname - the nickname to use.

password - the password to use.

Throws:

XMPPException - if an error occurs joining the room. In particular, a 401 error can occur if no password was provided and one is required; or a 403 error can occur if the user is banned; or a 404 error can occur if the room does not exist or is locked; or a 407 error can occur if user is not on the member list; or a 409 error can occur if someone is already in the group chat with the same nickname.

join

public void join(String nickname,
                 String password,
                 DiscussionHistory history,
                 long timeout)
          throws XMPPException

Joins the chat room using the specified nickname and password. If already joined using another nickname, this method will first leave the room and then re-join using the new nickname.

To control the amount of history to receive while joining a room you will need to provide a configured DiscussionHistory object.

A password is required when joining password protected rooms. If the room does not require a password there is no need to provide one.

If the room does not already exist when the user seeks to enter it, the server will decide to create a new room or not.

Parameters:

nickname - the nickname to use.

password - the password to use.

history - the amount of discussion history to receive while joining a room.

timeout - the amount of time to wait for a reply from the MUC service(in milleseconds).

Throws:

XMPPException - if an error occurs joining the room. In particular, a 401 error can occur if no password was provided and one is required; or a 403 error can occur if the user is banned; or a 404 error can occur if the room does not exist or is locked; or a 407 error can occur if user is not on the member list; or a 409 error can occur if someone is already in the group chat with the same nickname.

isJoined

public boolean isJoined()

Returns true if currently in the multi user chat (after calling the join(String) method).

Returns:

true if currently in the multi user chat room.

leave

public void leave()

Leave the chat room.

getConfigurationForm

public Form getConfigurationForm()
                          throws XMPPException

Returns the room's configuration form that the room's owner can use or null if no configuration is possible. The configuration form allows to set the room's language, enable logging, specify room's type, etc..

Returns:

the Form that contains the fields to complete together with the instrucions or null if no configuration is possible.

Throws:

XMPPException - if an error occurs asking the configuration form for the room.

sendConfigurationForm

public void sendConfigurationForm(Form form)
                           throws XMPPException

Sends the completed configuration form to the server. The room will be configured with the new settings defined in the form. If the form is empty then the server will create an instant room (will use default configuration).

Parameters:

form - the form with the new settings.

Throws:

XMPPException - if an error occurs setting the new rooms' configuration.

getRegistrationForm

public Form getRegistrationForm()
                         throws XMPPException

Returns the room's registration form that an unaffiliated user, can use to become a member of the room or null if no registration is possible. Some rooms may restrict the privilege to register members and allow only room admins to add new members.

If the user requesting registration requirements is not allowed to register with the room (e.g. because that privilege has been restricted), the room will return a "Not Allowed" error to the user (error code 405).

Returns:

the registration Form that contains the fields to complete together with the instrucions or null if no registration is possible.

Throws:

XMPPException - if an error occurs asking the registration form for the room or a 405 error if the user is not allowed to register with the room.

sendRegistrationForm

public void sendRegistrationForm(Form form)
                          throws XMPPException

Sends the completed registration form to the server. After the user successfully submits the form, the room may queue the request for review by the room admins or may immediately add the user to the member list by changing the user's affiliation from "none" to "member.

If the desired room nickname is already reserved for that room, the room will return a "Conflict" error to the user (error code 409). If the room does not support registration, it will return a "Service Unavailable" error to the user (error code 503).

Parameters:

form - the completed registration form.

Throws:

XMPPException - if an error occurs submitting the registration form. In particular, a 409 error can occur if the desired room nickname is already reserved for that room; or a 503 error can occur if the room does not support registration.

destroy

public void destroy(String reason,
                    String alternateJID)
             throws XMPPException

Sends a request to the server to destroy the room. The sender of the request should be the room's owner. If the sender of the destroy request is not the room's owner then the server will answer a "Forbidden" error (403).

Parameters:

reason - the reason for the room destruction.

alternateJID - the JID of an alternate location.

Throws:

XMPPException - if an error occurs while trying to destroy the room. An error can occur which will be wrapped by an XMPPException -- XMPP error code 403. The error code can be used to present more appropiate error messages to end-users.

invite

public void invite(String user,
                   String reason)

Invites another user to the room in which one is an occupant. The invitation will be sent to the room which in turn will forward the invitation to the invitee.

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:

user - the user to invite to the room.(e.g. hecate@shakespeare.lit)

reason - the reason why the user is being invited.

invite

public void invite(Message message,
                   String user,
                   String reason)

Invites another user to the room in which one is an occupant using a given Message. The invitation will be sent to the room which in turn will forward the invitation to the invitee.

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:

message - the message to use for sending the invitation.

user - the user to invite to the room.(e.g. hecate@shakespeare.lit)

reason - the reason why the user is being invited.

decline

public static void decline(XMPPConnection conn,
                           String room,
                           String inviter,
                           String reason)

Informs the sender of an invitation that the invitee declines the invitation. The rejection will be sent to the room which in turn will forward the rejection to the inviter.

Parameters:

conn - the connection to use for sending the rejection.

room - the room that sent the original invitation.

inviter - the inviter of the declined invitation.

reason - the reason why the invitee is declining the invitation.

addInvitationListener

public static void addInvitationListener(XMPPConnection conn,
                                         InvitationListener listener)

Adds a listener to invitation notifications. The listener will be fired anytime an invitation is received.

Parameters:

conn - the connection where the listener will be applied.

listener - an invitation listener.

removeInvitationListener

public static void removeInvitationListener(XMPPConnection conn,
                                            InvitationListener listener)

Removes a listener to invitation notifications. The listener will be fired anytime an invitation is received.

Parameters:

conn - the connection where the listener was applied.

listener - an invitation listener.

addInvitationRejectionListener

public void addInvitationRejectionListener(InvitationRejectionListener listener)

Adds a listener to invitation rejections notifications. The listener will be fired anytime an invitation is declined.

Parameters:

listener - an invitation rejection listener.

removeInvitationRejectionListener

public void removeInvitationRejectionListener(InvitationRejectionListener listener)

Removes a listener from invitation rejections notifications. The listener will be fired anytime an invitation is declined.

Parameters:

listener - an invitation rejection listener.

addSubjectUpdatedListener

public void addSubjectUpdatedListener(SubjectUpdatedListener listener)

Adds a listener to subject change notifications. The listener will be fired anytime the room's subject changes.

Parameters:

listener - a subject updated listener.

removeSubjectUpdatedListener

public void removeSubjectUpdatedListener(SubjectUpdatedListener listener)

Removes a listener from subject change notifications. The listener will be fired anytime the room's subject changes.

Parameters:

listener - a subject updated listener.

addPresenceInterceptor

public void addPresenceInterceptor(PacketInterceptor presenceInterceptor)

Adds a new PacketInterceptor that will be invoked every time a new presence is going to be sent by this MultiUserChat to the server. Packet interceptors may add new extensions to the presence that is going to be sent to the MUC service.

Parameters:

presenceInterceptor - the new packet interceptor that will intercept presence packets.

removePresenceInterceptor

public void removePresenceInterceptor(PacketInterceptor presenceInterceptor)

Removes a PacketInterceptor that was being invoked every time a new presence was being sent by this MultiUserChat to the server. Packet interceptors may add new extensions to the presence that is going to be sent to the MUC service.

Parameters:

presenceInterceptor - the packet interceptor to remove.

getSubject

public String getSubject()

Returns the last known room's subject or null if the user hasn't joined the room or the room does not have a subject yet. In case the room has a subject, as soon as the user joins the room a message with the current room's subject will be received.

To be notified every time the room's subject change you should add a listener to this room. addSubjectUpdatedListener(SubjectUpdatedListener)

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

Returns:

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

getReservedNickname

public String getReservedNickname()

Returns the reserved room nickname for the user in the room. A user may have a reserved nickname, for example through explicit room registration or database integration. In such cases it may be desirable for the user to discover the reserved nickname before attempting to enter the room.

Returns:

the reserved room nickname or null if none.

getNickname

public String getNickname()

Returns the nickname that was used to join the room, or null if not currently joined.

Returns:

the nickname currently being used.

changeNickname

public void changeNickname(String nickname)
                    throws XMPPException

Changes the occupant's nickname to a new nickname within the room. Each room occupant will receive two presence packets. One of type "unavailable" for the old nickname and one indicating availability for the new nickname. The unavailable presence will contain the new nickname and an appropriate status code (namely 303) as extended presence information. The status code 303 indicates that the occupant is changing his/her nickname.

Parameters:

nickname - the new nickname within the room.

Throws:

XMPPException - if the new nickname is already in use by another occupant.

changeAvailabilityStatus

public void changeAvailabilityStatus(String status,
                                     Presence.Mode mode)

Changes the occupant's availability status within the room. The presence type will remain available but with a new status that describes the presence update and a new presence mode (e.g. Extended away).

Parameters:

status - a text message describing the presence update.

mode - the mode type for the presence update.

kickParticipant

public void kickParticipant(String nickname,
                            String reason)
                     throws XMPPException

Kicks a visitor or participant from the room. The kicked occupant will receive a presence of type "unavailable" including a status code 307 and optionally along with the reason (if provided) and the bare JID of the user who initiated the kick. After the occupant was kicked from the room, the rest of the occupants will receive a presence of type "unavailable". The presence will include a status code 307 which means that the occupant was kicked from the room.

Parameters:

nickname - the nickname of the participant or visitor to kick from the room (e.g. "john").

reason - the reason why the participant or visitor is being kicked from the room.

Throws:

XMPPException - if an error occurs kicking the occupant. In particular, a 405 error can occur if a moderator or a user with an affiliation of "owner" or "admin" was intended to be kicked (i.e. Not Allowed error); or a 403 error can occur if the occupant that intended to kick another occupant does not have kicking privileges (i.e. Forbidden error); or a 400 error can occur if the provided nickname is not present in the room.

grantVoice

public void grantVoice(Collection<String> nicknames)
                throws XMPPException

Grants voice to visitors 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:

nicknames - the nicknames of the visitors to grant voice in the room (e.g. "john").

Throws:

XMPPException - if an error occurs granting voice to a visitor. In particular, a 403 error can occur if the occupant that intended to grant voice is not a moderator in this room (i.e. Forbidden error); or a 400 error can occur if the provided nickname is not present in the room.

grantVoice

public void grantVoice(String nickname)
                throws XMPPException

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").

Throws:

XMPPException - if an error occurs granting voice to a visitor. In particular, a 403 error can occur if the occupant that intended to grant voice is not a moderator in this room (i.e. Forbidden error); or a 400 error can occur if the provided nickname is not present in the room.

revokeVoice

public void revokeVoice(Collection<String> nicknames)
                 throws XMPPException

Revokes voice from participants 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:

nicknames - the nicknames of the participants to revoke voice (e.g. "john").

Throws:

XMPPException - if an error occurs revoking voice from a participant. In particular, a 405 error can occur if a moderator or a user with an affiliation of "owner" or "admin" was tried to revoke his voice (i.e. Not Allowed error); or a 400 error can occur if the provided nickname is not present in the room.

revokeVoice

public void revokeVoice(String nickname)
                 throws XMPPException

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").

Throws:

XMPPException - if an error occurs revoking voice from a participant. In particular, a 405 error can occur if a moderator or a user with an affiliation of "owner" or "admin" was tried to revoke his voice (i.e. Not Allowed error); or a 400 error can occur if the provided nickname is not present in the room.

banUsers

public void banUsers(Collection<String> jids)
              throws XMPPException

Bans users from the room. An admin or owner of the room can ban users from a room. This means that the 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 bare XMPP user ID of the user who initiated the ban.

Parameters:

jids - the bare XMPP user IDs of the users to ban.

Throws:

XMPPException - if an error occurs banning a user. In particular, a 405 error can occur if a moderator or a user with an affiliation of "owner" or "admin" was tried to be banned (i.e. Not Allowed error).

banUser

public void banUser(String jid,
                    String reason)
             throws XMPPException

Bans a user from the room. An admin or owner of the room can ban users from a room. This means that the 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 bare XMPP user ID of the user who initiated the ban.

Parameters:

jid - the bare XMPP user ID of the user to ban (e.g. "user@host.org").

reason - the reason why the user was banned.

Throws:

XMPPException - if an error occurs banning a user. In particular, a 405 error can occur if a moderator or a user with an affiliation of "owner" or "admin" was tried to be banned (i.e. Not Allowed error).

grantMembership

public void grantMembership(Collection<String> jids)
                     throws XMPPException

Grants membership to other users. 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:

jids - the XMPP user IDs of the users to grant membership.

Throws:

XMPPException - if an error occurs granting membership to a user.

grantMembership

public void grantMembership(String jid)
                     throws XMPPException

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:

jid - the XMPP user ID of the user to grant membership (e.g. "user@host.org").

Throws:

XMPPException - if an error occurs granting membership to a user.

revokeMembership

public void revokeMembership(Collection<String> jids)
                      throws XMPPException

Revokes users' 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:

jids - the bare XMPP user IDs of the users to revoke membership.

Throws:

XMPPException - if an error occurs revoking membership to a user.

revokeMembership

public void revokeMembership(String jid)
                      throws XMPPException

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:

jid - the bare XMPP user ID of the user to revoke membership (e.g. "user@host.org").

Throws:

XMPPException - if an error occurs revoking membership to a user.

grantModerator

public void grantModerator(Collection<String> nicknames)
                    throws XMPPException

Grants moderator privileges to participants or visitors. 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:

nicknames - the nicknames of the occupants to grant moderator privileges.

Throws:

XMPPException - if an error occurs granting moderator privileges to a user.

grantModerator

public void grantModerator(String nickname)
                    throws XMPPException

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.

Throws:

XMPPException - if an error occurs granting moderator privileges to a user.

revokeModerator

public void revokeModerator(Collection<String> nicknames)
                     throws XMPPException

Revokes moderator privileges from other users. 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:

nicknames - the nicknames of the occupants to revoke moderator privileges.

Throws:

XMPPException - if an error occurs revoking moderator privileges from a user.

revokeModerator

public void revokeModerator(String nickname)
                     throws XMPPException

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.

Throws:

XMPPException - if an error occurs revoking moderator privileges from a user.

grantOwnership

public void grantOwnership(Collection<String> jids)
                    throws XMPPException

Grants ownership privileges to other users. 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:

jids - the collection of bare XMPP user IDs of the users to grant ownership.

Throws:

XMPPException - if an error occurs granting ownership privileges to a user.

grantOwnership

public void grantOwnership(String jid)
                    throws XMPPException

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:

jid - the bare XMPP user ID of the user to grant ownership (e.g. "user@host.org").

Throws:

XMPPException - if an error occurs granting ownership privileges to a user.

revokeOwnership

public void revokeOwnership(Collection<String> jids)
                     throws XMPPException

Revokes ownership privileges from other users. 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:

jids - the bare XMPP user IDs of the users to revoke ownership.

Throws:

XMPPException - if an error occurs revoking ownership privileges from a user.

revokeOwnership

public void revokeOwnership(String jid)
                     throws XMPPException

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:

jid - the bare XMPP user ID of the user to revoke ownership (e.g. "user@host.org").

Throws:

XMPPException - if an error occurs revoking ownership privileges from a user.

grantAdmin

public void grantAdmin(Collection<String> jids)
                throws XMPPException

Grants administrator privileges to other users. 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:

jids - the bare XMPP user IDs of the users to grant administrator privileges.

Throws:

XMPPException - if an error occurs granting administrator privileges to a user.

grantAdmin

public void grantAdmin(String jid)
                throws XMPPException

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:

jid - the bare XMPP user ID of the user to grant administrator privileges (e.g. "user@host.org").

Throws:

XMPPException - if an error occurs granting administrator privileges to a user.

revokeAdmin

public void revokeAdmin(Collection<String> jids)
                 throws XMPPException

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

Parameters:

jids - the bare XMPP user IDs of the user to revoke administrator privileges.

Throws:

XMPPException - if an error occurs revoking administrator privileges from a user.

revokeAdmin

public void revokeAdmin(String jid)
                 throws XMPPException

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:

jid - the bare XMPP user ID of the user to revoke administrator privileges (e.g. "user@host.org").

Throws:

XMPPException - if an error occurs revoking administrator privileges from a user.

getOccupantsCount

public int getOccupantsCount()

Returns the number of occupants in the group chat.

Note: this value will only be accurate after joining the group chat, and may fluctuate over time. If you query this value directly after joining the group chat it may not be accurate, as it takes a certain amount of time for the server to send all presence packets to this client.

Returns:

the number of occupants in the group chat.

getOccupants

public Iterator<String> getOccupants()

Returns an Iterator (of Strings) for the list of fully qualified occupants in the group chat. For example, "conference@chat.jivesoftware.com/SomeUser". Typically, a client would only display the nickname of the occupant. To get the nickname from the fully qualified name, use the StringUtils.parseResource(String) method. Note: this value will only be accurate after joining the group chat, and may fluctuate over time.

Returns:

an Iterator for the occupants in the group chat.

getOccupantPresence

public Presence getOccupantPresence(String user)

Returns the presence info for a particular user, or null if the user is not in the room.

Parameters:

user - the room occupant to search for his presence. The format of user must be: roomName@service/nickname (e.g. darkcave@macbeth.shakespeare.lit/thirdwitch).

Returns:

the occupant's current presence, or null if the user is unavailable or if no presence information is available.

getOccupant

public Occupant getOccupant(String user)

Returns the Occupant information for a particular occupant, or null if the user is not in the room. The Occupant object may include information such as full JID of the user as well as the role and affiliation of the user in the room.

Parameters:

user - the room occupant to search for his presence. The format of user must be: roomName@service/nickname (e.g. darkcave@macbeth.shakespeare.lit/thirdwitch).

Returns:

the Occupant or null if the user is unavailable (i.e. not in the room).

addParticipantListener

public void addParticipantListener(PacketListener listener)

Adds a packet listener that will be notified of any new Presence packets sent to the group chat. Using a listener is a suitable way to know when the list of occupants should be re-loaded due to any changes.

Parameters:

listener - a packet listener that will be notified of any presence packets sent to the group chat.

removeParticipantListener

public void removeParticipantListener(PacketListener listener)

Remoces a packet listener that was being notified of any new Presence packets sent to the group chat.

Parameters:

listener - a packet listener that was being notified of any presence packets sent to the group chat.

getOwners

public Collection<Affiliate> getOwners()
                                throws XMPPException

Returns a collection of Affiliate with the room owners.

Returns:

a collection of Affiliate with the room owners.

Throws:

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

getAdmins

public Collection<Affiliate> getAdmins()
                                throws XMPPException

Returns a collection of Affiliate with the room administrators.

Returns:

a collection of Affiliate with the room administrators.

Throws:

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

getMembers

public Collection<Affiliate> getMembers()
                                 throws XMPPException

Returns a collection of Affiliate with the room members.

Returns:

a collection of Affiliate with the room members.

Throws:

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

getOutcasts

public Collection<Affiliate> getOutcasts()
                                  throws XMPPException

Returns a collection of Affiliate with the room outcasts.

Returns:

a collection of Affiliate with the room outcasts.

Throws:

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

getModerators

public Collection<Occupant> getModerators()
                                   throws XMPPException

Returns a collection of Occupant with the room moderators.

Returns:

a collection of Occupant with the room moderators.

Throws:

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

getParticipants

public Collection<Occupant> getParticipants()
                                     throws XMPPException

Returns a collection of Occupant with the room participants.

Returns:

a collection of Occupant with the room participants.

Throws:

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

sendMessage

public void sendMessage(String text)
                 throws XMPPException

Sends a message to the chat room.

Parameters:

text - the text of the message to send.

Throws:

XMPPException - if sending the message fails.

createPrivateChat

public Chat createPrivateChat(String occupant,
                              MessageListener listener)

Returns a new Chat for sending private messages to a given room occupant. The Chat's occupant address is the room's JID (i.e. roomName@service/nick). The server service will change the 'from' address to the sender's room JID and delivering the message to the intended recipient's full JID.

Parameters:

occupant - occupant unique room JID (e.g. 'darkcave@macbeth.shakespeare.lit/Paul').

listener - the listener is a message listener that will handle messages for the newly created chat.

Returns:

new Chat for sending private messages to a given room occupant.

createMessage

public Message createMessage()

Creates a new Message to send to the chat room.

Returns:

a new Message addressed to the chat room.

sendMessage

public void sendMessage(Message message)
                 throws XMPPException

Sends a Message to the chat room.

Parameters:

message - the message.

Throws:

XMPPException - if sending the message fails.

pollMessage

public Message pollMessage()

Polls for and returns the next message, or null if there isn't a message immediately available. This method provides significantly different functionalty than the nextMessage() method since it's non-blocking. In other words, the method call will always return immediately, whereas the nextMessage method will return only when a message is available (or after a specific timeout).

Returns:

the next message if one is immediately available and null otherwise.

nextMessage

public Message nextMessage()

Returns the next available message in the chat. The method call will block (not return) until a message is available.

Returns:

the next message.

nextMessage

public Message nextMessage(long timeout)

Returns the next available message in the chat. The method call will block (not return) until a packet is available or the timeout has elapased. If the timeout elapses without a result, null will be returned.

Parameters:

timeout - the maximum amount of time to wait for the next message.

Returns:

the next message, or null if the timeout elapses without a message becoming available.

addMessageListener

public void addMessageListener(PacketListener listener)

Adds a packet listener that will be notified of any new messages in the group chat. Only "group chat" messages addressed to this group chat will be delivered to the listener. If you wish to listen for other packets that may be associated with this group chat, you should register a PacketListener directly with the XMPPConnection with the appropriate PacketListener.

Parameters:

listener - a packet listener.

removeMessageListener

public void removeMessageListener(PacketListener listener)

Removes a packet listener that was being notified of any new messages in the multi user chat. Only "group chat" messages addressed to this multi user chat were being delivered to the listener.

Parameters:

listener - a packet listener.

changeSubject

public void changeSubject(String subject)
                   throws XMPPException

Changes the subject within the room. As a default, only users with a role of "moderator" are allowed to change the subject in a room. Although some rooms may be configured to allow a mere participant or even a visitor to change the subject.

Parameters:

subject - the new room's subject to set.

Throws:

XMPPException - if someone without appropriate privileges attempts to change the room subject will throw an error with code 403 (i.e. Forbidden)

addUserStatusListener

public void addUserStatusListener(UserStatusListener listener)

Adds a listener that will be notified of changes in your status in the room such as the user being kicked, banned, or granted admin permissions.

Parameters:

listener - a user status listener.

removeUserStatusListener

public void removeUserStatusListener(UserStatusListener listener)

Removes a listener that was being notified of changes in your status in the room such as the user being kicked, banned, or granted admin permissions.

Parameters:

listener - a user status listener.

addParticipantStatusListener

public void addParticipantStatusListener(ParticipantStatusListener listener)

Adds a listener that will be notified of changes in occupants status in the room such as the user being kicked, banned, or granted admin permissions.

Parameters:

listener - a participant status listener.

removeParticipantStatusListener

public void removeParticipantStatusListener(ParticipantStatusListener listener)

Removes a listener that was being notified of changes in occupants status in the room such as the user being kicked, banned, or granted admin permissions.

Parameters:

listener - a participant status listener.

finalize

public void finalize()
              throws Throwable

Overrides:

finalize in class Object

Throws:

Throwable