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    @Override
096    public String getElementName() {
097        return ELEMENT;
098    }
099
100    @Override
101    public String getNamespace() {
102        return NAMESPACE;
103    }
104
105    @Override
106    public XmlStringBuilder toXML() {
107        XmlStringBuilder xml = new XmlStringBuilder(this);
108        xml.attribute("jid", getRoomAddress());
109        xml.closeEmptyElement();
110        return xml;
111    }
112
113    /**
114     * Deprecated.
115     * @param packet
116     * @return the GroupChatInvitation or null
117     * @deprecated use {@link #from(Stanza)} instead
118     */
119    @Deprecated
120    public static GroupChatInvitation getFrom(Stanza packet) {
121        return from(packet);
122    }
123
124    /**
125     * Get the group chat invitation from the given stanza.
126     * @param packet
127     * @return the GroupChatInvitation or null
128     */
129    public static GroupChatInvitation from(Stanza packet) {
130        return packet.getExtension(ELEMENT, NAMESPACE);
131    }
132
133    public static class Provider extends ExtensionElementProvider<GroupChatInvitation> {
134
135        @Override
136        public GroupChatInvitation parse(XmlPullParser parser,
137                        int initialDepth) throws XmlPullParserException,
138                        IOException {
139            String roomAddress = parser.getAttributeValue("", "jid");
140            // Advance to end of extension.
141            parser.next();
142            return new GroupChatInvitation(roomAddress);
143        }
144    }
145}