MultiUserChatServer


1   /**
2    * $RCSfile: MultiUserChatServer.java,v $
3    * $Revision: 1.17 $
4    * $Date: 2005/02/08 21:39:58 $
5    *
6    * Copyright (C) 2004 Jive Software. All rights reserved.
7    *
8    * This software is published under the terms of the GNU Public License (GPL),
9    * a copy of which is included in this distribution.
10   */
11  
12  package org.jivesoftware.messenger.muc;
13  
14  import java.util.List  ;
15  import java.util.Collection  ;
16  
17  import org.jivesoftware.messenger.auth.UnauthorizedException;
18  import org.jivesoftware.messenger.user.UserNotFoundException;
19  import org.xmpp.packet.Message;
20  import org.xmpp.packet.JID;
21  import org.xmpp.component.Component;
22  
23  /**
24   * Manages groupchat conversations, chatrooms, and users. This class is designed to operate
25   * independently from the rest of the Jive server infrastruture. This theoretically allows
26   * deployment of the groupchat on a separate server from the main IM server.
27   * 
28   * @author Gaston Dombiak
29   */
30  public interface MultiUserChatServer extends Component {
31  
32      /**
33       * Returns the fully-qualifed domain name of this chat service.
34       * The domain is composed by the service name and the
35       * name of the XMPP server where the service is running.
36       * 
37       * @return the chat server domain (service name + host name).
38       */
39      String   getServiceDomain();
40  
41      /**
42       * Returns the subdomain of the chat service.
43       *
44       * @return the subdomain of the chat service.
45       */
46      String   getServiceName();
47  
48      /**
49       * Set the name of this chat service. The new name won't go into effect until the server is
50       * restarted.
51       * 
52       * @param name The chat service name (host name).
53       */
54      void setServiceName(String   name);
55  
56      /**
57       * Returns the collection of JIDs that are system administrators of the MUC service. A sysadmin has
58       * the same permissions as a room owner. 
59       * 
60       * @return a list of bare JIDs.
61       */
62      Collection  <String  > getSysadmins();
63  
64      /**
65       * Adds a new system administrator of the MUC service. A sysadmin has the same permissions as 
66       * a room owner. 
67       * 
68       * @param userJID the bare JID of the new user to add as a system administrator.
69       */
70      void addSysadmin(String   userJID);
71  
72      /**
73       * Removes a system administrator of the MUC service.
74       * 
75       * @param userJID the bare JID of the user to remove from the list.
76       */
77      void removeSysadmin(String   userJID);
78  
79      /**
80       * Returns false if anyone can create rooms or true if only the returned JIDs in
81       * <code>getUsersAllowedToCreate</code> are allowed to create rooms.
82       *
83       * @return true if only some JIDs are allowed to create rooms.
84       */
85      boolean isRoomCreationRestricted();
86  
87      /**
88       * Sets if anyone can create rooms or if only the returned JIDs in
89       * <code>getUsersAllowedToCreate</code> are allowed to create rooms.
90       *
91       * @param roomCreationRestricted whether anyone can create rooms or not.
92       */
93      void setRoomCreationRestricted(boolean roomCreationRestricted);
94  
95      /**
96       * Returns the collection of JIDs that are allowed to create MUC rooms. An empty list means that
97       * anyone can create a room. 
98       * 
99       * @return a list of bare JIDs.
100      */
101     Collection  <String  > getUsersAllowedToCreate();
102 
103     /**
104      * Adds a new user to the list of JIDs that are allowed to create MUC rooms.
105      * 
106      * @param userJID the bare JID of the new user to add to list.
107      */
108     void addUserAllowedToCreate(String   userJID);
109 
110     /**
111      * Removes a user from list of JIDs that are allowed to create MUC rooms.
112      * 
113      * @param userJID the bare JID of the user to remove from the list.
114      */
115     void removeUserAllowedToCreate(String   userJID);
116 
117     /**
118      * Sets the time to elapse between clearing of idle chat users. A <code>TimerTask</code> will be
119      * added to a <code>Timer</code> scheduled for repeated fixed-delay execution whose main
120      * responsibility is to kick users that have been idle for a certain time. A user is considered
121      * idle if he/she didn't send any message to any group chat room for a certain amount of time.
122      * See {@link #setUserIdleTime(int)}.
123      *
124      * @param timeout the time to elapse between clearing of idle chat users.
125      */
126     void setKickIdleUsersTimeout(int timeout);
127 
128     /**
129      * Returns the time to elapse between clearing of idle chat users. A user is considered
130      * idle if he/she didn't send any message to any group chat room for a certain amount of time.
131      * See {@link #getUserIdleTime()}.
132      *
133      * @return the time to elapse between clearing of idle chat users.
134      */
135     int getKickIdleUsersTimeout();
136 
137     /**
138      * Sets the number of milliseconds a user must be idle before he/she gets kicked from all
139      * the rooms. By idle we mean that the user didn't send any message to any group chat room.
140      *
141      * @param idle the amount of time to wait before considering a user idle.
142      */
143     void setUserIdleTime(int idle);
144 
145     /**
146      * Returns the number of milliseconds a user must be idle before he/she gets kicked from all
147      * the rooms. By idle we mean that the user didn't send any message to any group chat room.
148      *
149      * @return the amount of time to wait before considering a user idle.
150      */
151     int getUserIdleTime();
152 
153     /**
154      * Sets the time to elapse between logging the room conversations. A <code>TimerTask</code> will
155      * be added to a <code>Timer</code> scheduled for repeated fixed-delay execution whose main
156      * responsibility is to log queued rooms conversations. The number of queued conversations to
157      * save on each run can be configured. See {@link #setLogConversationBatchSize(int)}.
158      *
159      * @param timeout the time to elapse between logging the room conversations.
160      */
161     void setLogConversationsTimeout(int timeout);
162 
163     /**
164      * Returns the time to elapse between logging the room conversations. A <code>TimerTask</code>
165      * will be added to a <code>Timer</code> scheduled for repeated fixed-delay execution whose main
166      * responsibility is to log queued rooms conversations. The number of queued conversations to
167      * save on each run can be configured. See {@link #getLogConversationBatchSize()}.
168      *
169      * @return the time to elapse between logging the room conversations.
170      */
171     int getLogConversationsTimeout();
172 
173     /**
174      * Sets the number of messages to save to the database on each run of the logging process.
175      * Even though the saving of queued conversations takes place in another thread it is not
176      * recommended specifying a big number.
177      *
178      * @param size the number of messages to save to the database on each run of the logging process.
179      */
180     void setLogConversationBatchSize(int size);
181 
182     /**
183      * Returns the number of messages to save to the database on each run of the logging process.
184      *
185      * @return the number of messages to save to the database on each run of the logging process.
186      */
187     int getLogConversationBatchSize();
188 
189     /**
190      * Obtain the server-wide default message history settings.
191      * 
192      * @return The message history strategy defaults for the server.
193      */
194     HistoryStrategy getHistoryStrategy();
195 
196     /**
197      * Obtains a chatroom by name. A chatroom is created for that name if none exists and the user
198      * has permission. The user that asked for the chatroom will be the room's owner if the chatroom
199      * was created.
200      * 
201      * @param roomName Name of the room to get.
202      * @param userjid The user's normal jid, not the chat nickname jid.
203      * @return The chatroom for the given name.
204      * @throws UnauthorizedException If the caller doesn't have permission to create a new room.
205      */
206     MUCRoom getChatRoom(String   roomName, JID userjid) throws UnauthorizedException;
207 
208     /**
209      * Obtains a chatroom by name. If the chatroom does not exists then null will be returned.
210      * 
211      * @param roomName Name of the room to get.
212      * @return The chatroom for the given name or null if the room does not exists.
213      */
214     MUCRoom getChatRoom(String   roomName);
215 
216     /**
217      * Retuns a list with a snapshot of all the rooms in the server (i.e. persistent or not,
218      * in memory or not).
219      *
220      * @return a list with a snapshot of all the rooms.
221      */
222     List  <MUCRoom> getChatRooms();
223 
224     /**
225      * Returns true if the server includes a chatroom with the requested name.
226      * 
227      * @param roomName the name of the chatroom to check.
228      * @return true if the server includes a chatroom with the requested name.
229      */
230     boolean hasChatRoom(String   roomName);
231 
232     /**
233      * Removes the room associated with the given name.
234      * 
235      * @param roomName The room to remove.
236      */
237     void removeChatRoom(String   roomName);
238 
239     /**
240      * Removes a user from all chat rooms.
241      * 
242      * @param jabberID The user's normal jid, not the chat nickname jid.
243      */
244     void removeUser(JID jabberID);
245 
246     /**
247      * Obtain a chat user by XMPPAddress.
248      * 
249      * @param userjid The XMPPAddress of the user.
250      * @return The chatuser corresponding to that XMPPAddress.
251      * @throws UserNotFoundException If the user is not found and can't be auto-created.
252      */
253     MUCUser getChatUser(JID userjid) throws UserNotFoundException;
254 
255     /**
256      * Broadcast a given message to all members of this chat room. The sender is always set to be
257      * the chatroom.
258      * 
259      * @param msg The message to broadcast.
260      */
261     void serverBroadcast(String   msg) throws UnauthorizedException;
262 
263     /**
264      * Returns the total chat time of all rooms combined.
265      * 
266      * @return total chat time in milliseconds.
267      */
268     public long getTotalChatTime();
269 
270     /**
271      * Logs that a given message was sent to a room as part of a conversation. Every message sent
272      * to the room that is allowed to be broadcasted and that was sent either from the room itself 
273      * or from an occupant will be logged.<p>
274      * 
275      * Note: For performane reasons, the logged message won't be immediately saved. Instead we keep
276      * the logged messages in memory until the logging process saves them to the database. It's 
277      * possible to configure the logging process to run every X milliseconds and also the number 
278      * of messages to log on each execution. 
279      * @see org.jivesoftware.messenger.muc.spi.MultiUserChatServerImpl#initialize(org.jivesoftware.messenger.XMPPServer)
280      * 
281      * @param room the room that received the message.
282      * @param message the message to log as part of the conversation in the room.
283      * @param sender the real XMPPAddress of the sender (e.g. john@example.org). 
284      */
285     void logConversation(MUCRoom room, Message message, JID sender);
286 }
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags