RosterExchange


1   /**
2    * $RCSfile$
3    * $Revision: 2407 $
4    * $Date: 2004-11-02 20:37:00 -0300 (Tue, 02 Nov 2004) $
5    *
6    * Copyright 2003-2004 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.packet;
22  
23  import java.util.*;
24  
25  import org.jivesoftware.smack.*;
26  import org.jivesoftware.smack.packet.PacketExtension;
27  import org.jivesoftware.smackx.*;
28  
29  /**
30   * Represents XMPP Roster Item Exchange packets.<p>
31   * 
32   * The 'jabber:x:roster' namespace (which is not to be confused with the 'jabber:iq:roster' 
33   * namespace) is used to send roster items from one client to another. A roster item is sent by 
34   * adding to the &lt;message/&gt; element an &lt;x/&gt; child scoped by the 'jabber:x:roster' namespace. This 
35   * &lt;x/&gt; element may contain one or more &lt;item/&gt; children (one for each roster item to be sent).<p>
36   * 
37   * Each &lt;item/&gt; element may possess the following attributes:<p>
38   * 
39   * &lt;jid/&gt; -- The id of the contact being sent. This attribute is required.<br>
40   * &lt;name/&gt; -- A natural-language nickname for the contact. This attribute is optional.<p>
41   * 
42   * Each &lt;item/&gt; element may also contain one or more &lt;group/&gt; children specifying the 
43   * natural-language name of a user-specified group, for the purpose of categorizing this contact 
44   * into one or more roster groups.
45   *
46   * @author Gaston Dombiak
47   */
48  public class RosterExchange implements PacketExtension {
49  
50      private List remoteRosterEntries = new ArrayList();
51  
52      /**
53       * Creates a new empty roster exchange package.
54       *
55       */
56      public RosterExchange() {
57          super();
58      }
59  
60      /**
61       * Creates a new roster exchange package with the entries specified in roster.
62       *
63       * @param roster the roster to send to other XMPP entity.
64       */
65      public RosterExchange(Roster roster) {
66          // Add all the roster entries to the new RosterExchange 
67          for (Iterator rosterEntries = roster.getEntries(); rosterEntries.hasNext();) {
68              this.addRosterEntry((RosterEntry) rosterEntries.next());
69          }
70      }
71  
72      /**
73       * Adds a roster entry to the packet.
74       *
75       * @param rosterEntry a roster entry to add.
76       */
77      public void addRosterEntry(RosterEntry rosterEntry) {
78          // Obtain a String[] from the roster entry groups name 
79          ArrayList groupNamesList = new ArrayList();
80          String  [] groupNames;
81          for (Iterator groups = rosterEntry.getGroups(); groups.hasNext();) {
82              groupNamesList.add(((RosterGroup) groups.next()).getName());
83          }
84          groupNames = (String  []) groupNamesList.toArray(new String  [groupNamesList.size()]);
85  
86          // Create a new Entry based on the rosterEntry and add it to the packet
87          RemoteRosterEntry remoteRosterEntry = new RemoteRosterEntry(rosterEntry.getUser(), rosterEntry.getName(), groupNames);
88          
89          addRosterEntry(remoteRosterEntry);
90      }
91  
92      /**
93       * Adds a remote roster entry to the packet.
94       *
95       * @param remoteRosterEntry a remote roster entry to add.
96       */
97      public void addRosterEntry(RemoteRosterEntry remoteRosterEntry) {
98          synchronized (remoteRosterEntries) {
99              remoteRosterEntries.add(remoteRosterEntry);
100         }
101     }
102     
103     /**
104     * Returns the XML element name of the extension sub-packet root element.
105     * Always returns "x"
106     *
107     * @return the XML element name of the packet extension.
108     */
109     public String   getElementName() {
110         return "x";
111     }
112 
113     /** 
114      * Returns the XML namespace of the extension sub-packet root element.
115      * According the specification the namespace is always "jabber:x:roster"
116      * (which is not to be confused with the 'jabber:iq:roster' namespace
117      *
118      * @return the XML namespace of the packet extension.
119      */
120     public String   getNamespace() {
121         return "jabber:x:roster";
122     }
123 
124     /**
125      * Returns an Iterator for the roster entries in the packet.
126      *
127      * @return an Iterator for the roster entries in the packet.
128      */
129     public Iterator getRosterEntries() {
130         synchronized (remoteRosterEntries) {
131             List entries = Collections.unmodifiableList(new ArrayList(remoteRosterEntries));
132             return entries.iterator();
133         }
134     }
135 
136     /**
137      * Returns a count of the entries in the roster exchange.
138      *
139      * @return the number of entries in the roster exchange.
140      */
141     public int getEntryCount() {
142         return remoteRosterEntries.size();
143     }
144 
145     /**
146      * Returns the XML representation of a Roster Item Exchange according the specification.
147      * 
148      * Usually the XML representation will be inside of a Message XML representation like
149      * in the following example:
150      * <pre>
151      * &lt;message id="MlIpV-4" to="gato1@gato.home" from="gato3@gato.home/Smack"&gt;
152      *     &lt;subject&gt;Any subject you want&lt;/subject&gt;
153      *     &lt;body&gt;This message contains roster items.&lt;/body&gt;
154      *     &lt;x xmlns="jabber:x:roster"&gt;
155      *         &lt;item jid="gato1@gato.home"/&gt;
156      *         &lt;item jid="gato2@gato.home"/&gt;
157      *     &lt;/x&gt;
158      * &lt;/message&gt;
159      * </pre>
160      * 
161      */
162     public String   toXML() {
163         StringBuffer   buf = new StringBuffer  ();
164         buf.append("<").append(getElementName()).append(" xmlns=\"").append(getNamespace()).append(
165             "\">");
166         // Loop through all roster entries and append them to the string buffer
167         for (Iterator i = getRosterEntries(); i.hasNext();) {
168             RemoteRosterEntry remoteRosterEntry = (RemoteRosterEntry) i.next();
169             buf.append(remoteRosterEntry.toXML());
170         }
171         buf.append("</").append(getElementName()).append(">");
172         return buf.toString();
173     }
174 
175 }
176
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags