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}