001: /**
002: * $RCSfile$
003: * $Revision: 3036 $
004: * $Date: 2005-11-07 15:15:00 -0300 (Mon, 07 Nov 2005) $
005: *
006: * Copyright (C) 2007 Jive Software. All rights reserved.
007: *
008: * This software is published under the terms of the GNU Public License (GPL),
009: * a copy of which is included in this distribution.
010: */package org.jivesoftware.openfire.muc;
011:
012: import org.xmpp.component.Component;
013: import org.xmpp.packet.JID;
014: import org.xmpp.packet.Message;
015:
016: import java.util.Collection;
017: import java.util.List;
018:
019: /**
020: * Manages groupchat conversations, chatrooms, and users. This class is designed to operate
021: * independently from the rest of the Jive server infrastruture. This theoretically allows
022: * deployment of the groupchat on a separate server from the main IM server.
023: *
024: * @author Gaston Dombiak
025: */
026: public interface MultiUserChatServer extends Component {
027:
028: /**
029: * Returns the fully-qualifed domain name of this chat service.
030: * The domain is composed by the service name and the
031: * name of the XMPP server where the service is running.
032: *
033: * @return the chat server domain (service name + host name).
034: */
035: String getServiceDomain();
036:
037: /**
038: * Returns the subdomain of the chat service.
039: *
040: * @return the subdomain of the chat service.
041: */
042: String getServiceName();
043:
044: /**
045: * Set the name of this chat service. The new name won't go into effect until the server is
046: * restarted.
047: *
048: * @param name The chat service name (host name).
049: */
050: void setServiceName(String name);
051:
052: /**
053: * Returns the collection of JIDs that are system administrators of the MUC service. A sysadmin has
054: * the same permissions as a room owner.
055: *
056: * @return a list of bare JIDs.
057: */
058: Collection<String> getSysadmins();
059:
060: /**
061: * Adds a new system administrator of the MUC service. A sysadmin has the same permissions as
062: * a room owner.
063: *
064: * @param userJID the bare JID of the new user to add as a system administrator.
065: */
066: void addSysadmin(String userJID);
067:
068: /**
069: * Removes a system administrator of the MUC service.
070: *
071: * @param userJID the bare JID of the user to remove from the list.
072: */
073: void removeSysadmin(String userJID);
074:
075: /**
076: * Returns false if anyone can create rooms or true if only the returned JIDs in
077: * <code>getUsersAllowedToCreate</code> are allowed to create rooms.
078: *
079: * @return true if only some JIDs are allowed to create rooms.
080: */
081: boolean isRoomCreationRestricted();
082:
083: /**
084: * Sets if anyone can create rooms or if only the returned JIDs in
085: * <code>getUsersAllowedToCreate</code> are allowed to create rooms.
086: *
087: * @param roomCreationRestricted whether anyone can create rooms or not.
088: */
089: void setRoomCreationRestricted(boolean roomCreationRestricted);
090:
091: /**
092: * Returns the collection of JIDs that are allowed to create MUC rooms. An empty list means that
093: * anyone can create a room.
094: *
095: * @return a list of bare JIDs.
096: */
097: Collection<String> getUsersAllowedToCreate();
098:
099: /**
100: * Adds a new user to the list of JIDs that are allowed to create MUC rooms.
101: *
102: * @param userJID the bare JID of the new user to add to list.
103: */
104: void addUserAllowedToCreate(String userJID);
105:
106: /**
107: * Removes a user from list of JIDs that are allowed to create MUC rooms.
108: *
109: * @param userJID the bare JID of the user to remove from the list.
110: */
111: void removeUserAllowedToCreate(String userJID);
112:
113: /**
114: * Sets the time to elapse between clearing of idle chat users. A <code>TimerTask</code> will be
115: * added to a <code>Timer</code> scheduled for repeated fixed-delay execution whose main
116: * responsibility is to kick users that have been idle for a certain time. A user is considered
117: * idle if he/she didn't send any message to any group chat room for a certain amount of time.
118: * See {@link #setUserIdleTime(int)}.
119: *
120: * @param timeout the time to elapse between clearing of idle chat users.
121: */
122: void setKickIdleUsersTimeout(int timeout);
123:
124: /**
125: * Returns the time to elapse between clearing of idle chat users. A user is considered
126: * idle if he/she didn't send any message to any group chat room for a certain amount of time.
127: * See {@link #getUserIdleTime()}.
128: *
129: * @return the time to elapse between clearing of idle chat users.
130: */
131: int getKickIdleUsersTimeout();
132:
133: /**
134: * Sets the number of milliseconds a user must be idle before he/she gets kicked from all
135: * the rooms. By idle we mean that the user didn't send any message to any group chat room.
136: *
137: * @param idle the amount of time to wait before considering a user idle.
138: */
139: void setUserIdleTime(int idle);
140:
141: /**
142: * Returns the number of milliseconds a user must be idle before he/she gets kicked from all
143: * the rooms. By idle we mean that the user didn't send any message to any group chat room.
144: *
145: * @return the amount of time to wait before considering a user idle.
146: */
147: int getUserIdleTime();
148:
149: /**
150: * Sets the time to elapse between logging the room conversations. A <code>TimerTask</code> will
151: * be added to a <code>Timer</code> scheduled for repeated fixed-delay execution whose main
152: * responsibility is to log queued rooms conversations. The number of queued conversations to
153: * save on each run can be configured. See {@link #setLogConversationBatchSize(int)}.
154: *
155: * @param timeout the time to elapse between logging the room conversations.
156: */
157: void setLogConversationsTimeout(int timeout);
158:
159: /**
160: * Returns the time to elapse between logging the room conversations. A <code>TimerTask</code>
161: * will be added to a <code>Timer</code> scheduled for repeated fixed-delay execution whose main
162: * responsibility is to log queued rooms conversations. The number of queued conversations to
163: * save on each run can be configured. See {@link #getLogConversationBatchSize()}.
164: *
165: * @return the time to elapse between logging the room conversations.
166: */
167: int getLogConversationsTimeout();
168:
169: /**
170: * Sets the number of messages to save to the database on each run of the logging process.
171: * Even though the saving of queued conversations takes place in another thread it is not
172: * recommended specifying a big number.
173: *
174: * @param size the number of messages to save to the database on each run of the logging process.
175: */
176: void setLogConversationBatchSize(int size);
177:
178: /**
179: * Returns the number of messages to save to the database on each run of the logging process.
180: *
181: * @return the number of messages to save to the database on each run of the logging process.
182: */
183: int getLogConversationBatchSize();
184:
185: /**
186: * Obtain the server-wide default message history settings.
187: *
188: * @return The message history strategy defaults for the server.
189: */
190: HistoryStrategy getHistoryStrategy();
191:
192: /**
193: * Obtains a chatroom by name. A chatroom is created for that name if none exists and the user
194: * has permission. The user that asked for the chatroom will be the room's owner if the chatroom
195: * was created.
196: *
197: * @param roomName Name of the room to get.
198: * @param userjid The user's normal jid, not the chat nickname jid.
199: * @return The chatroom for the given name.
200: * @throws NotAllowedException If the caller doesn't have permission to create a new room.
201: */
202: MUCRoom getChatRoom(String roomName, JID userjid)
203: throws NotAllowedException;
204:
205: /**
206: * Obtains a chatroom by name. If the chatroom does not exists then null will be returned.
207: *
208: * @param roomName Name of the room to get.
209: * @return The chatroom for the given name or null if the room does not exists.
210: */
211: MUCRoom getChatRoom(String roomName);
212:
213: /**
214: * Retuns a list with a snapshot of all the rooms in the server (i.e. persistent or not,
215: * in memory or not).
216: *
217: * @return a list with a snapshot of all the rooms.
218: */
219: List<MUCRoom> getChatRooms();
220:
221: /**
222: * Returns true if the server includes a chatroom with the requested name.
223: *
224: * @param roomName the name of the chatroom to check.
225: * @return true if the server includes a chatroom with the requested name.
226: */
227: boolean hasChatRoom(String roomName);
228:
229: /**
230: * Removes the room associated with the given name.
231: *
232: * @param roomName The room to remove.
233: */
234: void removeChatRoom(String roomName);
235:
236: /**
237: * Returns the list of {@link org.jivesoftware.openfire.muc.MUCRole} in all rooms for the specified
238: * user's session. When running in a cluster the list will include
239: * {@link org.jivesoftware.openfire.muc.spi.LocalMUCRole} and {@link org.jivesoftware.openfire.muc.spi.RemoteMUCRole}.
240: *
241: *
242: * @param user the full JID that identifies the session of the user.
243: * @return the list of MUCRoles in all rooms for the specified user's session.
244: */
245: Collection<MUCRole> getMUCRoles(JID user);
246:
247: /**
248: * Returns the total chat time of all rooms combined.
249: *
250: * @return total chat time in milliseconds.
251: */
252: public long getTotalChatTime();
253:
254: /**
255: * Logs that a given message was sent to a room as part of a conversation. Every message sent
256: * to the room that is allowed to be broadcasted and that was sent either from the room itself
257: * or from an occupant will be logged.<p>
258: *
259: * Note: For performane reasons, the logged message won't be immediately saved. Instead we keep
260: * the logged messages in memory until the logging process saves them to the database. It's
261: * possible to configure the logging process to run every X milliseconds and also the number
262: * of messages to log on each execution.
263: * @see org.jivesoftware.openfire.muc.spi.MultiUserChatServerImpl#initialize(org.jivesoftware.openfire.XMPPServer)
264: *
265: * @param room the room that received the message.
266: * @param message the message to log as part of the conversation in the room.
267: * @param sender the real XMPPAddress of the sender (e.g. john@example.org).
268: */
269: void logConversation(MUCRoom room, Message message, JID sender);
270:
271: /**
272: * Notification message indicating the server that an incoming message was broadcasted
273: * to a given number of occupants.
274: *
275: * @param numOccupants number of occupants that received the message.
276: */
277: void messageBroadcastedTo(int numOccupants);
278:
279: /**
280: * Enables or disables the MUC service. When disabled the MUC service will disappear from
281: * the disco#items list. Moreover, service discovery features will be disabled.
282: *
283: * @param enabled true if the service is enabled.
284: * @param persistent true if the new setting will persist accorss restarts.
285: */
286: void enableService(boolean enabled, boolean persistent);
287:
288: /**
289: * Returns true if the MUC service is available. Use {@link #enableService(boolean, boolean)} to
290: * enable or disable the service.
291: *
292: * @return true if the MUC service is available.
293: */
294: boolean isServiceEnabled();
295:
296: /**
297: * Registers a listener to receive events.
298: *
299: * @param listener the listener.
300: */
301: void addListener(MUCEventListener listener);
302:
303: /**
304: * Unregisters a listener to receive events.
305: *
306: * @param listener the listener.
307: */
308: void removeListener(MUCEventListener listener);
309: }
|