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.xroster.packet; 019 020import org.jivesoftware.smack.packet.ExtensionElement; 021import org.jivesoftware.smack.roster.Roster; 022import org.jivesoftware.smack.roster.RosterEntry; 023import org.jivesoftware.smack.roster.RosterGroup; 024import org.jivesoftware.smackx.xroster.RemoteRosterEntry; 025import org.jivesoftware.smackx.xroster.RosterExchangeManager; 026 027import java.util.ArrayList; 028import java.util.Collections; 029import java.util.Iterator; 030import java.util.List; 031 032/** 033 * Represents XMPP Roster Item Exchange packets.<p> 034 * 035 * The 'jabber:x:roster' namespace (which is not to be confused with the 'jabber:iq:roster' 036 * namespace) is used to send roster items from one client to another. A roster item is sent by 037 * adding to the <message/> element an <x/> child scoped by the 'jabber:x:roster' namespace. This 038 * <x/> element may contain one or more <item/> children (one for each roster item to be sent).<p> 039 * 040 * Each <item/> element may possess the following attributes:<p> 041 * 042 * <jid/> -- The id of the contact being sent. This attribute is required.<br> 043 * <name/> -- A natural-language nickname for the contact. This attribute is optional.<p> 044 * 045 * Each <item/> element may also contain one or more <group/> children specifying the 046 * natural-language name of a user-specified group, for the purpose of categorizing this contact 047 * into one or more roster groups. 048 * 049 * @author Gaston Dombiak 050 */ 051public class RosterExchange implements ExtensionElement { 052 053 private final List<RemoteRosterEntry> remoteRosterEntries = new ArrayList<>(); 054 055 /** 056 * Creates a new empty roster exchange package. 057 * 058 */ 059 public RosterExchange() { 060 super(); 061 } 062 063 /** 064 * Creates a new roster exchange package with the entries specified in roster. 065 * 066 * @param roster the roster to send to other XMPP entity. 067 */ 068 public RosterExchange(Roster roster) { 069 // Add all the roster entries to the new RosterExchange 070 for (RosterEntry rosterEntry : roster.getEntries()) { 071 this.addRosterEntry(rosterEntry); 072 } 073 } 074 075 /** 076 * Adds a roster entry to the packet. 077 * 078 * @param rosterEntry a roster entry to add. 079 */ 080 public void addRosterEntry(RosterEntry rosterEntry) { 081 // Obtain a String[] from the roster entry groups name 082 List<String> groupNamesList = new ArrayList<String>(); 083 String[] groupNames; 084 for (RosterGroup group : rosterEntry.getGroups()) { 085 groupNamesList.add(group.getName()); 086 } 087 groupNames = groupNamesList.toArray(new String[groupNamesList.size()]); 088 089 // Create a new Entry based on the rosterEntry and add it to the packet 090 RemoteRosterEntry remoteRosterEntry = new RemoteRosterEntry(rosterEntry.getJid(), 091 rosterEntry.getName(), groupNames); 092 093 addRosterEntry(remoteRosterEntry); 094 } 095 096 /** 097 * Adds a remote roster entry to the packet. 098 * 099 * @param remoteRosterEntry a remote roster entry to add. 100 */ 101 public void addRosterEntry(RemoteRosterEntry remoteRosterEntry) { 102 synchronized (remoteRosterEntries) { 103 remoteRosterEntries.add(remoteRosterEntry); 104 } 105 } 106 107 /** 108 * Returns the XML element name of the extension sub-packet root element. 109 * Always returns "x" 110 * 111 * @return the XML element name of the stanza(/packet) extension. 112 */ 113 @Override 114 public String getElementName() { 115 return RosterExchangeManager.ELEMENT; 116 } 117 118 /** 119 * Returns the XML namespace of the extension sub-packet root element. 120 * According the specification the namespace is always "jabber:x:roster" 121 * (which is not to be confused with the 'jabber:iq:roster' namespace 122 * 123 * @return the XML namespace of the stanza(/packet) extension. 124 */ 125 @Override 126 public String getNamespace() { 127 return RosterExchangeManager.NAMESPACE; 128 } 129 130 /** 131 * Returns an Iterator for the roster entries in the packet. 132 * 133 * @return an Iterator for the roster entries in the packet. 134 */ 135 public Iterator<RemoteRosterEntry> getRosterEntries() { 136 synchronized (remoteRosterEntries) { 137 List<RemoteRosterEntry> entries = Collections.unmodifiableList(new ArrayList<RemoteRosterEntry>(remoteRosterEntries)); 138 return entries.iterator(); 139 } 140 } 141 142 /** 143 * Returns a count of the entries in the roster exchange. 144 * 145 * @return the number of entries in the roster exchange. 146 */ 147 public int getEntryCount() { 148 return remoteRosterEntries.size(); 149 } 150 151 /** 152 * Returns the XML representation of a Roster Item Exchange according the specification. 153 * 154 * Usually the XML representation will be inside of a Message XML representation like 155 * in the following example: 156 * <pre> 157 * <message id="MlIpV-4" to="gato1@gato.home" from="gato3@gato.home/Smack"> 158 * <subject>Any subject you want</subject> 159 * <body>This message contains roster items.</body> 160 * <x xmlns="jabber:x:roster"> 161 * <item jid="gato1@gato.home"/> 162 * <item jid="gato2@gato.home"/> 163 * </x> 164 * </message> 165 * </pre> 166 * 167 */ 168 @Override 169 public String toXML() { 170 StringBuilder buf = new StringBuilder(); 171 buf.append('<').append(getElementName()).append(" xmlns=\"").append(getNamespace()).append( 172 "\">"); 173 // Loop through all roster entries and append them to the string buffer 174 for (Iterator<RemoteRosterEntry> i = getRosterEntries(); i.hasNext();) { 175 RemoteRosterEntry remoteRosterEntry = i.next(); 176 buf.append(remoteRosterEntry.toXML()); 177 } 178 buf.append("</").append(getElementName()).append('>'); 179 return buf.toString(); 180 } 181 182}