MultiUserChatService.java 15.2 KB
Newer Older
1 2 3 4 5
/**
 * $RCSfile$
 * $Revision: 3036 $
 * $Date: 2005-11-07 15:15:00 -0300 (Mon, 07 Nov 2005) $
 *
6
 * Copyright (C) 2005-2008 Jive Software. All rights reserved.
7
 *
8 9 10 11 12 13 14 15 16 17 18
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
19 20
 */

21
package org.jivesoftware.openfire.muc;
22 23

import org.xmpp.component.Component;
Gaston Dombiak's avatar
Gaston Dombiak committed
24 25
import org.xmpp.packet.JID;
import org.xmpp.packet.Message;
26 27 28
import org.jivesoftware.openfire.muc.spi.LocalMUCRoom;
import org.jivesoftware.database.JiveID;
import org.jivesoftware.util.JiveConstants;
Gaston Dombiak's avatar
Gaston Dombiak committed
29 30 31

import java.util.Collection;
import java.util.List;
32 33 34 35 36 37 38 39

/**
 * Manages groupchat conversations, chatrooms, and users. This class is designed to operate
 * independently from the rest of the Jive server infrastruture. This theoretically allows
 * deployment of the groupchat on a separate server from the main IM server.
 * 
 * @author Gaston Dombiak
 */
40 41
@JiveID(JiveConstants.MUC_SERVICE)
public interface MultiUserChatService extends Component {
42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62

    /**
     * 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.
     * 
     * @return the chat server domain (service name + host name).
     */
    String getServiceDomain();

    /**
     * Returns the subdomain of the chat service.
     *
     * @return the subdomain of the chat service.
     */
    String getServiceName();

    /**
     * Returns the collection of JIDs that are system administrators of the MUC service. A sysadmin has
     * the same permissions as a room owner. 
     * 
63
     * @return a list of user/group JIDs.
64
     */
65
    Collection<JID> getSysadmins();
66 67 68 69 70 71 72
    
    /**
     * Validates the given JID as a MUC service administrator. 
     * 
     * @return true if the given JID is a MUC service administrator
     */
    boolean isSysadmin(JID bareJID);
73 74 75 76 77

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

82 83 84 85 86 87 88 89
    /**
     * Adds multiple system administrators for the MUC service. A sysadmin has the same permissions as 
     * a room owner. 
     * 
     * @param userJIDs the JIDs of the new users/groups to add as a system administrator.
     */
    void addSysadmins(Collection<JID> userJIDs);

90 91 92
    /**
     * Removes a system administrator of the MUC service.
     * 
93
     * @param userJID the bare JID of the user/group to remove from the list.
94
     */
95
    void removeSysadmin(JID userJID);
96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116

    /**
     * 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
     * anyone can create a room. 
     * 
117
     * @return a list of user/group JIDs.
118
     */
119
    Collection<JID> getUsersAllowedToCreate();
120 121

    /**
122
     * Adds a new user/group to the list of JIDs that are allowed to create MUC rooms.
123
     * 
124
     * @param userJID the JID of the new user/group to add to list.
125
     */
126
    void addUserAllowedToCreate(JID userJID);
127 128
    
    /**
129 130
     * Adds new users/groups to the list of JIDs that are allowed to create MUC rooms.
     * @param userJIDs collection of JIDs for users/groups to add to list.
131 132
     */
    void addUsersAllowedToCreate(Collection<JID> userJIDs);
133 134

    /**
135
     * Removes a user/group from list of JIDs that are allowed to create MUC rooms.
136
     * 
137
     * @param userJID the JID of the user/group to remove from the list.
138
     */
139
    void removeUserAllowedToCreate(JID userJID);
140

141
    /**
142
     * Removes users/groups from list of JIDs that are allowed to create MUC rooms.
143
     * 
144
     * @param userJIDs collection of JIDs of users/groups to remove from the list.
145 146 147
     */
    void removeUsersAllowedToCreate(Collection<JID> userJIDs);

148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245
    /**
     * 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.
     */
    void setKickIdleUsersTimeout(int timeout);

    /**
     * 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.
     */
    int getKickIdleUsersTimeout();

    /**
     * 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.
     */
    void setUserIdleTime(int idle);

    /**
     * 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.
     */
    int getUserIdleTime();

    /**
     * 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.
     */
    void setLogConversationsTimeout(int timeout);

    /**
     * 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.
     */
    int getLogConversationsTimeout();

    /**
     * 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.
     */
    void setLogConversationBatchSize(int size);

    /**
     * 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.
     */
    int getLogConversationBatchSize();

    /**
     * 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.
     * @throws NotAllowedException If the caller doesn't have permission to create a new room.
     */
    MUCRoom getChatRoom(String roomName, JID userjid) throws NotAllowedException;

