DataForm.java 6.39 KB
Newer Older
1 2 3 4 5 6 7
/**
 * $RCSfile$
 * $Revision: 128 $
 * $Date: 2004-10-25 20:42:00 -0300 (Mon, 25 Oct 2004) $
 *
 * Copyright (C) 2004-2008 Jive Software. All rights reserved.
 *
8 9 10 11 12 13 14 15 16 17 18
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165
 */

package org.jivesoftware.openfire.forms;

import java.util.ArrayList;
import java.util.Iterator;
import java.util.List;

/**
 * Represents a form that could be use for gathering data as well as for reporting data
 * returned from a search.
 * <p/>
 * The form could be of the following types:
 * <ul>
 * <li>form -> Indicates a form to fill out.</li>
 * <li>submit -> The form is filled out, and this is the data that is being returned from
 * the form.</li>
 * <li>cancel -> The form was cancelled. Tell the asker that piece of information.</li>
 * <li>result -> Data results being returned from a search, or some other query.</li>
 * </ul>
 * <p/>
 * In case the form represents a search, the report will be structured in columns and rows. Use
 * {@link #addReportedField(FormField)} to set the columns of the report whilst the report's rows
 * can be configured using {@link #addItemFields(ArrayList)}.
 *
 * @author gdombiak
 * @deprecated replaced by {@link org.xmpp.forms.DataForm}
 */
@Deprecated
public interface DataForm {

    public static final String TYPE_FORM = "form";
    public static final String TYPE_SUBMIT = "submit";
    public static final String TYPE_CANCEL = "cancel";
    public static final String TYPE_RESULT = "result";

    /**
     * Sets the description of the data. It is similar to the title on a web page or an X window.
     * You can put a <title/> on either a form to fill out, or a set of data results.
     *
     * @param title description of the data.
     */
    public abstract void setTitle(String title);

    /**
     * Sets the list of instructions that explain how to fill out the form and what the form is
     * about. The dataform could include multiple instructions since each instruction could not
     * contain newlines characters.
     *
     * @param instructions list of instructions that explain how to fill out the form.
     */
    public abstract void setInstructions(List instructions);

    /**
     * Returns the meaning of the data within the context. The data could be part of a form
     * to fill out, a form submission or data results.<p>
     * <p/>
     * Possible form types are:
     * <ul>
     * <li>form -> This packet contains a form to fill out. Display it to the user (if your
     * program can).</li>
     * <li>submit -> The form is filled out, and this is the data that is being returned from
     * the form.</li>
     * <li>cancel -> The form was cancelled. Tell the asker that piece of information.</li>
     * <li>result -> Data results being returned from a search, or some other query.</li>
     * </ul>
     *
     * @return the form's type.
     */
    public abstract String getType();

    /**
     * Returns the description of the data. It is similar to the title on a web page or an X
     * window.  You can put a <title/> on either a form to fill out, or a set of data results.
     *
     * @return description of the data.
     */
    public abstract String getTitle();

    /**
     * Returns an Iterator for the list of instructions that explain how to fill out the form and
     * what the form is about. The dataform could include multiple instructions since each
     * instruction could not contain newlines characters. Join the instructions together in order
     * to show them to the user.
     *
     * @return an Iterator for the list of instructions that explain how to fill out the form.
     */
    public abstract Iterator getInstructions();

    /**
     * Returns the field of the form whose variable matches the specified variable.
     * The fields of type FIXED will never be returned since they do not specify a
     * variable.
     *
     * @param variable the variable to look for in the form fields.
     * @return the field of the form whose variable matches the specified variable.
     */
    public FormField getField(String variable);

    /**
     * Returns an Iterator for the fields that are part of the form.
     *
     * @return an Iterator for the fields that are part of the form.
     */
    public abstract Iterator getFields();

    /**
     * Returns the number of fields included in the form.
     *
     * @return the number of fields included in the form.
     */
    public abstract int getFieldsSize();

    /**
     * Adds a new instruction to the list of instructions that explain how to fill out the form
     * and what the form is about. The dataform could include multiple instructions since each
     * instruction could not contain newlines characters.
     *
     * @param instruction the new instruction that explain how to fill out the form.
     */
    public abstract void addInstruction(String instruction);

    /**
     * Adds a new field as part of the form.
     *
     * @param field the field to add to the form.
     */
    public abstract void addField(FormField field);

    /**
     * Adds a field to the list of fields that will be returned from a search. Each field represents
     * a column in the report. The order of the columns in the report will honor the sequence in
     * which they were added.
     *
     * @param field the field to add to the list of fields that will be returned from a search.
     */
    public abstract void addReportedField(FormField field);

    /**
     * Adds a new row of items of reported data. The list of items to add will be formed by
     * FormFields. Each FormField variable <b>must</b> be valid (i.e. the variable must be defined
     * by the FormFields added as ReportedField.
     *
     * @param itemFields list of FormFields to add as a row in the report.
     */
    public abstract void addItemFields(ArrayList itemFields);
}