MultiUserChatServer.java 10.4 KB
Newer Older
Matt Tucker's avatar
Matt Tucker committed
1 2 3 4 5
/**
 * $RCSfile$
 * $Revision$
 * $Date$
 *
Matt Tucker's avatar
Matt Tucker committed
6
 * Copyright (C) 2004 Jive Software. All rights reserved.
Matt Tucker's avatar
Matt Tucker committed
7
 *
Matt Tucker's avatar
Matt Tucker committed
8 9
 * This software is published under the terms of the GNU Public License (GPL),
 * a copy of which is included in this distribution.
Matt Tucker's avatar
Matt Tucker committed
10
 */
Matt Tucker's avatar
Matt Tucker committed
11

Matt Tucker's avatar
Matt Tucker committed
12 13 14
package org.jivesoftware.messenger.muc;

import java.util.List;
15
import java.util.Collection;
Matt Tucker's avatar
Matt Tucker committed
16 17 18

import org.jivesoftware.messenger.auth.UnauthorizedException;
import org.jivesoftware.messenger.user.UserNotFoundException;
19 20
import org.xmpp.packet.Message;
import org.xmpp.packet.JID;
21
import org.xmpp.component.Component;
Matt Tucker's avatar
Matt Tucker committed
22 23 24 25

/**
 * Manages groupchat conversations, chatrooms, and users. This class is designed to operate
 * 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.
Matt Tucker's avatar
Matt Tucker committed
27 28 29
 * 
 * @author Gaston Dombiak
 */
30
public interface MultiUserChatServer extends Component {
Matt Tucker's avatar
Matt Tucker committed
31 32

    /**
33 34 35
     * Returns the fully-qualifed domain name of this chat service.
     * The domain is composed by the service name and the
     * name of the XMPP server where the service is running.
Matt Tucker's avatar
Matt Tucker committed
36
     * 
37
     * @return the chat server domain (service name + host name).
Matt Tucker's avatar
Matt Tucker committed
38
     */
39
    String getServiceDomain();
Matt Tucker's avatar
Matt Tucker committed
40

41 42 43 44 45 46 47
    /**
     * Returns the subdomain of the chat service.
     *
     * @return the subdomain of the chat service.
     */
    String getServiceName();

Matt Tucker's avatar
Matt Tucker committed
48
    /**
49
     * Set the name of this chat service. The new name won't go into effect until the server is
Matt Tucker's avatar
Matt Tucker committed
50 51
     * restarted.
     * 
52
     * @param name The chat service name (host name).
Matt Tucker's avatar
Matt Tucker committed
53
     */
54
    void setServiceName(String name);
Matt Tucker's avatar
Matt Tucker committed
55 56

    /**
57
     * Returns the collection of JIDs that are system administrators of the MUC service. A sysadmin has
Matt Tucker's avatar
Matt Tucker committed
58 59 60 61
     * the same permissions as a room owner. 
     * 
     * @return a list of bare JIDs.
     */
62
    Collection<String> getSysadmins();
Matt Tucker's avatar
Matt Tucker committed
63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79

    /**
     * Adds a new system administrator of the MUC service. A sysadmin has the same permissions as 
     * a room owner. 
     * 
     * @param userJID the bare JID of the new user to add as a system administrator.
     */
    void addSysadmin(String userJID);

    /**
     * Removes a system administrator of the MUC service.
     * 
     * @param userJID the bare JID of the user to remove from the list.
     */
    void removeSysadmin(String userJID);

    /**
80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96
     * Returns false if anyone can create rooms or true if only the returned JIDs in
     * <code>getUsersAllowedToCreate</code> are allowed to create rooms.
     *
     * @return true if only some JIDs are allowed to create rooms.
     */
    boolean isRoomCreationRestricted();

    /**
     * Sets if anyone can create rooms or if only the returned JIDs in
     * <code>getUsersAllowedToCreate</code> are allowed to create rooms.
     *
     * @param roomCreationRestricted whether anyone can create rooms or not.
     */
    void setRoomCreationRestricted(boolean roomCreationRestricted);

