Package org.jivesoftware.openfire.muc

Interface MultiUserChatService

  • All Superinterfaces:
    org.xmpp.component.Component
    All Known Implementing Classes:
    MultiUserChatServiceImpl
    public interface MultiUserChatService
extends org.xmpp.component.Component
    Manages groupchat conversations, chatrooms, and users. This class is designed to operate independently from the rest of the Jive server infrastructure. This theoretically allows deployment of the groupchat on a separate server from the main IM server.
    Author:
    Gaston Dombiak

    • Method Detail

      • getServiceDomain

        String getServiceDomain()
        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.
        Returns:
        the chat server domain (service name + host name).

      • getServiceName

        String getServiceName()
        Returns the subdomain of the chat service.
        Returns:
        the subdomain of the chat service.

      • getSysadmins

        Collection<org.xmpp.packet.JID> getSysadmins()
        Returns the collection of JIDs that are system administrators of the MUC service. A sysadmin has the same permissions as a room owner.
        Returns:
        a list of user/group JIDs.

      • isSysadmin

        boolean isSysadmin​(org.xmpp.packet.JID bareJID)
        Validates the given JID as a MUC service administrator.
        Parameters:
        bareJID - the bare JID of the user
        Returns:
        true if the given JID is a MUC service administrator

      • addSysadmin

        void addSysadmin​(org.xmpp.packet.JID userJID)
        Adds a new system administrator of the MUC service. A sysadmin has the same permissions as a room owner.
        Parameters:
        userJID - the bare JID of the new user/group to add as a system administrator.

      • addSysadmins

        void addSysadmins​(Collection<org.xmpp.packet.JID> userJIDs)
        Adds multiple system administrators for the MUC service. A sysadmin has the same permissions as a room owner.
        Parameters:
        userJIDs - the JIDs of the new users/groups to add as a system administrator.

      • removeSysadmin

        void removeSysadmin​(org.xmpp.packet.JID userJID)
        Removes a system administrator of the MUC service.
        Parameters:
        userJID - the bare JID of the user/group to remove from the list.

      • isPasswordRequiredForSysadminsToJoinRoom

        default boolean isPasswordRequiredForSysadminsToJoinRoom()
        Returns true when a system administrator of the MUC service can join a password-protected room, without supplying the password.
        Returns:
        false if a sysadmin can join a password-protected room without a password, otherwise true.

      • setPasswordRequiredForSysadminsToJoinRoom

        default void setPasswordRequiredForSysadminsToJoinRoom​(boolean isRequired)
        Sets if a system administrator of the MUC service can join a password-protected room, without supplying the password.
        Parameters:
        isRequired - false if a sysadmin is allowed to join a password-protected room without a password, otherwise true.

      • isRoomCreationRestricted

        boolean isRoomCreationRestricted()
        Returns false if anyone can create rooms or true if only the returned JIDs in getUsersAllowedToCreate are allowed to create rooms.
        Returns:
        true if only some JIDs are allowed to create rooms.

      • setRoomCreationRestricted

        void setRoomCreationRestricted​(boolean roomCreationRestricted)
        Sets if anyone can create rooms. When set to true, users are allowed to create rooms only when isAllRegisteredUsersAllowedToCreate or getUsersAllowedToCreate (or both) allow them to.
        Parameters:
        roomCreationRestricted - whether anyone can create rooms or not.

      • isAllRegisteredUsersAllowedToCreate

        boolean isAllRegisteredUsersAllowedToCreate()
        Sets if all registered users of Openfire are allowed to create rooms. When true, anonymous users and users from other domains (through federation) are initially prohibited from creating rooms, but can still be allowed by registering their JIDs in addUserAllowedToCreate.
        Returns:
        true if all registered users are allowed to create rooms.

      • setAllRegisteredUsersAllowedToCreate

        void setAllRegisteredUsersAllowedToCreate​(boolean allow)
        Sets if all registered users of Openfire are allowed to create rooms.
        Parameters:
        allow - whether all registered users can create rooms.

      • getUsersAllowedToCreate

        Collection<org.xmpp.packet.JID> getUsersAllowedToCreate()
        Returns the collection of JIDs that are allowed to create MUC rooms. When isAllRegisteredUsersAllowedToCreate, this method will not return a JID of every user in the system.
        Returns:
        a list of user/group JIDs.

      • addUserAllowedToCreate

        void addUserAllowedToCreate​(org.xmpp.packet.JID userJID)
        Adds a new user/group to the list of JIDs that are allowed to create MUC rooms.
        Parameters:
        userJID - the JID of the new user/group to add to list.

      • addUsersAllowedToCreate

        void addUsersAllowedToCreate​(Collection<org.xmpp.packet.JID> userJIDs)
        Adds new users/groups to the list of JIDs that are allowed to create MUC rooms.
        Parameters:
        userJIDs - collection of JIDs for users/groups to add to list.

      • removeUserAllowedToCreate

        void removeUserAllowedToCreate​(org.xmpp.packet.JID userJID)
        Removes a user/group from list of JIDs that are allowed to create MUC rooms.
        Parameters:
        userJID - the JID of the user/group to remove from the list.

      • removeUsersAllowedToCreate

        void removeUsersAllowedToCreate​(Collection<org.xmpp.packet.JID> userJIDs)
        Removes users/groups from list of JIDs that are allowed to create MUC rooms.
        Parameters:
        userJIDs - collection of JIDs of users/groups to remove from the list.

      • setIdleUserTaskInterval

        void setIdleUserTaskInterval​(@Nonnull
                             Duration duration)
        Sets the period of the fixed-delay execution of tasks by the Timer whose main responsibility is to process 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.
        Parameters:
        duration - The fixed-delay interval in which idle checks need to be performed.
        See Also:
        getIdleUserKickThreshold(), getIdleUserPingThreshold()

      • getIdleUserTaskInterval

        @Nonnull
