KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > jivesoftware > smackx > packet > DataForm


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.ArrayList JavaDoc;
24 import java.util.Collections JavaDoc;
25 import java.util.Iterator JavaDoc;
26 import java.util.List JavaDoc;
27
28 import org.jivesoftware.smack.packet.PacketExtension;
29 import org.jivesoftware.smackx.FormField;
30
31 /**
32  * Represents a form that could be use for gathering data as well as for reporting data
33  * returned from a search.
34  *
35  * @author Gaston Dombiak
36  */
37 public class DataForm implements PacketExtension {
38
39     private String JavaDoc type;
40     private String JavaDoc title;
41     private List JavaDoc instructions = new ArrayList JavaDoc();
42     private ReportedData reportedData;
43     private List JavaDoc items = new ArrayList JavaDoc();
44     private List JavaDoc fields = new ArrayList JavaDoc();
45     
46     public DataForm(String JavaDoc type) {
47         this.type = type;
48     }
49     
50     /**
51      * Returns the meaning of the data within the context. The data could be part of a form
52      * to fill out, a form submission or data results.<p>
53      *
54      * Possible form types are:
55      * <ul>
56      * <li>form -> This packet contains a form to fill out. Display it to the user (if your
57      * program can).</li>
58      * <li>submit -> The form is filled out, and this is the data that is being returned from
59      * the form.</li>
60      * <li>cancel -> The form was cancelled. Tell the asker that piece of information.</li>
61      * <li>result -> Data results being returned from a search, or some other query.</li>
62      * </ul>
63      *
64      * @return the form's type.
65      */
66     public String JavaDoc getType() {
67         return type;
68     }
69     
70     /**
71      * Returns the description of the data. It is similar to the title on a web page or an X
72      * window. You can put a <title/> on either a form to fill out, or a set of data results.
73      *
74      * @return description of the data.
75      */
76     public String JavaDoc getTitle() {
77         return title;
78     }
79
80     /**
81      * Returns an Iterator for the list of instructions that explain how to fill out the form and
82      * what the form is about. The dataform could include multiple instructions since each
83      * instruction could not contain newlines characters. Join the instructions together in order
84      * to show them to the user.
85      *
86      * @return an Iterator for the list of instructions that explain how to fill out the form.
87      */
88     public Iterator JavaDoc getInstructions() {
89         synchronized (instructions) {
90             return Collections.unmodifiableList(new ArrayList JavaDoc(instructions)).iterator();
91         }
92     }
93
94     /**
95      * Returns the fields that will be returned from a search.
96      *
97      * @return fields that will be returned from a search.
98      */
99     public ReportedData getReportedData() {
100         return reportedData;
101     }
102
103     /**
104      * Returns an Iterator for the items returned from a search.
105      *
106      * @return an Iterator for the items returned from a search.
107      */
108     public Iterator JavaDoc getItems() {
109         synchronized (items) {
110             return Collections.unmodifiableList(new ArrayList JavaDoc(items)).iterator();
111         }
112     }
113
114     /**
115      * Returns an Iterator for the fields that are part of the form.
116      *
117      * @return an Iterator for the fields that are part of the form.
118      */
119     public Iterator JavaDoc getFields() {
120         synchronized (fields) {
121             return Collections.unmodifiableList(new ArrayList JavaDoc(fields)).iterator();
122         }
123     }
124
125     public String JavaDoc getElementName() {
126         return "x";
127     }
128
129     public String JavaDoc getNamespace() {
130         return "jabber:x:data";
131     }
132
133     /**
134      * Sets the description of the data. It is similar to the title on a web page or an X window.
135      * You can put a <title/> on either a form to fill out, or a set of data results.
136      *
137      * @param title description of the data.
138      */
139     public void setTitle(String JavaDoc title) {
140         this.title = title;
141     }
142
143     /**
144      * Sets the list of instructions that explain how to fill out the form and what the form is
145      * about. The dataform could include multiple instructions since each instruction could not
146      * contain newlines characters.
147      *
148      * @param instructions list of instructions that explain how to fill out the form.
149      */
150     public void setInstructions(List JavaDoc instructions) {
151         this.instructions = instructions;
152     }
153
154     /**
155      * Sets the fields that will be returned from a search.
156      *
157      * @param reportedData the fields that will be returned from a search.
158      */
159     public void setReportedData(ReportedData reportedData) {
160         this.reportedData = reportedData;
161     }
162
163     /**
164      * Adds a new field as part of the form.
165      *
166      * @param field the field to add to the form.
167      */
168     public void addField(FormField field) {
169         synchronized (fields) {
170             fields.add(field);
171         }
172     }
173     
174     /**
175      * Adds a new instruction to the list of instructions that explain how to fill out the form
176      * and what the form is about. The dataform could include multiple instructions since each
177      * instruction could not contain newlines characters.
178      *
179      * @param instruction the new instruction that explain how to fill out the form.
180      */
181     public void addInstruction(String JavaDoc instruction) {
182         synchronized (instructions) {
183             instructions.add(instruction);
184         }
185     }
186
187     /**
188      * Adds a new item returned from a search.
189      *
190      * @param item the item returned from a search.
191      */
192     public void addItem(Item item) {
193         synchronized (items) {
194             items.add(item);
195         }
196     }
197
198     public String JavaDoc toXML() {
199         StringBuffer JavaDoc buf = new StringBuffer JavaDoc();
200         buf.append("<").append(getElementName()).append(" xmlns=\"").append(getNamespace()).append(
201             "\" type=\"" + getType() +"\">");
202         if (getTitle() != null) {
203             buf.append("<title>").append(getTitle()).append("</title>");
204         }
205         for (Iterator JavaDoc it=getInstructions(); it.hasNext();) {
206             buf.append("<instructions>").append(it.next()).append("</instructions>");
207         }
208         // Append the list of fields returned from a search
209 if (getReportedData() != null) {
210             buf.append(getReportedData().toXML());
211         }
212         // Loop through all the items returned from a search and append them to the string buffer
213 for (Iterator JavaDoc i = getItems(); i.hasNext();) {
214             Item item = (Item) i.next();
215             buf.append(item.toXML());
216         }
217         // Loop through all the form fields and append them to the string buffer
218 for (Iterator JavaDoc i = getFields(); i.hasNext();) {
219             FormField field = (FormField) i.next();
220             buf.append(field.toXML());
221         }
222         buf.append("</").append(getElementName()).append(">");
223         return buf.toString();
224     }
225
226     /**
227      *
228      * Represents the fields that will be returned from a search. This information is useful when
229      * you try to use the jabber:iq:search namespace to return dynamic form information.
230      *
231      * @author Gaston Dombiak
232      */
233     public static class ReportedData {
234         private List JavaDoc fields = new ArrayList JavaDoc();
235         
236         public ReportedData(List JavaDoc fields) {
237             this.fields = fields;
238         }
239         
240         /**
241          * Returns the fields returned from a search.
242          *
243          * @return the fields returned from a search.
244          */
245         public Iterator JavaDoc getFields() {
246             return Collections.unmodifiableList(new ArrayList JavaDoc(fields)).iterator();
247         }
248         
249         public String JavaDoc toXML() {
250             StringBuffer JavaDoc buf = new StringBuffer JavaDoc();
251             buf.append("<reported>");
252             // Loop through all the form items and append them to the string buffer
253 for (Iterator JavaDoc i = getFields(); i.hasNext();) {
254                 FormField field = (FormField) i.next();
255                 buf.append(field.toXML());
256             }
257             buf.append("</reported>");
258             return buf.toString();
259         }
260     }
261     
262     /**
263      *
264      * Represents items of reported data.
265      *
266      * @author Gaston Dombiak
267      */
268     public static class Item {
269         private List JavaDoc fields = new ArrayList JavaDoc();
270         
271         public Item(List JavaDoc fields) {
272             this.fields = fields;
273         }
274         
275         /**
276          * Returns the fields that define the data that goes with the item.
277          *
278          * @return the fields that define the data that goes with the item.
279          */
280         public Iterator JavaDoc getFields() {
281             return Collections.unmodifiableList(new ArrayList JavaDoc(fields)).iterator();
282         }
283         
284         public String JavaDoc toXML() {
285             StringBuffer JavaDoc buf = new StringBuffer JavaDoc();
286             buf.append("<item>");
287             // Loop through all the form items and append them to the string buffer
288 for (Iterator JavaDoc i = getFields(); i.hasNext();) {
289                 FormField field = (FormField) i.next();
290                 buf.append(field.toXML());
291             }
292             buf.append("</item>");
293             return buf.toString();
294         }
295     }
296 }
297
Popular Tags