    /**
     * Returns the collection of JIDs that are allowed to create MUC rooms. An empty list means that
Matt Tucker's avatar
Matt Tucker committed
97 98 99 100
     * anyone can create a room. 
     * 
     * @return a list of bare JIDs.
     */
101
    Collection<String> getUsersAllowedToCreate();
Matt Tucker's avatar
Matt Tucker committed
102 103 104 105 106 107 108 109 110 111 112 113 114 115 116

    /**
     * Adds a new user to the list of JIDs that are allowed to create MUC rooms.
     * 
     * @param userJID the bare JID of the new user to add to list.
     */
    void addUserAllowedToCreate(String userJID);

    /**
     * Removes a user from list of JIDs that are allowed to create MUC rooms.
     * 
     * @param userJID the bare JID of the user to remove from the list.
     */
    void removeUserAllowedToCreate(String userJID);

117 118 119 120 121 122 123 124 125
    /**
     * Sets the time to elapse between clearing of idle chat users. A <code>TimerTask</code> will be
     * added to a <code>Timer</code> scheduled for repeated fixed-delay execution whose main
     * responsibility is to kick users that have been idle for a certain time. A user is considered
     * idle if he/she didn't send any message to any group chat room for a certain amount of time.
     * See {@link #setUserIdleTime(int)}.
     *
     * @param timeout the time to elapse between clearing of idle chat users.
     */
126 127
    void setKickIdleUsersTimeout(int timeout);

128 129 130 131 132 133 134
    /**
     * Returns the time to elapse between clearing of idle chat users. A user is considered
     * idle if he/she didn't send any message to any group chat room for a certain amount of time.
     * See {@link #getUserIdleTime()}.
     *
     * @return the time to elapse between clearing of idle chat users.
     */
135 136
    int getKickIdleUsersTimeout();

137 138 139 140 141 142
    /**
     * Sets the number of milliseconds a user must be idle before he/she gets kicked from all
     * the rooms. By idle we mean that the user didn't send any message to any group chat room.
     *
     * @param idle the amount of time to wait before considering a user idle.
     */
143 144
    void setUserIdleTime(int idle);

145 146 147 148 149 150
    /**
     * Returns the number of milliseconds a user must be idle before he/she gets kicked from all
     * the rooms. By idle we mean that the user didn't send any message to any group chat room.
     *
     * @return the amount of time to wait before considering a user idle.
     */
151 152
    int getUserIdleTime();

153 154 155 156 157 158 159 160
    /**
     * Sets the time to elapse between logging the room conversations. A <code>TimerTask</code> will
     * be added to a <code>Timer</code> scheduled for repeated fixed-delay execution whose main
     * responsibility is to log queued rooms conversations. The number of queued conversations to
     * save on each run can be configured. See {@link #setLogConversationBatchSize(int)}.
     *
     * @param timeout the time to elapse between logging the room conversations.
     */
161 162
    void setLogConversationsTimeout(int timeout);

163 164 165 166 167 168 169 170
    /**
     * Returns the time to elapse between logging the room conversations. A <code>TimerTask</code>
     * will be added to a <code>Timer</code> scheduled for repeated fixed-delay execution whose main
     * responsibility is to log queued rooms conversations. The number of queued conversations to
     * save on each run can be configured. See {@link #getLogConversationBatchSize()}.
     *
     * @return the time to elapse between logging the room conversations.
     */
171 172
    int getLogConversationsTimeout();

173 174 175 176 177 178 179
    /**
     * Sets the number of messages to save to the database on each run of the logging process.
     * Even though the saving of queued conversations takes place in another thread it is not
     * recommended specifying a big number.
     *
     * @param size the number of messages to save to the database on each run of the logging process.
     */
180 181
    void setLogConversationBatchSize(int size);

182 183 184 185 186
    /**
     * Returns the number of messages to save to the database on each run of the logging process.
     *
     * @return the number of messages to save to the database on each run of the logging process.
     */
187 188
    int getLogConversationBatchSize();

Matt Tucker's avatar
Matt Tucker committed
189 190 191 192 193 194 195 196 197 198 199 200 201 202 203
    /**
     * Obtain the server-wide default message history settings.
     * 
     * @return The message history strategy defaults for the server.
     */
    HistoryStrategy getHistoryStrategy();

