KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > jivesoftware > smack > Chat


1 /**
2  * $RCSfile$
3  * $Revision: 2408 $
4  * $Date: 2004-11-02 20:53:30 -0300 (Tue, 02 Nov 2004) $
5  *
6  * Copyright 2003-2004 Jive Software.
7  *
8  * All rights reserved. Licensed under the Apache License, Version 2.0 (the "License");
9  * you may not use this file except in compliance with the License.
10  * You may obtain a copy of the License at
11  *
12  * http://www.apache.org/licenses/LICENSE-2.0
13  *
14  * Unless required by applicable law or agreed to in writing, software
15  * distributed under the License is distributed on an "AS IS" BASIS,
16  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
17  * See the License for the specific language governing permissions and
18  * limitations under the License.
19  */
20
21 package org.jivesoftware.smack;
22
23 import org.jivesoftware.smack.packet.Message;
24 import org.jivesoftware.smack.util.StringUtils;
25 import org.jivesoftware.smack.filter.*;
26
27 /**
28  * A chat is a series of messages sent between two users. Each chat can have
29  * a unique thread ID, which is used to track which messages are part of a particular
30  * conversation.<p>
31  *
32  * In some situations, it is better to have all messages from the other user delivered
33  * to a Chat rather than just the messages that have a particular thread ID. To
34  * enable this behavior, call {@link #setFilteredOnThreadID(boolean)} with
35  * <tt>false</tt> as the parameter.
36  *
37  * @see XMPPConnection#createChat(String)
38  * @author Matt Tucker
39  */
40 public class Chat {
41
42     /**
43      * A prefix helps to make sure that ID's are unique across mutliple instances.
44      */
45     private static String JavaDoc prefix = StringUtils.randomString(5);
46     
47     /**
48      * True if only messages that have a matching threadID will be delivered to a Chat. When
49      * false, any message from the other participant will be delivered to a Chat.
50      */
51     private static boolean filteredOnThreadID = true;
52     
53     /**
54      * Keeps track of the current increment, which is appended to the prefix to
55      * forum a unique ID.
56      */
57     private static long id = 0;
58
59     /**
60      * Returns the next unique id. Each id made up of a short alphanumeric
61      * prefix along with a unique numeric value.
62      *
63      * @return the next id.
64      */
65     private static synchronized String JavaDoc nextID() {
66         return prefix + Long.toString(id++);
67     }
68
69     private XMPPConnection connection;
70     private String JavaDoc threadID;
71     private String JavaDoc participant;
72     private PacketFilter messageFilter;
73     private PacketCollector messageCollector;
74
75     /**
76      * Creates a new chat with the specified user.
77      *
78      * @param connection the connection the chat will use.
79      * @param participant the user to chat with.
80      */
81     public Chat(XMPPConnection connection, String JavaDoc participant) {
82         // Automatically assign the next chat ID.
83 this(connection, participant, nextID());
84         // If not filtering on thread ID, force the thread ID for this Chat to be null.
85 if (!filteredOnThreadID) {
86             this.threadID = null;
87         }
88     }
89
90     /**
91      * Creates a new chat with the specified user and thread ID.
92      *
93      * @param connection the connection the chat will use.
94      * @param participant the user to chat with.
95      * @param threadID the thread ID to use.
96      */
97     public Chat(XMPPConnection connection, String JavaDoc participant, String JavaDoc threadID) {
98         this.connection = connection;
99         this.participant = participant;
100         this.threadID = threadID;
101
102         if (filteredOnThreadID) {
103             // Filter the messages whose thread equals Chat's id
104 messageFilter = new ThreadFilter(threadID);
105         }
106         else {
107             // Filter the messages of type "chat" and sender equals Chat's participant
108 messageFilter =
109                 new OrFilter(
110                     new AndFilter(
111                         new MessageTypeFilter(Message.Type.CHAT),
112                         new FromContainsFilter(participant)),
113                     new ThreadFilter(threadID));
114         }
115         messageCollector = connection.createPacketCollector(messageFilter);
116     }
117
118     /**
119      * Returns true if only messages that have a matching threadID will be delivered to Chat
120      * instances. When false, any message from the other participant will be delivered to Chat instances.
121      *
122      * @return true if messages delivered to Chat instances are filtered on thread ID.
123      */
124     public static boolean isFilteredOnThreadID() {
125         return filteredOnThreadID;
126     }
127
128     /**
129      * Sets whether only messages that have a matching threadID will be delivered to Chat instances.
130      * When false, any message from the other participant will be delivered to a Chat instances.
131      *
132      * @param value true if messages delivered to Chat instances are filtered on thread ID.
133      */
134     public static void setFilteredOnThreadID(boolean value) {
135         filteredOnThreadID = value;
136     }
137
138     /**
139      * Returns the thread id associated with this chat, which corresponds to the
140      * <tt>thread</tt> field of XMPP messages. This method may return <tt>null</tt>
141      * if there is no thread ID is associated with this Chat.
142      *
143      * @return the thread ID of this chat.
144      */
145     public String JavaDoc getThreadID() {
146         return threadID;
147     }
148
149     /**
150      * Returns the name of the user the chat is with.
151      *
152      * @return the name of the user the chat is occuring with.
153      */
154     public String JavaDoc getParticipant() {
155         return participant;
156     }
157
158     /**
159      * Sends the specified text as a message to the other chat participant.
160      * This is a convenience method for:
161      *
162      * <pre>
163      * Message message = chat.createMessage();
164      * message.setBody(messageText);
165      * chat.sendMessage(message);
166      * </pre>
167      *
168      * @param text the text to send.
169      * @throws XMPPException if sending the message fails.
170      */
171     public void sendMessage(String JavaDoc text) throws XMPPException {
172         Message message = createMessage();
173         message.setBody(text);
174         connection.sendPacket(message);
175     }
176
177     /**
178      * Creates a new Message to the chat participant. The message returned
179      * will have its thread property set with this chat ID.
180      *
181      * @return a new message addressed to the chat participant and
182      * using the correct thread value.
183      * @see #sendMessage(Message)
184      */
185     public Message createMessage() {
186         Message message = new Message(participant, Message.Type.CHAT);
187         message.setThread(threadID);
188         return message;
189     }
190
191     /**
192      * Sends a message to the other chat participant. The thread ID, recipient,
193      * and message type of the message will automatically set to those of this chat
194      * in case the Message was not created using the {@link #createMessage() createMessage}
195      * method.
196      *
197      * @param message the message to send.
198      * @throws XMPPException if an error occurs sending the message.
199      */
200     public void sendMessage(Message message) throws XMPPException {
201         // Force the recipient, message type, and thread ID since the user elected
202 // to send the message through this chat object.
203 message.setTo(participant);
204         message.setType(Message.Type.CHAT);
205         message.setThread(threadID);
206         connection.sendPacket(message);
207     }
208
209     /**
210      * Polls for and returns the next message, or <tt>null</tt> if there isn't
211      * a message immediately available. This method provides significantly different
212      * functionalty than the {@link #nextMessage()} method since it's non-blocking.
213      * In other words, the method call will always return immediately, whereas the
214      * nextMessage method will return only when a message is available (or after
215      * a specific timeout).
216      *
217      * @return the next message if one is immediately available and
218      * <tt>null</tt> otherwise.
219      */
220     public Message pollMessage() {
221         return (Message)messageCollector.pollResult();
222     }
223
224     /**
225      * Returns the next available message in the chat. The method call will block
226      * (not return) until a message is available.
227      *
228      * @return the next message.
229      */
230     public Message nextMessage() {
231         return (Message)messageCollector.nextResult();
232     }
233
234     /**
235      * Returns the next available message in the chat. The method call will block
236      * (not return) until a packet is available or the <tt>timeout</tt> has elapased.
237      * If the timeout elapses without a result, <tt>null</tt> will be returned.
238      *
239      * @param timeout the maximum amount of time to wait for the next message.
240      * @return the next message, or <tt>null</tt> if the timeout elapses without a
241      * message becoming available.
242      */
243     public Message nextMessage(long timeout) {
244         return (Message)messageCollector.nextResult(timeout);
245     }
246
247     /**
248      * Adds a packet listener that will be notified of any new messages in the
249      * chat.
250      *
251      * @param listener a packet listener.
252      */
253     public void addMessageListener(PacketListener listener) {
254         connection.addPacketListener(listener, messageFilter);
255     }
256
257     public void finalize() throws Throwable JavaDoc {
258         super.finalize();
259         try {
260             if (messageCollector != null) {
261                 messageCollector.cancel();
262             }
263         }
264         catch (Exception JavaDoc e) {}
265     }
266 }
Popular Tags