Duration getIdleUserTaskInterval()
        Returns the period of fixed-delay executions of tasks that operate on idle users.
        Returns:
        The fixed-delay interval in which idle checks need to be performed.

      • setIdleUserKickThreshold

        void setIdleUserKickThreshold​(@Nullable
                              Duration duration)
        Sets the duration that 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. Set to null to disable the feature.
        Parameters:
        duration - the amount of time to wait before considering a user idle.

      • getIdleUserKickThreshold

        @Nullable
Duration getIdleUserKickThreshold()
        Returns the duration that 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. Returns null if the feature is disabled.
        Returns:
        the amount of time to wait before considering a user idle.

      • setIdleUserPingThreshold

        void setIdleUserPingThreshold​(@Nullable
                              Duration duration)
        Sets the duration that a user must be idle before he/she gets pinged by the room, to determine if the user is a 'ghost user'. By idle we mean that the user didn't send any message to any group chat room. Set to null to disable the feature.
        Parameters:
        duration - the amount of time to wait before considering a user idle.

      • getIdleUserPingThreshold

        @Nullable
Duration getIdleUserPingThreshold()
        Returns the duration that a user must be idle before he/she gets pinged by the rooms that they're an occupant of (to determine if they're a 'ghost user'). By idle we mean that the user didn't send any message to any group chat room. Returns null if the feature is disabled.
        Returns:
        the amount of time to wait before considering a user idle.

      • getArchiver

        Archiver<?> getArchiver()

      • getLogMaxConversationBatchSize

        default int getLogMaxConversationBatchSize()
        Returns the maximum number of messages to save to the database on each run of the archiving process.
        Returns:
        the maximum number of messages to save to the database on each run of the archiving process.

      • setLogMaxConversationBatchSize

        default void setLogMaxConversationBatchSize​(int size)
        Sets the maximum number of messages to save to the database on each run of the archiving process. Even though the saving of queued conversations takes place in another thread it is not recommended specifying a big number.
        Parameters:
        size - the maximum number of messages to save to the database on each run of the archiving process.

      • getLogMaxBatchInterval

        default Duration getLogMaxBatchInterval()
        Returns the maximum time allowed to elapse between writing archive entries to the database.
        Returns:
        the maximum time allowed to elapse between writing archive entries to the database.

      • setLogMaxBatchInterval

        default void setLogMaxBatchInterval​(Duration interval)
        Sets the maximum time allowed to elapse between writing archive batches to the database.
        Parameters:
        interval - the maximum time allowed to elapse between writing archive batches to the database.

      • getLogBatchGracePeriod

        default Duration getLogBatchGracePeriod()
        Returns the maximum time to wait for a next incoming entry before writing the batch to the database.
        Returns:
        the maximum time to wait for a next incoming entry before writing the batch to the database.

      • setLogBatchGracePeriod

        default void setLogBatchGracePeriod​(Duration interval)
        Sets the maximum time to wait for a next incoming entry before writing the batch to the database.
        Parameters:
        interval - the maximum time to wait for a next incoming entry before writing the batch to the database.

      • getHistoryStrategy

        HistoryStrategy getHistoryStrategy()
        Obtain the server-wide default message history settings.
        Returns:
        The message history strategy defaults for the server.

      • canDiscoverRoom

        boolean canDiscoverRoom​(MUCRoom room,
                        org.xmpp.packet.JID entity)
        Checks if the a particular entity is allowed to discover the room's existence.
        Parameters:
        room - The room to be discovered (cannot be null).
        entity - The JID of the entity (cannot be null).
        Returns:
        true if the entity can discover the room, otherwise false.

      • getChatRoomLock

        @Nonnull
