DiscoverItems


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.packet.IQ;
26  
27  /**
28   * A DiscoverItems IQ packet, which is used by XMPP clients to request and receive items 
29   * associated with XMPP entities.<p>
30   * 
31   * The items could also be queried in order to discover if they contain items inside. Some items 
32   * may be addressable by its JID and others may require to be addressed by a JID and a node name.
33   *
34   * @author Gaston Dombiak
35   */
36  public class DiscoverItems extends IQ {
37  
38      private List items = new ArrayList();
39      private String   node;
40  
41      /**
42       * Adds a new item to the discovered information.
43       * 
44       * @param item the discovered entity's item
45       */
46      public void addItem(Item item) {
47          synchronized (items) {
48              items.add(item);
49          }
50      }
51  
52      /**
53       * Returns the discovered items of the queried XMPP entity. 
54       *
55       * @return an Iterator on the discovered entity's items
56       */
57      public Iterator getItems() {
58          synchronized (items) {
59              return Collections.unmodifiableList(new ArrayList(items)).iterator();
60          }
61      }
62  
63      /**
64       * Returns the node attribute that supplements the 'jid' attribute. A node is merely 
65       * something that is associated with a JID and for which the JID can provide information.<p> 
66       * 
67       * Node attributes SHOULD be used only when trying to provide or query information which 
68       * is not directly addressable.
69       *
70       * @return the node attribute that supplements the 'jid' attribute
71       */
72      public String   getNode() {
73          return node;
74      }
75  
76      /**
77       * Sets the node attribute that supplements the 'jid' attribute. A node is merely 
78       * something that is associated with a JID and for which the JID can provide information.<p> 
79       * 
80       * Node attributes SHOULD be used only when trying to provide or query information which 
81       * is not directly addressable.
82       * 
83       * @param node the node attribute that supplements the 'jid' attribute
84       */
85      public void setNode(String   node) {
86          this.node = node;
87      }
88  
89      public String   getChildElementXML() {
90          StringBuffer   buf = new StringBuffer  ();
91          buf.append("<query xmlns=\"http://jabber.org/protocol/disco#items\"");
92          if (getNode() != null) {
93              buf.append(" node=\"");
94              buf.append(getNode());
95              buf.append("\"");
96          }
97          buf.append(">");
98          synchronized (items) {
99              for (int i = 0; i < items.size(); i++) {
100                 Item item = (Item) items.get(i);
101                 buf.append(item.toXML());
102             }
103         }
104         buf.append("</query>");
105         return buf.toString();
106     }
107 
108     /**
109      * An item is associated with an XMPP Entity, usually thought of a children of the parent 
110      * entity and normally are addressable as a JID.<p> 
111      * 
112      * An item associated with an entity may not be addressable as a JID. In order to handle 
113      * such items, Service Discovery uses an optional 'node' attribute that supplements the 
114      * 'jid' attribute.
115      */
116     public static class Item {
117 
118         /**
119          * Request to create or update the item.
120          */
121         public static final String   UPDATE_ACTION = "update";
122 
123         /**
124          * Request to remove the item.
125          */
126         public static final String   REMOVE_ACTION = "remove";
127 
128         private String   entityID;
129         private String   name;
130         private String   node;
131         private String   action;
132 
133         /**
134          * Create a new Item associated with a given entity.
135          * 
136          * @param entityID the id of the entity that contains the item
137          */
138         public Item(String   entityID) {
139             this.entityID = entityID;
140         }
141 
142         /**
143          * Returns the entity's ID.
144          *
145          * @return the entity's ID.
146          */
147         public String   getEntityID() {
148             return entityID;
149         }
150 
151         /**
152          * Returns the entity's name.
153          *
154          * @return the entity's name.
155          */
156         public String   getName() {
157             return name;
158         }
159 
160         /**
161          * Sets the entity's name.
162          *
163          * @param name the entity's name.
164          */
165         public void setName(String   name) {
166             this.name = name;
167         }
168 
169         /**
170          * Returns the node attribute that supplements the 'jid' attribute. A node is merely 
171          * something that is associated with a JID and for which the JID can provide information.<p> 
172          * 
173          * Node attributes SHOULD be used only when trying to provide or query information which 
174          * is not directly addressable.
175          *
176          * @return the node attribute that supplements the 'jid' attribute
177          */
178         public String   getNode() {
179             return node;
180         }
181 
182         /**
183          * Sets the node attribute that supplements the 'jid' attribute. A node is merely 
184          * something that is associated with a JID and for which the JID can provide information.<p> 
185          * 
186          * Node attributes SHOULD be used only when trying to provide or query information which 
187          * is not directly addressable.
188          * 
189          * @param node the node attribute that supplements the 'jid' attribute
190          */
191         public void setNode(String   node) {
192             this.node = node;
193         }
194 
195         /**
196          * Returns the action that specifies the action being taken for this item. Possible action 
197          * values are: "update" and "remove". Update should either create a new entry if the node 
198          * and jid combination does not already exist, or simply update an existing entry. If 
199          * "remove" is used as the action, the item should be removed from persistent storage.
200          *  
201          * @return the action being taken for this item
202          */
203         public String   getAction() {
204             return action;
205         }
206 
207         /**
208          * Sets the action that specifies the action being taken for this item. Possible action 
209          * values are: "update" and "remove". Update should either create a new entry if the node 
210          * and jid combination does not already exist, or simply update an existing entry. If 
211          * "remove" is used as the action, the item should be removed from persistent storage.
212          * 
213          * @param action the action being taken for this item
214          */
215         public void setAction(String   action) {
216             this.action = action;
217         }
218 
219         public String   toXML() {
220             StringBuffer   buf = new StringBuffer  ();
221             buf.append("<item jid=\"").append(entityID).append("\"");
222             if (name != null) {
223                 buf.append(" name=\"").append(name).append("\"");
224             }
225             if (node != null) {
226                 buf.append(" node=\"").append(node).append("\"");
227             }
228             if (action != null) {
229                 buf.append(" action=\"").append(action).append("\"");
230             }
231             buf.append("/>");
232             return buf.toString();
233         }
234     }
235 }
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags