Package org.jivesoftware.openfire.muc

Class MUCRole

  • All Implemented Interfaces:
    Externalizable, Serializable, Cacheable
    public class MUCRole
extends Object
implements Cacheable, Externalizable
    Defines the permissions and actions that a user currently may use in a particular room. Each MUCRole defines the relationship between a MUCRoom and a specific user that is joined to (is an occupant of) that room. Note that a MUCRole can exist only for a user that is currently an occupant of a room. The name 'MUCRole' can be confusing, as it clashes with the XEP-defined term 'role'. MUCRole is not an equivalent of the XEP-defined term (although MUCRole.Role is).
    Author:
    Gaston Dombiak
    See Also:
    Serialized Form

    • Constructor Detail

      • MUCRole

        public MUCRole()
        This constructor is provided to comply with the Externalizable interface contract. It should not be used directly.

      • MUCRole

        public MUCRole​(MUCRoom chatroom,
               String nickname,
               MUCRole.Role role,
               MUCRole.Affiliation affiliation,
               org.xmpp.packet.JID userJid,
               org.xmpp.packet.Presence presence)
        Create a new instance.
        Parameters:
        chatroom - the room the occupant is in.
        nickname - the nickname of the user in the room.
        role - the role of the user in the room.
        affiliation - the affiliation of the user in the room.
        userJid - the 'real' JID of the user.
        presence - the presence sent by the user to join the room.

    • Method Detail

      • createRoomSelfRepresentation

        public static MUCRole createRoomSelfRepresentation​(@Nonnull
                                                   MUCRoom room)
        An empty instance that represents the room itself in the chatroom. Chatrooms need to be able to speak (server messages) and so must have data representing their own 'occupancy' in the chatroom. 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:
        room - The room for which to return an instance.
        Returns:
        The representation of the room.

      • createRoomRole

        @Deprecated(since="4.9.0",
            forRemoval=true)
public static MUCRole createRoomRole​(@Nonnull
                                     MUCRoom room)
        Deprecated, for removal: This API element is subject to removal in a future version.
        Replaced by createRoomSelfRepresentation(MUCRoom)
        An empty instance that represents the room itself in the chatroom. Chatrooms need to be able to speak (server messages) and so must have data representing their own 'occupancy' in the chatroom.
        Parameters:
        room - The room for which to return an instance.
        Returns:
        The representation of the room.

      • getPresence

        public org.xmpp.packet.Presence getPresence()
        Obtains a copy of the current presence status of an occupant of a chatroom. The 'from' address of the presence stanza is guaranteed to reflect the room address (as opposed to the real address) of the occupant..
        Returns:
        The presence of the user in the room.

      • setPresence

        public void setPresence​(org.xmpp.packet.Presence newPresence)
        Set the current presence status of a user in a chatroom.
        Parameters:
        newPresence - The presence of the user in the room.

      • setRole

        public void setRole​(MUCRole.Role newRole)
             throws NotAllowedException
        Call this method to promote or demote a user's role in a chatroom. It is common for the chatroom or other chat room members to change the role of users (a moderator promoting another user to moderator status for example). Owning ChatUsers should have their membership roles updated. A role is a temporary position or privilege level within a room, distinct from a user's long-lived affiliation with the room. A role lasts only for the duration of an occupant's visit to a room.
        Parameters:
        newRole - The new role that the user will play.
        Throws:
        NotAllowedException - Thrown if trying to change the moderator role to an owner or administrator.

      • getRole

        public MUCRole.Role getRole()
        Obtain the role state of the user. A role is a temporary position or privilege level within a room, distinct from a user's long-lived affiliation with the room. A role lasts only for the duration of an occupant's visit to a room.
        Returns:
        The role status of this user.

      • setAffiliation

        public void setAffiliation​(MUCRole.Affiliation newAffiliation)
                    throws NotAllowedException
        Call this method to promote or demote a user's affiliation in a chatroom. An affiliation is a long-lived association or connection with a room. Affiliation is distinct from role. An affiliation lasts across a user's visits to a room.
        Parameters:
        newAffiliation - the new affiliation that the user will play.
        Throws:
        NotAllowedException - thrown if trying to ban an owner or an administrator.

      • getAffiliation

        public MUCRole.Affiliation getAffiliation()
        Obtain the affiliation state of the user, which is a long-lived association or connection with a room. Affiliation is distinct from role. An affiliation lasts across a user's visits to a room.
        Returns:
        The affiliation status of this user.

      • getNickname

        public String getNickname()
        Obtain the nickname for the user in the chatroom.
        Returns:
        The user's nickname in the room or null if invisible.

      • changeNickname

        public void changeNickname​(String nickname)
        Changes the nickname of the occupant within the room to the new nickname.
        Parameters:
        nickname - the new nickname of the occupant in the room.

      • getChatRoom

        protected MUCRoom getChatRoom()
        Obtain the chat room that hosts this occupant.
        Returns:
        The chatroom hosting this occupant.

      • getOccupantJID

        public org.xmpp.packet.JID getOccupantJID()
        Returns the 'room@service/nick' by which the occupant is identified within the context of the room; contrast with getUserAddress().
        Returns:
        The Jabber ID that represents this occupant in the room.

      • getRoleAddress

        @Deprecated(since="4.9.0",
            forRemoval=true)
