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  ;
15  import java.util.Iterator  ;
16  import java.util.List  ;
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   TYPE_FORM = "form";
40      public static final String   TYPE_SUBMIT = "submit";
41      public static final String   TYPE_CANCEL = "cancel";
42      public static final String   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   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   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   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   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   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   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   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   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   itemFields);
154 }
155
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags