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 */ 017 018package org.jivesoftware.smackx.muc.packet; 019 020import java.io.IOException; 021 022import org.jivesoftware.smack.packet.Stanza; 023import org.jivesoftware.smack.packet.ExtensionElement; 024import org.jivesoftware.smack.provider.ExtensionElementProvider; 025import org.jivesoftware.smack.util.XmlStringBuilder; 026import org.xmlpull.v1.XmlPullParser; 027import org.xmlpull.v1.XmlPullParserException; 028 029/** 030 * A group chat invitation stanza(/packet) extension, which is used to invite other 031 * users to a group chat room. To invite a user to a group chat room, address 032 * a new message to the user and set the room name appropriately, as in the 033 * following code example: 034 * 035 * <pre> 036 * Message message = new Message("user@chat.example.com"); 037 * message.setBody("Join me for a group chat!"); 038 * message.addExtension(new GroupChatInvitation("room@chat.example.com");); 039 * con.sendStanza(message); 040 * </pre> 041 * 042 * To listen for group chat invitations, use a StanzaExtensionFilter for the 043 * <tt>x</tt> element name and <tt>jabber:x:conference</tt> namespace, as in the 044 * following code example: 045 * 046 * <pre> 047 * PacketFilter filter = new StanzaExtensionFilter("x", "jabber:x:conference"); 048 * // Create a stanza(/packet) collector or stanza(/packet) listeners using the filter... 049 * </pre> 050 * 051 * <b>Note</b>: this protocol is outdated now that the Multi-User Chat (MUC) XEP is available 052 * (<a href="http://www.xmpp.org/extensions/jep-0045.html">XEP-45</a>). However, most 053 * existing clients still use this older protocol. Once MUC support becomes more 054 * widespread, this API may be deprecated. 055 * 056 * @author Matt Tucker 057 */ 058public class GroupChatInvitation implements ExtensionElement { 059 060 /** 061 * Element name of the stanza(/packet) extension. 062 */ 063 public static final String ELEMENT = "x"; 064 065 /** 066 * Namespace of the stanza(/packet) extension. 067 */ 068 public static final String NAMESPACE = "jabber:x:conference"; 069 070 private final String roomAddress; 071 072 /** 073 * Creates a new group chat invitation to the specified room address. 074 * GroupChat room addresses are in the form <tt>room@service</tt>, 075 * where <tt>service</tt> is the name of groupchat server, such as 076 * <tt>chat.example.com</tt>. 077 * 078 * @param roomAddress the address of the group chat room. 079 */ 080 public GroupChatInvitation(String roomAddress) { 081 this.roomAddress = roomAddress; 082 } 083 084 /** 085 * Returns the address of the group chat room. GroupChat room addresses 086 * are in the form <tt>room@service</tt>, where <tt>service</tt> is 087 * the name of groupchat server, such as <tt>chat.example.com</tt>. 088 * 089 * @return the address of the group chat room. 090 */ 091 public String getRoomAddress() { 092 return roomAddress; 093 } 094 095 public String getElementName() { 096 return ELEMENT; 097 } 098 099 public String getNamespace() { 100 return NAMESPACE; 101 } 102 103 @Override 104 public XmlStringBuilder toXML() { 105 XmlStringBuilder xml = new XmlStringBuilder(this); 106 xml.attribute("jid", getRoomAddress()); 107 xml.closeEmptyElement(); 108 return xml; 109 } 110 111 /** 112 * 113 * @param packet 114 * @return the GroupChatInvitation or null 115 * @deprecated use {@link #from(Stanza)} instead 116 */ 117 @Deprecated 118 public static GroupChatInvitation getFrom(Stanza packet) { 119 return from(packet); 120 } 121 122 /** 123 * 124 * @param packet 125 * @return the GroupChatInvitation or null 126 */ 127 public static GroupChatInvitation from(Stanza packet) { 128 return packet.getExtension(ELEMENT, NAMESPACE); 129 } 130 131 public static class Provider extends ExtensionElementProvider<GroupChatInvitation> { 132 133 @Override 134 public GroupChatInvitation parse(XmlPullParser parser, 135 int initialDepth) throws XmlPullParserException, 136 IOException { 137 String roomAddress = parser.getAttributeValue("", "jid"); 138 // Advance to end of extension. 139 parser.next(); 140 return new GroupChatInvitation(roomAddress); 141 } 142 } 143}