public org.xmpp.packet.JID getRoleAddress()
        Deprecated, for removal: This API element is subject to removal in a future version.
        Replaced by getOccupantJID()
        Returns the 'room@service/nick' by which the occupant is identified within the context of the room; contrast with getUserAddress().
        Returns:
        The Jabber ID that represents this occupant in the room.

      • getUserAddress

        public org.xmpp.packet.JID getUserAddress()
        The JID of the user (the real JID, eg: 'user@domain/desktop`) that is the occupant of a room (as represented by this instance); contrast with getOccupantJID(). A null null value is returned when this instance is a self-representation of the room.
        Returns:
        The address of the user that joined the room or null if this instance represents to the room itself.

      • getReportedFmucAddress

        public org.xmpp.packet.JID getReportedFmucAddress()
        Obtain the XMPPAddress representing this occupant in a room in context of FMUC. This typically represents the XMPPAddress as it is known locally at the joining FMUC node. For users that are joined through FMUC from a remote node, this method will return the value as reported by the joining FMUC node. For users that are in the room, but connected directly to this instance of Openfire, this method returns null, even if the room is part of an FMUC node. Users that joined through server-to-server federation (as opposed to FMUC), will not have a FMUC address. Null is returned by this method for these users.
        Returns:
        The address of the user that joined the room through FMUC from a remote domain, or null.

      • setReportedFmucAddress

        public void setReportedFmucAddress​(@Nonnull
                                   org.xmpp.packet.JID reportedFmucAddress)

      • isRemoteFmuc

        public boolean isRemoteFmuc()
        Returns true if the user is one that is in the room as a result of that user being in another room that is federated with this room, through the FMUC protocol
        Returns:
        true if this user is a user on a remote MUC room that is federated with this chatroom.

      • isVoiceOnly

        public boolean isVoiceOnly()
        Returns true if the room occupant does not want to get messages broadcast to all room occupants. This type of users are called "deaf" occupants. Deaf occupants will still be able to get private messages, presences, IQ packets or room history.

        To be a deaf occupant the initial presence sent to the room while joining the room has to include the following child element: 

         <x xmlns='http://jivesoftware.org/protocol/muc'>
     <deaf-occupant/>
 </x>
        Note that this is a custom extension to the MUC specification.
        Returns:
        true if the room occupant does not want to get messages broadcasted to all room occupants.

      • send

        public void send​(org.xmpp.packet.Packet packet)
        Sends a packet to the user. Note that sending a packet can modify it (notably, the 'to' address can be changed). If this is undesired (for example, because post-processing should not expose the modified 'to' address), then a copy of the original stanza should be provided as an argument to this method.
        Parameters:
        packet - The packet to send
        See Also:
        issue OF-2163

      • augmentOutboundStanzaWithFMUCData

        public void augmentOutboundStanzaWithFMUCData​(@Nonnull
                                              org.xmpp.packet.Packet packet)
        When sending data to a user that joined the room through FMUC (when the user is a user that is local to a remote chatroom that joined our room as a 'joining FMUC node'), then we'll need to add an 'fmuc' element to all data that we send it. The data that is to be added must include the 'from' address representing the FMUC role for the occupant that sent the stanza. We either use the reported FMUC address as passed down from other FMUC nodes, or we use the address of users connected locally to our server. This method will add an 'fmuc' child element to the stanza when the user is a user that joined through FMUC (is a member of a room that federates with the MUC room local to our server). If the provided stanza already contains an FMUC element with relevant data, this data is left unchanged.
        Parameters:
        packet - The stanza to augment

      • hashCode

        public int hashCode()
        Overrides:
        hashCode in class Object

      • getCachedSize

        public int getCachedSize()
                  throws CannotCalculateSizeException
        Description copied from interface: Cacheable
        Returns the approximate size of the Object in bytes. The size should be considered to be a best estimate of how much memory the Object occupies and may be based on empirical trials or dynamic calculations.

        Specified by:
        getCachedSize in interface Cacheable
        Returns:
        the size of the Object in bytes.
        Throws:
        CannotCalculateSizeException - if the size cannot be calculated