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