Lock getChatRoomLock​(@Nonnull
                     String roomName)
        Generates a mutex object that controls cluster-wide access to a MUCRoom instance that represents the room in this service identified by the provided name. The lock, once returned, is not acquired/set.
        Parameters:
        roomName - Name of the room for which to return a lock.
        Returns:
        The lock (which has not been set yet).

      • syncChatRoom

        void syncChatRoom​(@Nonnull
                  MUCRoom room)
        Makes available the current state of the provided MUCRoom instance to all nodes in the Openfire cluster (if the local server is part of such a cluster). This method should be used whenever a MUCRoom instance has been changed.
        Parameters:
        room - The room for which to persist state changes across the Openfire cluster.

      • getChatRoom

        @Nonnull
MUCRoom getChatRoom​(@Nonnull
                    String roomName,
                    @Nonnull
                    org.xmpp.packet.JID userjid)
             throws NotAllowedException
        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. Note that when obtaining a room instance using this method, the caller should take responsibility to make sure that any changes to the instance will become visible to other cluster nodes (which is done by invoking syncChatRoom(MUCRoom). Where appropriate, the caller should apply mutex (as returned by getChatRoomLock(String)) to control concurrent access to the returned instance.
        Parameters:
        roomName - Name of the room to get.
        userjid - The user's normal jid, not the chat nickname jid.
        Returns:
        The chatroom for the given name.
        Throws:
        NotAllowedException - If the caller doesn't have permission to create a new room.
        See Also:
        syncChatRoom(MUCRoom)

      • getChatRoom

        @Nullable
MUCRoom getChatRoom​(@Nonnull
                    String roomName)
        Obtains a chatroom by name. If the chatroom does not exists then null will be returned. Note that when obtaining a room instance using this method, the caller should take responsibility to make sure that any changes to the instance will become visible to other cluster nodes (which is done by invoking syncChatRoom(MUCRoom). Where appropriate, the caller should apply a mutex (as returned by getChatRoomLock(String)) to control concurrent access to the returned instance.
        Parameters:
        roomName - Name of the room to get.
        Returns:
        The chatroom for the given name or null if the room does not exists.
        See Also:
        syncChatRoom(MUCRoom)

      • getActiveChatRooms

        List<MUCRoom> getActiveChatRooms()
        Returns a list with a snapshot of all the rooms in the server that are actively loaded in memory.
        Returns:
        a list with a snapshot of rooms.

      • getAllRoomNames

        Set<String> getAllRoomNames()
        Returns a list of names of all the rooms in the server (i.e. persistent or not, in memory or not).
        Returns:
        All room names

      • hasChatRoom

        boolean hasChatRoom​(String roomName)
        Returns true if the server includes a chatroom with the requested name.
        Parameters:
        roomName - the name of the chatroom to check.
        Returns:
        true if the server includes a chatroom with the requested name.

      • removeChatRoom

        void removeChatRoom​(String roomName)
        Removes the room associated with the given name.
        Parameters:
        roomName - The room to remove.

      • getOccupants

        Collection<MUCRole> getOccupants​(org.xmpp.packet.JID user)
        Returns the list of MUCRole in all rooms for the specified user's session. Note that a method by this name was introduced in Openfire 4.9.0, but will be refactored as part of the 4.10.0 release of Openfire, as the type of the returned class will be modified in that release.
        Parameters:
        user - the full JID that identifies the session of the user.
        Returns:
        the list of occupants in all rooms for the specified user's session.

      • getMUCRoles

        @Deprecated(since="4.9.0",
            forRemoval=true)
default Collection<MUCRole> getMUCRoles​(org.xmpp.packet.JID user)
        Deprecated, for removal: This API element is subject to removal in a future version.
        Replaced by getOccupants(JID)
        Returns the list of MUCRole in all rooms for the specified user's session.
        Parameters:
        user - the full JID that identifies the session of the user.
        Returns:
        the list of MUCRoles in all rooms for the specified user's session.

      • getTotalChatTime

        long getTotalChatTime()
        Returns the total chat time of all rooms combined.
        Returns:
        total chat time in milliseconds.

      • getNumberChatRooms

        int getNumberChatRooms()
        Returns the number of existing rooms in the server (i.e. persistent or not, in memory or not).
        Returns:
        the number of existing rooms in the server.

      • getNumberConnectedUsers

        int getNumberConnectedUsers()
        Returns the total number of occupants in all rooms.
        Returns:
        the count of all occupants.

      • getNumberRoomOccupants

        int getNumberRoomOccupants()
        Retuns the total number of users that have joined in all rooms in the server.
        Returns:
        the number of existing rooms in the server.

      • getIncomingMessageCount

        long getIncomingMessageCount​(boolean resetAfter)
        Returns the total number of incoming messages since last reset.
        Parameters:
        resetAfter - True if you want the counter to be reset after results returned.
        Returns:
        the number of incoming messages through the service.

      • getOutgoingMessageCount

        long getOutgoingMessageCount​(boolean resetAfter)
        Returns the total number of outgoing messages since last reset.
        Parameters:
        resetAfter - True if you want the counter to be reset after results returned.
        Returns:
        the number of outgoing messages through the service.

      • logConversation

        void logConversation​(MUCRoom room,
                     org.xmpp.packet.Message message,
                     org.xmpp.packet.JID sender)
        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.

        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.

        Parameters:
        room - the room that received the message.
        message - the message to log as part of the conversation in the room.
        sender - the real XMPPAddress of the sender (e.g. john@example.org).
        See Also:
        MultiUserChatServiceImpl.initialize(org.jivesoftware.openfire.XMPPServer)

      • messageBroadcastedTo

        void messageBroadcastedTo​(int numOccupants)
        Notification message indicating the server that an incoming message was broadcasted to a given number of occupants.
        Parameters:
        numOccupants - number of occupants that received the message.

      • enableService

        void enableService​(boolean enabled,
                   boolean persistent)
        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.
        Parameters:
        enabled - true if the service is enabled.
        persistent - true if the new setting will persist across restarts.

      • isServiceEnabled

        boolean isServiceEnabled()
        Returns true if the MUC service is available. Use enableService(boolean, boolean) to enable or disable the service.
        Returns:
        true if the MUC service is available.

      • isHidden

        boolean isHidden()
        Returns true if the MUC service is a hidden, externally managed, service. This is typically 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.
        Returns:
        true if the MUC service is hidden and externally managed.

      • addIQHandler

        void addIQHandler​(IQHandler handler)
        Add a IQHandler to MUC rooms and services. If the IQHandler only supports one or other, it should quietly ignore it.
        Parameters:
        handler - the IQ handler to add

      • removeIQHandler

        void removeIQHandler​(IQHandler handler)

      • addExtraFeature

        void addExtraFeature​(String feature)
        Adds an extra Disco feature to the list of features returned for the conference service.
        Parameters:
        feature - Feature to add.

      • removeExtraFeature

        void removeExtraFeature​(String feature)
        Removes an extra Disco feature from the list of features returned for the conference service.
        Parameters:
        feature - Feature to remove.

      • addExtraIdentity

        void addExtraIdentity​(String category,
                      String name,
                      String type)
        Adds an extra Disco identity to the list of identities returned for the conference service.
        Parameters:
        category - Category for identity. e.g. conference
        name - Descriptive name for identity. e.g. Public Chatrooms
        type - Type for identity. e.g. text

      • removeExtraIdentity

        void removeExtraIdentity​(String name)
        Removes an extra Disco identity from the list of identities returned for the conference service.
        Parameters:
        name - Name of identity to remove.

      • setMUCDelegate

        void setMUCDelegate​(MUCEventDelegate delegate)
        Sets the MUC event delegate handler for this service.
        Parameters:
        delegate - Handler for MUC events.

      • getMUCDelegate

        MUCEventDelegate getMUCDelegate()
        Gets the MUC event delegate handler for this service.
        Returns:
        Handler for MUC events (delegate)