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 org.jivesoftware.smack.packet.PacketExtension;
021import org.jivesoftware.smack.provider.PacketExtensionProvider;
022import org.xmlpull.v1.XmlPullParser;
023
024/**
025 * A group chat invitation packet extension, which is used to invite other
026 * users to a group chat room. To invite a user to a group chat room, address
027 * a new message to the user and set the room name appropriately, as in the
028 * following code example:
029 *
030 * <pre>
031 * Message message = new Message("user@chat.example.com");
032 * message.setBody("Join me for a group chat!");
033 * message.addExtension(new GroupChatInvitation("room@chat.example.com"););
034 * con.sendPacket(message);
035 * </pre>
036 *
037 * To listen for group chat invitations, use a PacketExtensionFilter for the
038 * <tt>x</tt> element name and <tt>jabber:x:conference</tt> namespace, as in the
039 * following code example:
040 *
041 * <pre>
042 * PacketFilter filter = new PacketExtensionFilter("x", "jabber:x:conference");
043 * // Create a packet collector or packet listeners using the filter...
044 * </pre>
045 *
046 * <b>Note</b>: this protocol is outdated now that the Multi-User Chat (MUC) XEP is available
047 * (<a href="http://www.xmpp.org/extensions/jep-0045.html">XEP-45</a>). However, most
048 * existing clients still use this older protocol. Once MUC support becomes more
049 * widespread, this API may be deprecated.
050 * 
051 * @author Matt Tucker
052 */
053public class GroupChatInvitation implements PacketExtension {
054
055    /**
056     * Element name of the packet extension.
057     */
058    public static final String ELEMENT_NAME = "x";
059
060    /**
061     * Namespace of the packet extension.
062     */
063    public static final String NAMESPACE = "jabber:x:conference";
064
065    private String roomAddress;
066
067    /**
068     * Creates a new group chat invitation to the specified room address.
069     * GroupChat room addresses are in the form <tt>room@service</tt>,
070     * where <tt>service</tt> is the name of groupchat server, such as
071     * <tt>chat.example.com</tt>.
072     *
073     * @param roomAddress the address of the group chat room.
074     */
075    public GroupChatInvitation(String roomAddress) {
076        this.roomAddress = roomAddress;
077    }
078
079    /**
080     * Returns the address of the group chat room. GroupChat room addresses
081     * are in the form <tt>room@service</tt>, where <tt>service</tt> is
082     * the name of groupchat server, such as <tt>chat.example.com</tt>.
083     *
084     * @return the address of the group chat room.
085     */
086    public String getRoomAddress() {
087        return roomAddress;
088    }
089
090    public String getElementName() {
091        return ELEMENT_NAME;
092    }
093
094    public String getNamespace() {
095        return NAMESPACE;
096    }
097
098    public String toXML() {
099        StringBuilder buf = new StringBuilder();
100        buf.append("<x xmlns=\"jabber:x:conference\" jid=\"").append(roomAddress).append("\"/>");
101        return buf.toString();
102    }
103
104    public static class Provider implements PacketExtensionProvider {
105        public PacketExtension parseExtension (XmlPullParser parser) throws Exception {
106            String roomAddress = parser.getAttributeValue("", "jid");
107            // Advance to end of extension.
108            parser.next();
109            return new GroupChatInvitation(roomAddress);
110        }
111    }
112}