KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > jivesoftware > messenger > forms > DataForm


1 /**
2  * $RCSfile: DataForm.java,v $
3  * $Revision: 1.3 $
4  * $Date: 2004/10/25 23:41:58 $
5  *
6  * Copyright (C) 2004 Jive Software. All rights reserved.
7  *
8  * This software is published under the terms of the GNU Public License (GPL),
9  * a copy of which is included in this distribution.
10  */

11
12 package org.jivesoftware.messenger.forms;
13
14 import java.util.ArrayList JavaDoc;
15 import java.util.Iterator JavaDoc;
16 import java.util.List JavaDoc;
17
18 /**
19  * Represents a form that could be use for gathering data as well as for reporting data
20  * returned from a search.
21  * <p/>
22  * The form could be of the following types:
23  * <ul>
24  * <li>form -> Indicates a form to fill out.</li>
25  * <li>submit -> The form is filled out, and this is the data that is being returned from
26  * the form.</li>
27  * <li>cancel -> The form was cancelled. Tell the asker that piece of information.</li>
28  * <li>result -> Data results being returned from a search, or some other query.</li>
29  * </ul>
30  * <p/>
31  * In case the form represents a search, the report will be structured in columns and rows. Use
32  * {@link #addReportedField(FormField)} to set the columns of the report whilst the report's rows
33  * can be configured using {@link #addItemFields(ArrayList)}.
34  *
35  * @author gdombiak
36  */

37 public interface DataForm {
38
39     public static final String JavaDoc TYPE_FORM = "form";
40     public static final String JavaDoc TYPE_SUBMIT = "submit";
41     public static final String JavaDoc TYPE_CANCEL = "cancel";
42     public static final String JavaDoc TYPE_RESULT = "result";
43
44     /**
45      * Sets the description of the data. It is similar to the title on a web page or an X window.
46      * You can put a <title/> on either a form to fill out, or a set of data results.
47      *
48      * @param title description of the data.
49      */

50     public abstract void setTitle(String JavaDoc title);
51
52     /**
53      * Sets the list of instructions that explain how to fill out the form and what the form is
54      * about. The dataform could include multiple instructions since each instruction could not
55      * contain newlines characters.
56      *
57      * @param instructions list of instructions that explain how to fill out the form.
58      */

59     public abstract void setInstructions(List JavaDoc instructions);
60
61     /**
62      * Returns the meaning of the data within the context. The data could be part of a form
63      * to fill out, a form submission or data results.<p>
64      * <p/>
65      * Possible form types are:
66      * <ul>
67      * <li>form -> This packet contains a form to fill out. Display it to the user (if your
68      * program can).</li>
69      * <li>submit -> The form is filled out, and this is the data that is being returned from
70      * the form.</li>
71      * <li>cancel -> The form was cancelled. Tell the asker that piece of information.</li>
72      * <li>result -> Data results being returned from a search, or some other query.</li>
73      * </ul>
74      *
75      * @return the form's type.
76      */

77     public abstract String JavaDoc getType();
78
79     /**
80      * Returns the description of the data. It is similar to the title on a web page or an X
81      * window. You can put a <title/> on either a form to fill out, or a set of data results.
82      *
83      * @return description of the data.
84      */

85     public abstract String JavaDoc getTitle();
86
87     /**
88      * Returns an Iterator for the list of instructions that explain how to fill out the form and
89      * what the form is about. The dataform could include multiple instructions since each
90      * instruction could not contain newlines characters. Join the instructions together in order
91      * to show them to the user.
92      *
93      * @return an Iterator for the list of instructions that explain how to fill out the form.
94      */

95     public abstract Iterator JavaDoc getInstructions();
96
97     /**
98      * Returns the field of the form whose variable matches the specified variable.
99      * The fields of type FIXED will never be returned since they do not specify a
100      * variable.
101      *
102      * @param variable the variable to look for in the form fields.
103      * @return the field of the form whose variable matches the specified variable.
104      */

105     public FormField getField(String JavaDoc variable);
106
107     /**
108      * Returns an Iterator for the fields that are part of the form.
109      *
110      * @return an Iterator for the fields that are part of the form.
111      */

112     public abstract Iterator JavaDoc getFields();
113
114     /**
115      * Returns the number of fields included in the form.
116      *
117      * @return the number of fields included in the form.
118      */

119     public abstract int getFieldsSize();
120
121     /**
122      * Adds a new instruction to the list of instructions that explain how to fill out the form
123      * and what the form is about. The dataform could include multiple instructions since each
124      * instruction could not contain newlines characters.
125      *
126      * @param instruction the new instruction that explain how to fill out the form.
127      */

128     public abstract void addInstruction(String JavaDoc instruction);
129
130     /**
131      * Adds a new field as part of the form.
132      *
133      * @param field the field to add to the form.
134      */

135     public abstract void addField(FormField field);
136
137     /**
138      * Adds a field to the list of fields that will be returned from a search. Each field represents
139      * a column in the report. The order of the columns in the report will honor the sequence in
140      * which they were added.
141      *
142      * @param field the field to add to the list of fields that will be returned from a search.
143      */

144     public abstract void addReportedField(FormField field);
145
146     /**
147      * Adds a new row of items of reported data. The list of items to add will be formed by
148      * FormFields. Each FormField variable <b>must</b> be valid (i.e. the variable must be defined
149      * by the FormFields added as ReportedField.
150      *
151      * @param itemFields list of FormFields to add as a row in the report.
152      */

153     public abstract void addItemFields(ArrayList JavaDoc itemFields);
154 }
155
Popular Tags