org.jivesoftware.smack
Class Chat

java.lang.Object
  org.jivesoftware.smack.Chat

public class Chat
extends Object

A chat is a series of messages sent between two users. Each chat can have a unique thread ID, which is used to track which messages are part of a particular conversation.

In some situations, it is better to have all messages from the other user delivered to a Chat rather than just the messages that have a particular thread ID. To enable this behavior, call setFilteredOnThreadID(boolean) with false as the parameter.

Author:

Matt Tucker

See Also:

XMPPConnection.createChat(String)

Constructor Summary

Chat(XMPPConnection connection, String participant)
Creates a new chat with the specified user.

Chat(XMPPConnection connection, String participant, String threadID)
Creates a new chat with the specified user and thread ID.

Method Summary

void	addMessageListener(PacketListener listener) Adds a packet listener that will be notified of any new messages in the chat.
Message	createMessage() Creates a new Message to the chat participant.
void	finalize()
String	getParticipant() Returns the name of the user the chat is with.
String	getThreadID() Returns the thread id associated with this chat, which corresponds to the thread field of XMPP messages.
static boolean	isFilteredOnThreadID() Returns true if only messages that have a matching threadID will be delivered to Chat instances.
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 other chat participant.
void	sendMessage(String text) Sends the specified text as a message to the other chat participant.
static void	setFilteredOnThreadID(boolean value) Sets whether only messages that have a matching threadID will be delivered to Chat instances.

Methods inherited from class java.lang.Object

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

Constructor Detail

Chat

public Chat(XMPPConnection connection,
            String participant)

Creates a new chat with the specified user.

Parameters:

connection - the connection the chat will use.

participant - the user to chat with.

Chat

public Chat(XMPPConnection connection,
            String participant,
            String threadID)

Creates a new chat with the specified user and thread ID.

Parameters:

connection - the connection the chat will use.

participant - the user to chat with.

threadID - the thread ID to use.

Method Detail

isFilteredOnThreadID

public static boolean isFilteredOnThreadID()

Returns true if only messages that have a matching threadID will be delivered to Chat instances. When false, any message from the other participant will be delivered to Chat instances.

Returns:

true if messages delivered to Chat instances are filtered on thread ID.

setFilteredOnThreadID

public static void setFilteredOnThreadID(boolean value)

Sets whether only messages that have a matching threadID will be delivered to Chat instances. When false, any message from the other participant will be delivered to a Chat instances.

Parameters:

value - true if messages delivered to Chat instances are filtered on thread ID.

getThreadID

public String getThreadID()

Returns the thread id associated with this chat, which corresponds to the thread field of XMPP messages. This method may return null if there is no thread ID is associated with this Chat.

Returns:

the thread ID of this chat.

getParticipant

public String getParticipant()

Returns the name of the user the chat is with.

Returns:

the name of the user the chat is occuring with.

sendMessage

public void sendMessage(String text)
                 throws XMPPException

Sends the specified text as a message to the other chat participant. This is a convenience method for:

     Message message = chat.createMessage();
     message.setBody(messageText);
     chat.sendMessage(message);
 

Parameters:

text - the text to send.

Throws:

XMPPException - if sending the message fails.

createMessage

public Message createMessage()

Creates a new Message to the chat participant. The message returned will have its thread property set with this chat ID.

Returns:

a new message addressed to the chat participant and using the correct thread value.

See Also:

sendMessage(Message)

sendMessage

public void sendMessage(Message message)
                 throws XMPPException

Sends a message to the other chat participant. The thread ID, recipient, and message type of the message will automatically set to those of this chat in case the Message was not created using the createMessage method.

Parameters:

message - the message to send.

Throws:

XMPPException - if an error occurs sending the message.

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

Parameters:

listener - a packet listener.

finalize

public void finalize()
              throws Throwable

Overrides:

finalize in class Object

Throws:

Throwable