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 073 /** 074 * Creates a new group chat invitation to the specified room address. 075 * GroupChat room addresses are in the form <code>room@service</code>, 076 * where <code>service</code> is the name of group chat server, such as 077 * <code>chat.example.com</code>. 078 * 079 * @param roomAddress the address of the group chat room. 080 */ 081 public GroupChatInvitation(EntityBareJid roomAddress) { 082 this.roomAddress = Objects.requireNonNull(roomAddress); 083 } 084 085 /** 086 * Returns the address of the group chat room. GroupChat room addresses 087 * are in the form <code>room@service</code>, where <code>service</code> is 088 * the name of group chat server, such as <code>chat.example.com</code>. 089 * 090 * @return the address of the group chat room. 091 */ 092 public EntityBareJid getRoomAddress() { 093 return roomAddress; 094 } 095 096 @Override 097 public String getElementName() { 098 return ELEMENT; 099 } 100 101 @Override 102 public String getNamespace() { 103 return NAMESPACE; 104 } 105 106 @Override 107 public XmlStringBuilder toXML(org.jivesoftware.smack.packet.XmlEnvironment enclosingNamespace) { 108 XmlStringBuilder xml = new XmlStringBuilder(this); 109 xml.attribute("jid", getRoomAddress()); 110 xml.closeEmptyElement(); 111 return xml; 112 } 113 114 /** 115 * Get the group chat invitation from the given stanza. 116 * @param packet TODO javadoc me please 117 * @return the GroupChatInvitation or null 118 */ 119 public static GroupChatInvitation from(Stanza packet) { 120 return packet.getExtension(GroupChatInvitation.class); 121 } 122 123}