    /**
     * 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);
246 247 248 249 250 251 252 253
    
    /**
    * Forces a re-read of the room. Useful when a change occurs externally.
    * 
    * @param roomName Name of the room to refresh.
    */
    void refreshChatRoom(String roomName);
    
254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269
    /**
     * 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();

    /**
     * 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);

270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285
    /**
     * Notification message indicating that the specified chat room was
     * removed from some other cluster member.
     *
     * @param room the removed room in another cluster node.
     */
    public void chatRoomRemoved(LocalMUCRoom room);

    /**
     * Notification message indicating that a chat room has been created
     * in another cluster member.
     *
     * @param room the created room in another cluster node.
     */
    public void chatRoomAdded(LocalMUCRoom room);

286 287 288 289 290 291 292
    /**
     * Removes the room associated with the given name.
     * 
     * @param roomName The room to remove.
     */
    void removeChatRoom(String roomName);

293 294 295 296 297 298 299 300 301 302 303
    /**
     * Returns the list of {@link org.jivesoftware.openfire.muc.MUCRole} in all rooms for the specified
     * user's session. When running in a cluster the list will include
     * {@link org.jivesoftware.openfire.muc.spi.LocalMUCRole} and {@link org.jivesoftware.openfire.muc.spi.RemoteMUCRole}.
     *
     *
     * @param user the full JID that identifies the session of the user.
     * @return the list of MUCRoles in all rooms for the specified user's session.
     */
    Collection<MUCRole> getMUCRoles(JID user);

304 305 306 307 308 309 310
    /**
     * Returns the total chat time of all rooms combined.
     * 
     * @return total chat time in milliseconds.
     */
    public long getTotalChatTime();

311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349
    /**
     * Retuns the number of existing rooms in the server (i.e. persistent or not,
     * in memory or not).
     *
     * @return the number of existing rooms in the server.
     */
    public int getNumberChatRooms();

    /**
     * Retuns the total number of occupants in all rooms in the server.
     *
     * @param onlyLocal true if only users connected to this JVM will be considered. Otherwise count cluster wise.
     * @return the number of existing rooms in the server.
     */
    public int getNumberConnectedUsers(boolean onlyLocal);

    /**
     * Retuns the total number of users that have joined in all rooms in the server.
     *
     * @return the number of existing rooms in the server.
     */
    public int getNumberRoomOccupants();

    /**
     * Returns the total number of incoming messages since last reset.
     *
     * @param resetAfter True if you want the counter to be reset after results returned.
     * @return the number of incoming messages through the service.
     */
    public long getIncomingMessageCount(boolean resetAfter);

    /**
     * Returns the total number of outgoing messages since last reset.
     *
     * @param resetAfter True if you want the counter to be reset after results returned.
     * @return the number of outgoing messages through the service.
     */
    public long getOutgoingMessageCount(boolean resetAfter);

350 351 352 353 354 355 356 357 358
    /**
     * 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. 
359
     * @see org.jivesoftware.openfire.muc.spi.MultiUserChatServiceImpl#initialize(org.jivesoftware.openfire.XMPPServer)
360 361 362 363 364 365
     * 
     * @param room the room that received the message.
     * @param message the message to log as part of the conversation in the room.
     * @param sender the real XMPPAddress of the sender (e.g. john@example.org). 
     */
    void logConversation(MUCRoom room, Message message, JID sender);
Gaston Dombiak's avatar
Gaston Dombiak committed
366 367 368 369 370 371 372 373

    /**
     * Notification message indicating the server that an incoming message was broadcasted
     * to a given number of occupants.
     *
     * @param numOccupants number of occupants that received the message.
     */
    void messageBroadcastedTo(int numOccupants);
374 375 376 377 378 379

    /**
     * Enables or disables the MUC service. When disabled the MUC service will disappear from
     * the disco#items list. Moreover, service discovery features will be disabled. 
     *
     * @param enabled true if the service is enabled.
Gaston Dombiak's avatar
Gaston Dombiak committed
380
     * @param persistent true if the new setting will persist across restarts.
381
     */
382
    void enableService(boolean enabled, boolean persistent);
383 384

    /**
385
     * Returns true if the MUC service is available. Use {@link #enableService(boolean, boolean)} to
386 387 388 389 390
     * enable or disable the service.
     *
     * @return true if the MUC service is available.
     */
    boolean isServiceEnabled();
391 392

    /**
393
     * Returns true if the MUC service is a hidden, externally managed, service.  This is typically
394 395 396
     * set to true when the implementation is not the default one, and is not to be managed by
     * the standard Openfire interface.  If this is set to true, the service will not show up in
     * the service list in the admin console.
397
     *
398
     * @return true if the MUC service is hidden and externally managed.
399
     */
400
    boolean isHidden();
401
}