org.jivesoftware.smack
Class GroupChat

java.lang.Object
  org.jivesoftware.smack.GroupChat

public class GroupChat
extends Object

A GroupChat is a conversation that takes place among many users in a virtual room. When joining a group chat, you specify a nickname, which is the identity that other chat room users see.

Author:

Matt Tucker

See Also:

XMPPConnection.createGroupChat(String)

Constructor Summary

GroupChat(XMPPConnection connection, String room)
Creates a new group chat with the specified connection and room name.

Method Summary

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.
Message	createMessage() Creates a new Message to send to the chat room.
void	finalize()
String	getNickname() Returns the nickname that was used to join the room, or null if not currently joined.
int	getParticipantCount() Returns the number of participants in the group chat.
Iterator	getParticipants() Returns an Iterator (of Strings) for the list of fully qualified participants in the group chat.
String	getRoom() Returns the name of the room this GroupChat object represents.
boolean	isJoined() Returns true if currently in the group chat (after calling the join(String) method.
void	join(String nickname) Joins the chat room using the specified nickname.
void	join(String nickname, long timeout) Joins the chat room using the specified nickname.
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.
void	sendMessage(Message message) Sends a Message to the chat room.
void	sendMessage(String text) Sends a message to the chat room.

Methods inherited from class java.lang.Object

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

Constructor Detail

GroupChat

public GroupChat(XMPPConnection connection,
                 String room)

Creates a new group 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.

Method Detail

getRoom

public String getRoom()

Returns the name of the room this GroupChat object represents.

Returns:

the groupchat room name.

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 5 seconds for a reply from the group chat server that the join succeeded will be used.

Parameters:

nickname - the nickname to use.

Throws:

XMPPException - if an error occurs joining the room. In particular, a 409 error can occur if someone is already in the group chat with the same nickname.

join

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

Joins the chat room using the specified nickname. If already joined as another nickname, will leave as that name first before joining under the new name.

Parameters:

nickname - the nickname to use.

timeout - the number of milleseconds to wait for a reply from the group chat that joining the room succeeded.

Throws:

XMPPException - if an error occurs joining the room. In particular, 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 group chat (after calling the join(String) method.

Returns:

true if currently in the group chat room.

leave

public void leave()

Leave the chat room.

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.

getParticipantCount

public int getParticipantCount()

Returns the number of participants 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 participants in the group chat.

getParticipants

public Iterator getParticipants()

Returns an Iterator (of Strings) for the list of fully qualified participants in the group chat. For example, "conference@chat.jivesoftware.com/SomeUser". Typically, a client would only display the nickname of the participant. 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 participants in the group chat.

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 participants 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.

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.

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.

finalize

public void finalize()
              throws Throwable

Overrides:

finalize in class Object

Throws:

Throwable