001/** 002 * 003 * Copyright 2003-2007 Jive Software. 004 * 005 * Licensed under the Apache License, Version 2.0 (the "License"); 006 * you may not use this file except in compliance with the License. 007 * You may obtain a copy of the License at 008 * 009 * http://www.apache.org/licenses/LICENSE-2.0 010 * 011 * Unless required by applicable law or agreed to in writing, software 012 * distributed under the License is distributed on an "AS IS" BASIS, 013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 014 * See the License for the specific language governing permissions and 015 * limitations under the License. 016 */ 017package org.jivesoftware.smackx.muc.packet; 018 019import javax.xml.namespace.QName; 020 021import org.jivesoftware.smack.packet.ExtensionElement; 022import org.jivesoftware.smack.packet.Stanza; 023import org.jivesoftware.smack.util.Objects; 024import org.jivesoftware.smack.util.XmlStringBuilder; 025 026import org.jxmpp.jid.EntityBareJid; 027 028/** 029 * A group chat invitation stanza extension, which is used to invite other 030 * users to a group chat room. To invite a user to a group chat room, address 031 * a new message to the user and set the room name appropriately, as in the 032 * following code example: 033 * 034 * <pre> 035 * Message message = new Message("user@chat.example.com"); 036 * message.setBody("Join me for a group chat!"); 037 * message.addExtension(new GroupChatInvitation("room@chat.example.com");); 038 * con.sendStanza(message); 039 * </pre> 040 * 041 * To listen for group chat invitations, use a StanzaExtensionFilter for the 042 * <code>x</code> element name and <code>jabber:x:conference</code> namespace, as in the 043 * following code example: 044 * 045 * <pre> 046 * PacketFilter filter = new StanzaExtensionFilter("x", "jabber:x:conference"); 047 * // Create a stanza collector or stanza listeners using the filter... 048 * </pre> 049 * 050 * <b>Note</b>: this protocol is outdated now that the Multi-User Chat (MUC) XEP is available 051 * (<a href="http://www.xmpp.org/extensions/jep-0045.html">XEP-45</a>). However, most 052 * existing clients still use this older protocol. Once MUC support becomes more 053 * widespread, this API may be deprecated. 054 * 055 * @author Matt Tucker 056 */ 057public class GroupChatInvitation implements ExtensionElement { 058 059 /** 060 * Element name of the stanza extension. 061 */ 062 public static final String ELEMENT = "x"; 063 064 /** 065 * Namespace of the stanza extension. 066 */ 067 public static final String NAMESPACE = "jabber:x:conference"; 068 069 public static final QName QNAME = new QName(NAMESPACE, ELEMENT); 070 071 private final EntityBareJid roomAddress; 072 private final String reason; 073 private final String password; 074 private final String thread; 075 private final boolean continueAsOneToOneChat; 076 077 /** 078 * Creates a new group chat invitation to the specified room address. 079 * GroupChat room addresses are in the form <code>room@service</code>, 080 * where <code>service</code> is the name of group chat server, such as 081 * <code>chat.example.com</code>. 082 * 083 * @param roomAddress the address of the group chat room. 084 */ 085 public GroupChatInvitation(EntityBareJid roomAddress) { 086 this(roomAddress, null, null, false, null); 087 } 088 089 /** 090 * Creates a new group chat invitation to the specified room address. 091 * GroupChat room addresses are in the form <code>room@service</code>, 092 * where <code>service</code> is the name of group chat server, such as 093 * <code>chat.example.com</code>. 094 * 095 * @param roomAddress the address of the group chat room. 096 * @param reason the purpose for the invitation 097 * @param password specifies a password needed for entry 098 * @param continueAsOneToOneChat specifies if the groupchat room continues a one-to-one chat having the designated thread 099 * @param thread the thread to continue 100 */ 101 public GroupChatInvitation(EntityBareJid roomAddress, 102 String reason, 103 String password, 104 boolean continueAsOneToOneChat, 105 String thread) { 106 this.roomAddress = Objects.requireNonNull(roomAddress); 107 this.reason = reason; 108 this.password = password; 109 this.continueAsOneToOneChat = continueAsOneToOneChat; 110 this.thread = thread; 111 } 112 113 /** 114 * Returns the purpose for the invitation. 115 * 116 * @return the address of the group chat room. 117 */ 118 public String getReason() { 119 return reason; 120 } 121 122 /** 123 * Returns the password needed for entry. 124 * 125 * @return the password needed for entry 126 */ 127 public String getPassword() { 128 return password; 129 } 130 131 /** 132 * Returns the thread to continue. 133 * 134 * @return the thread to continue. 135 */ 136 public String getThread() { 137 return thread; 138 } 139 140 /** 141 * Returns whether the groupchat room continues a one-to-one chat. 142 * 143 * @return whether the groupchat room continues a one-to-one chat. 144 */ 145 public boolean continueAsOneToOneChat() { 146 return continueAsOneToOneChat; 147 } 148 149 /** 150 * Returns the address of the group chat room. GroupChat room addresses 151 * are in the form <code>room@service</code>, where <code>service</code> is 152 * the name of group chat server, such as <code>chat.example.com</code>. 153 * 154 * @return the address of the group chat room. 155 */ 156 public EntityBareJid getRoomAddress() { 157 return roomAddress; 158 } 159 160 @Override 161 public String getElementName() { 162 return ELEMENT; 163 } 164 165 @Override 166 public String getNamespace() { 167 return NAMESPACE; 168 } 169 170 @Override 171 public XmlStringBuilder toXML(org.jivesoftware.smack.packet.XmlEnvironment enclosingNamespace) { 172 XmlStringBuilder xml = new XmlStringBuilder(this); 173 xml.attribute("jid", getRoomAddress()); 174 xml.optAttribute("reason", getReason()); 175 xml.optAttribute("password", getPassword()); 176 xml.optAttribute("thread", getThread()); 177 178 if (continueAsOneToOneChat()) 179 xml.optBooleanAttribute("continue", true); 180 181 xml.closeEmptyElement(); 182 return xml; 183 } 184 185 /** 186 * Get the group chat invitation from the given stanza. 187 * @param packet TODO javadoc me please 188 * @return the GroupChatInvitation or null 189 */ 190 public static GroupChatInvitation from(Stanza packet) { 191 return packet.getExtension(GroupChatInvitation.class); 192 } 193 194}