Home | History | Annotate | Download | only in smackx 
      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 
     21 package org.jivesoftware.smackx;
     22 
     23 import org.jivesoftware.smack.packet.PacketExtension;
     24 import org.jivesoftware.smack.provider.PacketExtensionProvider;
     25 import 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 (at) chat.example.com");
     35  * message.setBody("Join me for a group chat!");
     36  * message.addExtension(new GroupChatInvitation("room (at) 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  */
     56 public 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 }