/** * $RCSfile$ * $Revision$ * $Date$ * * Copyright 2003-2004 Jive Software. * * All rights reserved. Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at * * http://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. */ package org.jivesoftware.smackx.packet; import java.util.*; import org.jivesoftware.smack.*; import org.jivesoftware.smack.packet.PacketExtension; import org.jivesoftware.smackx.*; /** * Represents XMPP Roster Item Exchange packets.

* * The 'jabber:x:roster' namespace (which is not to be confused with the 'jabber:iq:roster' * namespace) is used to send roster items from one client to another. A roster item is sent by * adding to the <message/> element an <x/> child scoped by the 'jabber:x:roster' namespace. This * <x/> element may contain one or more <item/> children (one for each roster item to be sent).

* * Each <item/> element may possess the following attributes:

* * <jid/> -- The id of the contact being sent. This attribute is required.
* <name/> -- A natural-language nickname for the contact. This attribute is optional.

* * Each <item/> element may also contain one or more <group/> children specifying the * natural-language name of a user-specified group, for the purpose of categorizing this contact * into one or more roster groups. * * @author Gaston Dombiak */ public class RosterExchange implements PacketExtension { private List remoteRosterEntries = new ArrayList(); /** * Creates a new empty roster exchange package. * */ public RosterExchange() { super(); } /** * Creates a new roster exchange package with the entries specified in roster. * * @param roster the roster to send to other XMPP entity. */ public RosterExchange(Roster roster) { // Add all the roster entries to the new RosterExchange for (Iterator rosterEntries = roster.getEntries(); rosterEntries.hasNext();) { this.addRosterEntry((RosterEntry) rosterEntries.next()); } } /** * Adds a roster entry to the packet. * * @param rosterEntry a roster entry to add. */ public void addRosterEntry(RosterEntry rosterEntry) { // Obtain a String[] from the roster entry groups name ArrayList groupNamesList = new ArrayList(); String[] groupNames; for (Iterator groups = rosterEntry.getGroups(); groups.hasNext();) { groupNamesList.add(((RosterGroup) groups.next()).getName()); } groupNames = (String[]) groupNamesList.toArray(new String[groupNamesList.size()]); // Create a new Entry based on the rosterEntry and add it to the packet RemoteRosterEntry remoteRosterEntry = new RemoteRosterEntry(rosterEntry.getUser(), rosterEntry.getName(), groupNames); addRosterEntry(remoteRosterEntry); } /** * Adds a remote roster entry to the packet. * * @param remoteRosterEntry a remote roster entry to add. */ public void addRosterEntry(RemoteRosterEntry remoteRosterEntry) { synchronized (remoteRosterEntries) { remoteRosterEntries.add(remoteRosterEntry); } } /** * Returns the XML element name of the extension sub-packet root element. * Always returns "x" * * @return the XML element name of the packet extension. */ public String getElementName() { return "x"; } /** * Returns the XML namespace of the extension sub-packet root element. * According the specification the namespace is always "jabber:x:roster" * (which is not to be confused with the 'jabber:iq:roster' namespace * * @return the XML namespace of the packet extension. */ public String getNamespace() { return "jabber:x:roster"; } /** * Returns an Iterator for the roster entries in the packet. * * @return an Iterator for the roster entries in the packet. */ public Iterator getRosterEntries() { synchronized (remoteRosterEntries) { List entries = Collections.unmodifiableList(new ArrayList(remoteRosterEntries)); return entries.iterator(); } } /** * Returns a count of the entries in the roster exchange. * * @return the number of entries in the roster exchange. */ public int getEntryCount() { return remoteRosterEntries.size(); } /** * Returns the XML representation of a Roster Item Exchange according the specification. * * Usually the XML representation will be inside of a Message XML representation like * in the following example: *

     * <message id="MlIpV-4" to="gato1@gato.home" from="gato3@gato.home/Smack">
     *     <subject>Any subject you want</subject>
     *     <body>This message contains roster items.</body>
     *     <x xmlns="jabber:x:roster">
     *         <item jid="gato1@gato.home"/>
     *         <item jid="gato2@gato.home"/>
     *     </x>
     * </message>
     * 
* */ public String toXML() { StringBuffer buf = new StringBuffer(); buf.append("<").append(getElementName()).append(" xmlns=\"").append(getNamespace()).append( "\">"); // Loop through all roster entries and append them to the string buffer for (Iterator i = getRosterEntries(); i.hasNext();) { RemoteRosterEntry remoteRosterEntry = (RemoteRosterEntry) i.next(); buf.append(remoteRosterEntry.toXML()); } buf.append(""); return buf.toString(); } }