    /**
     * Obtains a chatroom by name. A chatroom is created for that name if none exists and the user
     * has permission. The user that asked for the chatroom will be the room's owner if the chatroom
     * was created.
     * 
     * @param roomName Name of the room to get.
     * @param userjid The user's normal jid, not the chat nickname jid.
     * @return The chatroom for the given name.
204
     * @throws UnauthorizedException If the caller doesn't have permission to create a new room.
Matt Tucker's avatar
Matt Tucker committed
205
     */
206
    MUCRoom getChatRoom(String roomName, JID userjid) throws UnauthorizedException;
Matt Tucker's avatar
Matt Tucker committed
207 208 209 210 211 212 213 214 215

    /**
     * Obtains a chatroom by name. If the chatroom does not exists then null will be returned.
     * 
     * @param roomName Name of the room to get.
     * @return The chatroom for the given name or null if the room does not exists.
     */
    MUCRoom getChatRoom(String roomName);

216 217 218 219 220 221 222 223
    /**
     * Retuns a list with a snapshot of all the rooms in the server (i.e. persistent or not,
     * in memory or not).
     *
     * @return a list with a snapshot of all the rooms.
     */
    List<MUCRoom> getChatRooms();

Matt Tucker's avatar
Matt Tucker committed
224 225 226 227 228 229 230 231 232 233 234 235 236
    /**
     * Returns true if the server includes a chatroom with the requested name.
     * 
     * @param roomName the name of the chatroom to check.
     * @return true if the server includes a chatroom with the requested name.
     */
    boolean hasChatRoom(String roomName);

    /**
     * Removes the room associated with the given name.
     * 
     * @param roomName The room to remove.
     */
237
    void removeChatRoom(String roomName);
Matt Tucker's avatar
Matt Tucker committed
238 239 240 241 242 243

    /**
     * Removes a user from all chat rooms.
     * 
     * @param jabberID The user's normal jid, not the chat nickname jid.
     */
244
    void removeUser(JID jabberID);
Matt Tucker's avatar
Matt Tucker committed
245 246 247 248 249 250 251 252

    /**
     * Obtain a chat user by XMPPAddress.
     * 
     * @param userjid The XMPPAddress of the user.
     * @return The chatuser corresponding to that XMPPAddress.
     * @throws UserNotFoundException If the user is not found and can't be auto-created.
     */
253
    MUCUser getChatUser(JID userjid) throws UserNotFoundException;
Matt Tucker's avatar
Matt Tucker committed
254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278

    /**
     * Broadcast a given message to all members of this chat room. The sender is always set to be
     * the chatroom.
     * 
     * @param msg The message to broadcast.
     */
    void serverBroadcast(String msg) throws UnauthorizedException;

    /**
     * Returns the total chat time of all rooms combined.
     * 
     * @return total chat time in milliseconds.
     */
    public long getTotalChatTime();

    /**
     * Logs that a given message was sent to a room as part of a conversation. Every message sent
     * to the room that is allowed to be broadcasted and that was sent either from the room itself 
     * or from an occupant will be logged.<p>
     * 
     * Note: For performane reasons, the logged message won't be immediately saved. Instead we keep
     * the logged messages in memory until the logging process saves them to the database. It's 
     * possible to configure the logging process to run every X milliseconds and also the number 
     * of messages to log on each execution. 
279
     * @see org.jivesoftware.messenger.muc.spi.MultiUserChatServerImpl#initialize(org.jivesoftware.messenger.XMPPServer)
Matt Tucker's avatar
Matt Tucker committed
280 281 282
     * 
     * @param room the room that received the message.
     * @param message the message to log as part of the conversation in the room.
Matt Tucker's avatar
Matt Tucker committed
283
     * @param sender the real XMPPAddress of the sender (e.g. john@example.org). 
Matt Tucker's avatar
Matt Tucker committed
284
     */
285
    void logConversation(MUCRoom room, Message message, JID sender);
Matt Tucker's avatar
Matt Tucker committed
286
}