1/**
2 * $RCSfile$
3 * $Revision$
4 * $Date$
5 *
6 * Copyright 2003-2007 Jive Software.
7 *
8 * All rights reserved. Licensed under the Apache License, Version 2.0 (the "License");
9 * you may not use this file except in compliance with the License.
10 * You may obtain a copy of the License at
11 *
12 *     http://www.apache.org/licenses/LICENSE-2.0
13 *
14 * Unless required by applicable law or agreed to in writing, software
15 * distributed under the License is distributed on an "AS IS" BASIS,
16 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
17 * See the License for the specific language governing permissions and
18 * limitations under the License.
19 */
20
21package org.jivesoftware.smackx;
22
23import org.jivesoftware.smack.packet.PacketExtension;
24import org.jivesoftware.smack.provider.PacketExtensionProvider;
25import org.xmlpull.v1.XmlPullParser;
26
27/**
28 * A group chat invitation packet extension, which is used to invite other
29 * users to a group chat room. To invite a user to a group chat room, address
30 * a new message to the user and set the room name appropriately, as in the
31 * following code example:
32 *
33 * <pre>
34 * Message message = new Message("user@chat.example.com");
35 * message.setBody("Join me for a group chat!");
36 * message.addExtension(new GroupChatInvitation("room@chat.example.com"););
37 * con.sendPacket(message);
38 * </pre>
39 *
40 * To listen for group chat invitations, use a PacketExtensionFilter for the
41 * <tt>x</tt> element name and <tt>jabber:x:conference</tt> namespace, as in the
42 * following code example:
43 *
44 * <pre>
45 * PacketFilter filter = new PacketExtensionFilter("x", "jabber:x:conference");
46 * // Create a packet collector or packet listeners using the filter...
47 * </pre>
48 *
49 * <b>Note</b>: this protocol is outdated now that the Multi-User Chat (MUC) JEP is available
50 * (<a href="http://www.jabber.org/jeps/jep-0045.html">JEP-45</a>). However, most
51 * existing clients still use this older protocol. Once MUC support becomes more
52 * widespread, this API may be deprecated.
53 *
54 * @author Matt Tucker
55 */
56public class GroupChatInvitation implements PacketExtension {
57
58    /**
59     * Element name of the packet extension.
60     */
61    public static final String ELEMENT_NAME = "x";
62
63    /**
64     * Namespace of the packet extension.
65     */
66    public static final String NAMESPACE = "jabber:x:conference";
67
68    private String roomAddress;
69
70    /**
71     * Creates a new group chat invitation to the specified room address.
72     * GroupChat room addresses are in the form <tt>room@service</tt>,
73     * where <tt>service</tt> is the name of groupchat server, such as
74     * <tt>chat.example.com</tt>.
75     *
76     * @param roomAddress the address of the group chat room.
77     */
78    public GroupChatInvitation(String roomAddress) {
79        this.roomAddress = roomAddress;
80    }
81
82    /**
83     * Returns the address of the group chat room. GroupChat room addresses
84     * are in the form <tt>room@service</tt>, where <tt>service</tt> is
85     * the name of groupchat server, such as <tt>chat.example.com</tt>.
86     *
87     * @return the address of the group chat room.
88     */
89    public String getRoomAddress() {
90        return roomAddress;
91    }
92
93    public String getElementName() {
94        return ELEMENT_NAME;
95    }
96
97    public String getNamespace() {
98        return NAMESPACE;
99    }
100
101    public String toXML() {
102        StringBuilder buf = new StringBuilder();
103        buf.append("<x xmlns=\"jabber:x:conference\" jid=\"").append(roomAddress).append("\"/>");
104        return buf.toString();
105    }
106
107    public static class Provider implements PacketExtensionProvider {
108        public PacketExtension parseExtension (XmlPullParser parser) throws Exception {
109            String roomAddress = parser.getAttributeValue("", "jid");
110            // Advance to end of extension.
111            parser.next();
112            return new GroupChatInvitation(roomAddress);
113        }
114    }
115}