OF-606: AlternateJID should be optional, not required, when destroying a room....

OF-606: AlternateJID should be optional, not required, when destroying a room. I've added some Javadoc that explains what arguments are, and what arguments are not optional.

git-svn-id: http://svn.igniterealtime.org/svn/repos/openfire/trunk@13424 b35dd754-fafc-0310-a699-88a17e54d16e

src/java/org/jivesoftware/openfire/muc/MUCRoom.java

@@ -79,8 +79,7 @@ public interface MUCRoom extends Externalizable, Result {
      * Sets a new room ID if the room has just been saved to the database or sets the saved ID of
      * the room in the database while loading the room. 
      * 
-     * @param roomID the saved ID of the room in the DB or a new one if the room is being saved to 
-     * the DB.
+     * @param roomID the saved ID of the room in the DB or a new one if the room is being saved to the DB.
      */
     void setID(long roomID);
 
@@ -94,7 +93,7 @@ public interface MUCRoom extends Externalizable, Result {
     /**
      * Sets the multi user chat service the room is attached to.
      *
-     * @param service The MultiUserChatService that the room is attached to.
+     * @param service The MultiUserChatService that the room is attached to (cannot be <tt>null</tt>).
      */
     void setMUCService(MultiUserChatService service);
 
@@ -108,7 +107,7 @@ public interface MUCRoom extends Externalizable, Result {
     /**
      * Sets the date when the room was created.
      *
-     * @param creationDate the date when the room was created.
+     * @param creationDate the date when the room was created (cannot be <tt>null</tt>).
      */
     void setCreationDate(Date creationDate);
 
@@ -124,7 +123,7 @@ public interface MUCRoom extends Externalizable, Result {
      * Sets the last date when the room's configuration was modified. If the room's configuration
      * was never modified then the initial value will be the same as the creation date.
      *
-     * @param modificationDate the last date when the room's configuration was modified.
+     * @param modificationDate the last date when the room's configuration was modified (cannot be <tt>null</tt>).
      */
     void setModificationDate(Date modificationDate);
 
@@ -132,8 +131,7 @@ public interface MUCRoom extends Externalizable, Result {
      * Sets the date when the last occupant left the room. A null value means that there are
      * occupants in the room at the moment.
      *
-     * @param emptyDate the date when the last occupant left the room or null if there are occupants
-     *        in the room.
+     * @param emptyDate the date when the last occupant left the room or null if there are occupants in the room (can be <tt>null</tt>).
      */
     void setEmptyDate(Date emptyDate);
 
@@ -156,7 +154,7 @@ public interface MUCRoom extends Externalizable, Result {
     /**
      * Obtain the role of a given user by nickname.
      *
-     * @param nickname The nickname of the user you'd like to obtain
+     * @param nickname The nickname of the user you'd like to obtain (cannot be <tt>null</tt>)
      * @return The user's role in the room
      * @throws UserNotFoundException If there is no user with the given nickname
      */
@@ -166,7 +164,7 @@ public interface MUCRoom extends Externalizable, Result {
      * Obtain the roles of a given user in the room by his bare JID. A user can have several roles,
      * one for each client resource from which the user has joined the room. 
      *
-     * @param jid The bare jid of the user you'd like to obtain
+     * @param jid The bare jid of the user you'd like to obtain  (cannot be <tt>null</tt>).
      * @return The user's roles in the room
      * @throws UserNotFoundException If there is no user with the given nickname
      */
@@ -176,7 +174,7 @@ public interface MUCRoom extends Externalizable, Result {
      * Returns the role of a given user in the room by his full JID or <tt>null</tt>
      * if no role was found for the specified user.
      *
-     * @param jid The full jid of the user you'd like to obtain
+     * @param jid The full jid of the user you'd like to obtain  (cannot be <tt>null</tt>).
      * @return The user's role in the room or null if not found.
      */
     MUCRole getOccupantByFullJID(JID jid);
@@ -198,7 +196,7 @@ public interface MUCRoom extends Externalizable, Result {
     /**
      * Determine if a given nickname is taken.
      *
-     * @param nickname The nickname of the user you'd like to obtain
+     * @param nickname The nickname of the user you'd like to obtain  (cannot be <tt>null</tt>).
      * @return True if a nickname is taken
      */
     boolean hasOccupant(String nickname);
@@ -206,7 +204,7 @@ public interface MUCRoom extends Externalizable, Result {
     /**
      * Returns the reserved room nickname for the bare JID or null if none.
      * 
-     * @param bareJID The bare jid of the user of which you'd like to obtain his reserved nickname.
+     * @param jid The bare jid of the user of which you'd like to obtain his reserved nickname (cannot be <tt>null</tt>).
      * @return the reserved room nickname for the bare JID or null if none.
      */
     String getReservedNickname(JID jid);
@@ -217,7 +215,7 @@ public interface MUCRoom extends Externalizable, Result {
      * 
      * Note: Prerequisite - A lock must already be obtained before sending this message.
      *  
-     * @param bareJID The bare jid of the user of which you'd like to obtain his affiliation.
+     * @param bareJID The bare jid of the user of which you'd like to obtain his affiliation (cannot be <tt>null</tt>).
      * @return the affiliation state of the user in the room.
      */
     MUCRole.Affiliation getAffiliation(JID bareJID);
@@ -225,13 +223,13 @@ public interface MUCRoom extends Externalizable, Result {
     /**
      * Joins the room using the given nickname.
      *
-     * @param nickname       The nickname the user wants to use in the chatroom.
+     * @param nickname       The nickname the user wants to use in the chatroom  (cannot be <tt>null</tt>).
      * @param password       The password provided by the user to enter the chatroom or null if none.
      * @param historyRequest The amount of history that the user request or null meaning default.
-     * @param user           The user joining.
-     * @param presence       The presence sent by the user to join the room.
+     * @param user           The user joining (cannot be <tt>null</tt>).
+     * @param presence       The presence sent by the user to join the room (cannot be <tt>null</tt>).
      * @return The role created for the user.
-     * @throws UnauthorizedException         If the user doesn't have permision to join the room.
+     * @throws UnauthorizedException         If the user doesn't have permission to join the room.
      * @throws UserAlreadyExistsException    If the nickname is already taken.
      * @throws RoomLockedException           If the user is trying to join a locked room.
      * @throws ForbiddenException            If the user is an outcast.
@@ -251,7 +249,7 @@ public interface MUCRoom extends Externalizable, Result {
     /**
      * Remove a member from the chat room.
      *
-     * @param leaveRole room occupant that left the room.
+     * @param leaveRole room occupant that left the room  (cannot be <tt>null</tt>).
      */
     void leaveRoom(MUCRole leaveRole);
 
@@ -260,15 +258,15 @@ public interface MUCRoom extends Externalizable, Result {
      * "unavailable" whose "from" attribute will be the occupant's nickname that the user knows he 
      * or she has been removed from the room.
      * 
-     * @param alternateJID the alternate JID. Commonly used to provide a replacement room.
-     * @param reason the reason why the room was destroyed.
+     * @param alternateJID an optional alternate JID. Commonly used to provide a replacement room. (can be <tt>null</tt>)
+     * @param reason an optional reason why the room was destroyed (can be <tt>null</tt>).
      */
     void destroyRoom(JID alternateJID, String reason);
 
     /**
      * Create a new presence in this room for the given role.
      *
-     * @param type Type of presence to create.
+     * @param type Type of presence to create (cannot be <tt>null</tt>).
      * @return The new presence
      * @throws UnauthorizedException If the user doesn't have permission to leave the room
      */
@@ -278,7 +276,7 @@ public interface MUCRoom extends Externalizable, Result {
      * Broadcast a given message to all members of this chat room. The sender is always set to 
      * be the chatroom.
      *
-     * @param msg The message to broadcast
+     * @param msg The message to broadcast (cannot be <tt>null</tt>)
      */
     void serverBroadcast(String msg);
     
@@ -292,17 +290,17 @@ public interface MUCRoom extends Externalizable, Result {
     /**
      * Adds a new user to the list of owners. The user is the actual creator of the room. Only the
      * MultiUserChatServer should use this method. Regular owners list maintenance MUST be done
-     * through {@link #addOwner(String,MUCRole)}.
+     * through {@link #addOwner(JID jid,MUCRole)}.
      * 
-     * @param bareJID The bare JID of the user to add as owner.
+     * @param bareJID The bare JID of the user to add as owner (cannot be <tt>null</tt>).
      */
     public void addFirstOwner(JID bareJID);
 
     /**
      * Adds a new user to the list of owners.
      * 
-     * @param jid The JID of the user to add as owner.
-     * @param senderRole the role of the user that is trying to modify the owners list.
+     * @param jid The JID of the user to add as owner (cannot be <tt>null</tt>).
+     * @param senderRole the role of the user that is trying to modify the owners list (cannot be <tt>null</tt>).
      * @return the list of updated presences of all the client resources that the client used to
      *         join the room.
      * @throws ForbiddenException If the user is not allowed to modify the owner list.
@@ -312,8 +310,8 @@ public interface MUCRoom extends Externalizable, Result {
     /**
      * Adds a list of users to the list of owners.
      *
-     * @param newOwners the list of bare JIDs of the users to add to the list of existing owners.
-     * @param senderRole the role of the user that is trying to modify the owners list.
+     * @param newOwners the list of bare JIDs of the users to add to the list of existing owners (cannot be <tt>null</tt>).
+     * @param senderRole the role of the user that is trying to modify the owners list (cannot be <tt>null</tt>).
      * @return the list of updated presences of all the clients resources that the clients used to
      *         join the room.
      * @throws ForbiddenException If the user is not allowed to modify the owner list.
@@ -324,8 +322,8 @@ public interface MUCRoom extends Externalizable, Result {
     /**
      * Adds a list of users to the list of admins.
      *
-     * @param newAdmins the list of bare JIDs of the users to add to the list of existing admins.
-     * @param senderRole the role of the user that is trying to modify the admins list.
+     * @param newAdmins the list of bare JIDs of the users to add to the list of existing admins (cannot be <tt>null</tt>).
+     * @param senderRole the role of the user that is trying to modify the admins list (cannot be <tt>null</tt>).
      * @return the list of updated presences of all the clients resources that the clients used to
      *         join the room.
      * @throws ForbiddenException If the user is not allowed to modify the admin list.
@@ -337,8 +335,8 @@ public interface MUCRoom extends Externalizable, Result {
     /**
      * Adds a new user to the list of admins.
      * 
-     * @param jid The JID of the user to add as admin.
-     * @param senderRole The role of the user that is trying to modify the admins list.
+     * @param jid The JID of the user to add as admin (cannot be <tt>null</tt>).
+     * @param senderRole The role of the user that is trying to modify the admins list (cannot be <tt>null</tt>).
      * @return the list of updated presences of all the client resources that the client used to
      *         join the room.
      * @throws ForbiddenException If the user is not allowed to modify the admin list.
@@ -350,9 +348,9 @@ public interface MUCRoom extends Externalizable, Result {
     /**
      * Adds a new user to the list of members.
      * 
-     * @param jid The JID of the user to add as a member.
+     * @param jid The JID of the user to add as a member (cannot be <tt>null</tt>).
      * @param nickname The reserved nickname of the member for the room or null if none.
-     * @param senderRole the role of the user that is trying to modify the members list.
+     * @param senderRole the role of the user that is trying to modify the members list (cannot be <tt>null</tt>).
      * @return the list of updated presences of all the client resources that the client used to
      *         join the room.
      * @throws ForbiddenException If the user is not allowed to modify the members list.
@@ -365,9 +363,9 @@ public interface MUCRoom extends Externalizable, Result {
     /**
      * Adds a new user to the list of outcast users.
      * 
-     * @param jid The JID of the user to add as an outcast.
-     * @param reason The reason why the user was banned.
-     * @param senderRole The role of the user that initiated the ban.
+     * @param jid The JID of the user to add as an outcast (cannot be <tt>null</tt>).
+     * @param reason an optional reason why the user was banned (can be <tt>null</tt>).
+     * @param senderRole The role of the user that initiated the ban (cannot be <tt>null</tt>).
      * @return the list of updated presences of all the client resources that the client used to
      *         join the room.
      * @throws NotAllowedException Thrown if trying to ban an owner or an administrator.
@@ -380,8 +378,8 @@ public interface MUCRoom extends Externalizable, Result {
     /**
      * Removes the user from all the other affiliation list thus giving the user a NONE affiliation.
      * 
-     * @param jid The JID of the user to keep with a NONE affiliation.
-     * @param senderRole The role of the user that set the affiliation to none.
+     * @param jid The JID of the user to keep with a NONE affiliation (cannot be <tt>null</tt>).
+     * @param senderRole The role of the user that set the affiliation to none (cannot be <tt>null</tt>).
      * @return the list of updated presences of all the client resources that the client used to
      *         join the room or null if none was updated.
      * @throws ForbiddenException If the user is not allowed to modify the none list.
@@ -394,8 +392,8 @@ public interface MUCRoom extends Externalizable, Result {
      * Changes the role of the user within the room to moderator. A moderator is allowed to kick
      * occupants as well as granting/revoking voice from occupants.
      *
-     * @param fullJID The full JID of the occupant to give moderator privileges.
-     * @param senderRole The role of the user that is granting moderator privileges to an occupant.
+     * @param fullJID The full JID of the occupant to give moderator privileges (cannot be <tt>null</tt>).
+     * @param senderRole The role of the user that is granting moderator privileges to an occupant (cannot be <tt>null</tt>).
      * @return the updated presence of the occupant or <tt>null</tt> if the JID does not belong to
      *         an existing occupant.
      * @throws ForbiddenException If the user is not allowed to grant moderator privileges.
@@ -406,10 +404,10 @@ public interface MUCRoom extends Externalizable, Result {
      * Changes the role of the user within the room to participant. A participant is allowed to send
      * messages to the room (i.e. has voice) and may change the room's subject.
      *
-     * @param fullJID The full JID of the occupant to give participant privileges.
+     * @param fullJID The full JID of the occupant to give participant privileges (cannot be <tt>null</tt>).
      * @param reason The reason why participant privileges were gave to the user or <tt>null</tt>
      *        if none.
-     * @param senderRole The role of the user that is granting participant privileges to an occupant.
+     * @param senderRole The role of the user that is granting participant privileges to an occupant (cannot be <tt>null</tt>).
      * @return the updated presence of the occupant or <tt>null</tt> if the JID does not belong to
      *         an existing occupant.
      * @throws NotAllowedException If trying to change the moderator role to an owner or an admin.
@@ -423,8 +421,8 @@ public interface MUCRoom extends Externalizable, Result {
      * is not allowed to send messages to the room (i.e. does not has voice) and may invite others
      * to the room.
      *
-     * @param jid the full JID of the occupant to change to visitor.
-     * @param senderRole the role of the user that is changing the role to visitor.
+     * @param jid the full JID of the occupant to change to visitor (cannot be <tt>null</tt>).
+     * @param senderRole the role of the user that is changing the role to visitor (cannot be <tt>null</tt>).
      * @return the updated presence of the occupant or <tt>null</tt> if the JID does not belong to
      *         an existing occupant.
      * @throws NotAllowedException if trying to change the moderator role to an owner or an admin.
@@ -454,18 +452,18 @@ public interface MUCRoom extends Externalizable, Result {
     /**
      * An event callback fired whenever an occupant updated his presence in the chatroom.
      *
-     * @param occupantRole occupant that changed his presence in the room.
-     * @param newPresence presence sent by the occupant.
+     * @param occupantRole occupant that changed his presence in the room (cannot be <tt>null</tt>).
+     * @param newPresence presence sent by the occupant (cannot be <tt>null</tt>).
      */
     public void presenceUpdated(MUCRole occupantRole, Presence newPresence);
 
     /**
      * An event callback fired whenever an occupant changes his nickname within the chatroom.
      *
-     * @param occupantRole occupant that changed his nickname in the room.
-     * @param newPresence presence sent by the occupant with the new nickname.
-     * @param oldNick old nickname within the room.
-     * @param newNick new nickname within the room.
+     * @param occupantRole occupant that changed his nickname in the room (cannot be <tt>null</tt>).
+     * @param newPresence presence sent by the occupant with the new nickname (cannot be <tt>null</tt>).
+     * @param oldNick old nickname within the room (cannot be <tt>null</tt>).
+     * @param newNick new nickname within the room (cannot be <tt>null</tt>).
      */
     public void nicknameChanged(MUCRole occupantRole, Presence newPresence, String oldNick, String newNick);
     
@@ -476,8 +474,8 @@ public interface MUCRoom extends Externalizable, Result {
      * 
      * The new subject will be added to the history of the room.
      *  
-     * @param packet the sent packet to change the room's subject.
-     * @param role the role of the user that is trying to change the subject.
+     * @param packet the sent packet to change the room's subject (cannot be <tt>null</tt>).
+     * @param role the role of the user that is trying to change the subject (cannot be <tt>null</tt>).
      * @throws ForbiddenException If the user is not allowed to change the subject.
      */
     public void changeSubject(Message packet, MUCRole role) throws ForbiddenException;
@@ -493,7 +491,7 @@ public interface MUCRoom extends Externalizable, Result {
      * Sets the last subject that some occupant set to the room. This message will only be used
      * when loading a room from the database. 
      * 
-     * @param subject the last known subject of the room.
+     * @param subject the last known subject of the room (cannot be <tt>null</tt>).
      */
     public void setSubject(String subject);
 
@@ -502,8 +500,8 @@ public interface MUCRoom extends Externalizable, Result {
      * to occupants with a role of participant or higher. In an unmoderated room, any occupant can
      * send a message to all other occupants.
      * 
-     * @param message The message to send.
-     * @param senderRole the role of the user that is trying to send a public message.
+     * @param message The message to send (cannot be <tt>null</tt>).
+     * @param senderRole the role of the user that is trying to send a public message (cannot be <tt>null</tt>).
      * @throws ForbiddenException If the user is not allowed to send a public message (i.e. does not
      *             have voice in the room).
      */
@@ -524,9 +522,9 @@ public interface MUCRoom extends Externalizable, Result {
      * Kicks a user from the room. If the user was in the room, the returned updated presence will
      * be sent to the remaining occupants. 
      * 
-     * @param fullJID The full JID of the kicked user.
-     * @param actorJID The JID of the actor that initiated the kick.
-     * @param reason The reason why the user was kicked.
+     * @param fullJID The full JID of the kicked user  (cannot be <tt>null</tt>).
+     * @param actorJID The JID of the actor that initiated the kick (cannot be <tt>null</tt>).
+     * @param reason An optional reason why the user was kicked (can be <tt>null</tt>).
      * @return the updated presence of the kicked user or null if the user was not in the room.
      * @throws NotAllowedException Thrown if trying to ban an owner or an administrator.
      */

src/java/org/jivesoftware/openfire/muc/cluster/DestroyRoomRequest.java

@@ -36,8 +36,8 @@ import org.xmpp.packet.JID;
  * @author Gaston Dombiak
  */
 public class DestroyRoomRequest extends MUCRoomTask {
-    private JID alternateJID;
-    private String reason;
+    private JID alternateJID; // Is allowed to be null!
+    private String reason; // Is allowed to be null or empty!
 
     public DestroyRoomRequest() {
     }

src/java/org/jivesoftware/openfire/muc/spi/IQOwnerHandler.java

@@ -122,8 +122,12 @@ public class IQOwnerHandler {
                     }
                 }
 
-				room.destroyRoom(new JID(destroyElement.attributeValue("jid")),
-						destroyElement.elementTextTrim("reason"));
+                JID alternateJID = null;
+                final String jid = destroyElement.attributeValue("jid");
+                if (jid != null) {
+                    alternateJID = new JID(jid);
+                }
+                room.destroyRoom(alternateJID, destroyElement.elementTextTrim("reason"));
             }
             else {
                 List<Element> itemsList = element.elements("item");