001: /**
002: * $RCSfile$
003: * $Revision: 128 $
004: * $Date: 2004-10-25 20:42:00 -0300 (Mon, 25 Oct 2004) $
005: *
006: * Copyright (C) 2004 Jive Software. All rights reserved.
007: *
008: * This software is published under the terms of the GNU Public License (GPL),
009: * a copy of which is included in this distribution.
010: */package org.jivesoftware.openfire.forms;
011:
012: import java.util.ArrayList;
013: import java.util.Iterator;
014: import java.util.List;
015:
016: /**
017: * Represents a form that could be use for gathering data as well as for reporting data
018: * returned from a search.
019: * <p/>
020: * The form could be of the following types:
021: * <ul>
022: * <li>form -> Indicates a form to fill out.</li>
023: * <li>submit -> The form is filled out, and this is the data that is being returned from
024: * the form.</li>
025: * <li>cancel -> The form was cancelled. Tell the asker that piece of information.</li>
026: * <li>result -> Data results being returned from a search, or some other query.</li>
027: * </ul>
028: * <p/>
029: * In case the form represents a search, the report will be structured in columns and rows. Use
030: * {@link #addReportedField(FormField)} to set the columns of the report whilst the report's rows
031: * can be configured using {@link #addItemFields(ArrayList)}.
032: *
033: * @author gdombiak
034: */
035: public interface DataForm {
036:
037: public static final String TYPE_FORM = "form";
038: public static final String TYPE_SUBMIT = "submit";
039: public static final String TYPE_CANCEL = "cancel";
040: public static final String TYPE_RESULT = "result";
041:
042: /**
043: * Sets the description of the data. It is similar to the title on a web page or an X window.
044: * You can put a <title/> on either a form to fill out, or a set of data results.
045: *
046: * @param title description of the data.
047: */
048: public abstract void setTitle(String title);
049:
050: /**
051: * Sets the list of instructions that explain how to fill out the form and what the form is
052: * about. The dataform could include multiple instructions since each instruction could not
053: * contain newlines characters.
054: *
055: * @param instructions list of instructions that explain how to fill out the form.
056: */
057: public abstract void setInstructions(List instructions);
058:
059: /**
060: * Returns the meaning of the data within the context. The data could be part of a form
061: * to fill out, a form submission or data results.<p>
062: * <p/>
063: * Possible form types are:
064: * <ul>
065: * <li>form -> This packet contains a form to fill out. Display it to the user (if your
066: * program can).</li>
067: * <li>submit -> The form is filled out, and this is the data that is being returned from
068: * the form.</li>
069: * <li>cancel -> The form was cancelled. Tell the asker that piece of information.</li>
070: * <li>result -> Data results being returned from a search, or some other query.</li>
071: * </ul>
072: *
073: * @return the form's type.
074: */
075: public abstract String getType();
076:
077: /**
078: * Returns the description of the data. It is similar to the title on a web page or an X
079: * window. You can put a <title/> on either a form to fill out, or a set of data results.
080: *
081: * @return description of the data.
082: */
083: public abstract String getTitle();
084:
085: /**
086: * Returns an Iterator for the list of instructions that explain how to fill out the form and
087: * what the form is about. The dataform could include multiple instructions since each
088: * instruction could not contain newlines characters. Join the instructions together in order
089: * to show them to the user.
090: *
091: * @return an Iterator for the list of instructions that explain how to fill out the form.
092: */
093: public abstract Iterator getInstructions();
094:
095: /**
096: * Returns the field of the form whose variable matches the specified variable.
097: * The fields of type FIXED will never be returned since they do not specify a
098: * variable.
099: *
100: * @param variable the variable to look for in the form fields.
101: * @return the field of the form whose variable matches the specified variable.
102: */
103: public FormField getField(String variable);
104:
105: /**
106: * Returns an Iterator for the fields that are part of the form.
107: *
108: * @return an Iterator for the fields that are part of the form.
109: */
110: public abstract Iterator getFields();
111:
112: /**
113: * Returns the number of fields included in the form.
114: *
115: * @return the number of fields included in the form.
116: */
117: public abstract int getFieldsSize();
118:
119: /**
120: * Adds a new instruction to the list of instructions that explain how to fill out the form
121: * and what the form is about. The dataform could include multiple instructions since each
122: * instruction could not contain newlines characters.
123: *
124: * @param instruction the new instruction that explain how to fill out the form.
125: */
126: public abstract void addInstruction(String instruction);
127:
128: /**
129: * Adds a new field as part of the form.
130: *
131: * @param field the field to add to the form.
132: */
133: public abstract void addField(FormField field);
134:
135: /**
136: * Adds a field to the list of fields that will be returned from a search. Each field represents
137: * a column in the report. The order of the columns in the report will honor the sequence in
138: * which they were added.
139: *
140: * @param field the field to add to the list of fields that will be returned from a search.
141: */
142: public abstract void addReportedField(FormField field);
143:
144: /**
145: * Adds a new row of items of reported data. The list of items to add will be formed by
146: * FormFields. Each FormField variable <b>must</b> be valid (i.e. the variable must be defined
147: * by the FormFields added as ReportedField.
148: *
149: * @param itemFields list of FormFields to add as a row in the report.
150: */
151: public abstract void addItemFields(ArrayList itemFields);
152: }
|