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 MUCUser currently may use in a particular room. Each MUCRole defines the relationship between a MUCRoom and a MUCUser. MUCUsers can play different roles in different chat rooms.
    Author:
    Gaston Dombiak
    See Also:
    Serialized Form

    • Nested Class Summary

      Nested Classes 
      Modifier and Type Class Description
      static class  MUCRole.Affiliation
      A long-lived association or connection with a room.
      static class  MUCRole.Role
      A temporary position or privilege level within a room, distinct from a user's long-lived affiliation with the room.

    • Constructor Summary

      Constructors 
      Constructor Description
      MUCRole()
      This constructor is provided to comply with the Externalizable interface contract.
      MUCRole​(MUCRoom chatroom, String nickname, MUCRole.Role role, MUCRole.Affiliation affiliation, org.xmpp.packet.JID userJid, org.xmpp.packet.Presence presence)
      Create a new role.

    • 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 role. Note that whenever a new instance of MUCRole is created to reflect a new relation between an end-user and a MUC room, it is typically needed to register the same relation by adding the name of the chatroom to the collection of room names in MUCUser#roomNames. It is the responsibility of the caller to ensure that this is done.
        Parameters:
        chatroom - the room the role is valid in.
        nickname - the nickname of the user in the role.
        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 in the role.
        presence - the presence sent by the user to join the room.

    • Method Detail

      • createRoomRole

        public static MUCRole createRoomRole​(@Nonnull
                                     MUCRoom room)
        An empty role that represents the room itself in the chatroom. Chatrooms need to be able to speak (server messages) and so must have their own role in the chatroom.
        Parameters:
        room - The room for which to return a role.
        Returns:
        The role representing the room.

      • getPresence

        public org.xmpp.packet.Presence getPresence()
        Obtains a copy of the current presence status of a user in a chatroom. The 'from' address of the presence stanza is guaranteed to reflect the room role of this role.
        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 user's role.
        Returns:
        The chatroom hosting this role.

      • getRoleAddress

        public org.xmpp.packet.JID getRoleAddress()
        Obtain the XMPPAddress representing this role in a room: room@server/nickname
        Returns:
        The Jabber ID that represents this role in the room.

      • getUserAddress

        public org.xmpp.packet.JID getUserAddress()
        Obtain the XMPPAddress of the user that joined the room. A null null value represents the room's role.
        Returns:
        The address of the user that joined the room or null if this role belongs to the room itself.

      • getReportedFmucAddress

        public org.xmpp.packet.JID getReportedFmucAddress()
        Obtain the XMPPAddress representing this role 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