Smack

org.jivesoftware.smackx
Class Form

java.lang.Object
  extended by org.jivesoftware.smackx.Form
Direct Known Subclasses:
ConfigureForm, SubscribeForm

public class Form
extends java.lang.Object

Represents a Form for gathering data. The form could be of the following types:

Depending of the form's type different operations are available. For example, it's only possible to set answers if the form is of type "submit".

Author:
Gaston Dombiak
See Also:
XEP-0004 Data Forms

Field Summary
static java.lang.String ELEMENT
           
static java.lang.String NAMESPACE
           
static java.lang.String TYPE_CANCEL
           
static java.lang.String TYPE_FORM
           
static java.lang.String TYPE_RESULT
           
static java.lang.String TYPE_SUBMIT
           
 
Constructor Summary
Form(DataForm dataForm)
          Creates a new Form that will wrap an existing DataForm.
Form(java.lang.String type)
          Creates a new Form of a given type from scratch.
 
Method Summary
 void addField(FormField field)
          Adds a new field to complete as part of the form.
 Form createAnswerForm()
          Returns a new Form to submit the completed values.
 DataForm getDataFormToSend()
          Returns a DataForm that serves to send this Form to the server.
 FormField getField(java.lang.String variable)
          Returns the field of the form whose variable matches the specified variable.
 java.util.Iterator<FormField> getFields()
          Returns an Iterator for the fields that are part of the form.
static Form getFormFrom(Packet packet)
          Returns a new ReportedData if the packet is used for gathering data and includes an extension that matches the elementName and namespace "x","jabber:x:data".
 java.lang.String getInstructions()
          Returns the instructions that explain how to fill out the form and what the form is about.
 java.lang.String getTitle()
          Returns the description of the data.
 java.lang.String getType()
          Returns the meaning of the data within the context.
 void setAnswer(java.lang.String variable, boolean value)
          Sets a new boolean value to a given form's field.
 void setAnswer(java.lang.String variable, double value)
          Sets a new double value to a given form's field.
 void setAnswer(java.lang.String variable, float value)
          Sets a new float value to a given form's field.
 void setAnswer(java.lang.String variable, int value)
          Sets a new int value to a given form's field.
 void setAnswer(java.lang.String variable, java.util.List<java.lang.String> values)
          Sets a new values to a given form's field.
 void setAnswer(java.lang.String variable, long value)
          Sets a new long value to a given form's field.
 void setAnswer(java.lang.String variable, java.lang.String value)
          Sets a new String value to a given form's field.
 void setDefaultAnswer(java.lang.String variable)
          Sets the default value as the value of a given form's field.
 void setInstructions(java.lang.String instructions)
          Sets instructions that explain how to fill out the form and what the form is about.
 void setTitle(java.lang.String title)
          Sets the description of the data.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

TYPE_FORM

public static final java.lang.String TYPE_FORM
See Also:
Constant Field Values

TYPE_SUBMIT

public static final java.lang.String TYPE_SUBMIT
See Also:
Constant Field Values

TYPE_CANCEL

public static final java.lang.String TYPE_CANCEL
See Also:
Constant Field Values

TYPE_RESULT

public static final java.lang.String TYPE_RESULT
See Also:
Constant Field Values

NAMESPACE

public static final java.lang.String NAMESPACE
See Also:
Constant Field Values

ELEMENT

public static final java.lang.String ELEMENT
See Also:
Constant Field Values
Constructor Detail

Form

public Form(DataForm dataForm)
Creates a new Form that will wrap an existing DataForm. The wrapped DataForm must be used for gathering data.

Parameters:
dataForm - the data form used for gathering data.

Form

public Form(java.lang.String type)
Creates a new Form of a given type from scratch.

Possible form types are:

Parameters:
type - the form's type (e.g. form, submit,cancel,result).
Method Detail

getFormFrom

public static Form getFormFrom(Packet packet)
Returns a new ReportedData if the packet is used for gathering data and includes an extension that matches the elementName and namespace "x","jabber:x:data".

Parameters:
packet - the packet used for gathering data.
Returns:
the data form parsed from the packet or null if there was not a form in the packet.

addField

public void addField(FormField field)
Adds a new field to complete as part of the form.

Parameters:
field - the field to complete.

setAnswer

public void setAnswer(java.lang.String variable,
                      java.lang.String value)
Sets a new String value to a given form's field. The field whose variable matches the requested variable will be completed with the specified value. If no field could be found for the specified variable then an exception will be raised.

If the value to set to the field is not a basic type (e.g. String, boolean, int, etc.) you can use this message where the String value is the String representation of the object.

Parameters:
variable - the variable name that was completed.
value - the String value that was answered.
Throws:
java.lang.IllegalStateException - if the form is not of type "submit".
java.lang.IllegalArgumentException - if the form does not include the specified variable or if the answer type does not correspond with the field type..

setAnswer

public void setAnswer(java.lang.String variable,
                      int value)
Sets a new int value to a given form's field. The field whose variable matches the requested variable will be completed with the specified value. If no field could be found for the specified variable then an exception will be raised.

Parameters:
variable - the variable name that was completed.
value - the int value that was answered.
Throws:
java.lang.IllegalStateException - if the form is not of type "submit".
java.lang.IllegalArgumentException - if the form does not include the specified variable or if the answer type does not correspond with the field type.

setAnswer

public void setAnswer(java.lang.String variable,
                      long value)
Sets a new long value to a given form's field. The field whose variable matches the requested variable will be completed with the specified value. If no field could be found for the specified variable then an exception will be raised.

Parameters:
variable - the variable name that was completed.
value - the long value that was answered.
Throws:
java.lang.IllegalStateException - if the form is not of type "submit".
java.lang.IllegalArgumentException - if the form does not include the specified variable or if the answer type does not correspond with the field type.

setAnswer

public void setAnswer(java.lang.String variable,
                      float value)
Sets a new float value to a given form's field. The field whose variable matches the requested variable will be completed with the specified value. If no field could be found for the specified variable then an exception will be raised.

Parameters:
variable - the variable name that was completed.
value - the float value that was answered.
Throws:
java.lang.IllegalStateException - if the form is not of type "submit".
java.lang.IllegalArgumentException - if the form does not include the specified variable or if the answer type does not correspond with the field type.

setAnswer

public void setAnswer(java.lang.String variable,
                      double value)
Sets a new double value to a given form's field. The field whose variable matches the requested variable will be completed with the specified value. If no field could be found for the specified variable then an exception will be raised.

Parameters:
variable - the variable name that was completed.
value - the double value that was answered.
Throws:
java.lang.IllegalStateException - if the form is not of type "submit".
java.lang.IllegalArgumentException - if the form does not include the specified variable or if the answer type does not correspond with the field type.

setAnswer

public void setAnswer(java.lang.String variable,
                      boolean value)
Sets a new boolean value to a given form's field. The field whose variable matches the requested variable will be completed with the specified value. If no field could be found for the specified variable then an exception will be raised.

Parameters:
variable - the variable name that was completed.
value - the boolean value that was answered.
Throws:
java.lang.IllegalStateException - if the form is not of type "submit".
java.lang.IllegalArgumentException - if the form does not include the specified variable or if the answer type does not correspond with the field type.

setAnswer

public void setAnswer(java.lang.String variable,
                      java.util.List<java.lang.String> values)
Sets a new values to a given form's field. The field whose variable matches the requested variable will be completed with the specified values. If no field could be found for the specified variable then an exception will be raised.

The Objects contained in the List could be of any type. The String representation of them (i.e. #toString) will be actually used when sending the answer to the server.

Parameters:
variable - the variable that was completed.
values - the values that were answered.
Throws:
java.lang.IllegalStateException - if the form is not of type "submit".
java.lang.IllegalArgumentException - if the form does not include the specified variable.

setDefaultAnswer

public void setDefaultAnswer(java.lang.String variable)
Sets the default value as the value of a given form's field. The field whose variable matches the requested variable will be completed with its default value. If no field could be found for the specified variable then an exception will be raised.

Parameters:
variable - the variable to complete with its default value.
Throws:
java.lang.IllegalStateException - if the form is not of type "submit".
java.lang.IllegalArgumentException - if the form does not include the specified variable.

getFields

public java.util.Iterator<FormField> getFields()
Returns an Iterator for the fields that are part of the form.

Returns:
an Iterator for the fields that are part of the form.

getField

public FormField getField(java.lang.String variable)
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.

Parameters:
variable - the variable to look for in the form fields.
Returns:
the field of the form whose variable matches the specified variable.

getInstructions

public java.lang.String getInstructions()
Returns the instructions that explain how to fill out the form and what the form is about.

Returns:
instructions that explain how to fill out the form.

getTitle

public java.lang.String getTitle()
Returns the description of the data. It is similar to the title on a web page or an X window. You can put a on either a form to fill out, or a set of data results. <P> <DD><DL> <DT><B>Returns:</B><DD>description of the data.</DL> </DD> </DL> <HR> <A NAME="getType()"><!-- --></A><H3> getType</H3> <PRE> public java.lang.String <B>getType</B>()</PRE> <DL> <DD>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> Possible form types are: <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> <DD><DL> <DT><B>Returns:</B><DD>the form's type.</DL> </DD> </DL> <HR> <A NAME="setInstructions(java.lang.String)"><!-- --></A><H3> setInstructions</H3> <PRE> public void <B>setInstructions</B>(java.lang.String instructions)</PRE> <DL> <DD>Sets instructions that explain how to fill out the form and what the form is about. <P> <DD><DL> <DT><B>Parameters:</B><DD><CODE>instructions</CODE> - instructions that explain how to fill out the form.</DL> </DD> </DL> <HR> <A NAME="setTitle(java.lang.String)"><!-- --></A><H3> setTitle</H3> <PRE> public void <B>setTitle</B>(java.lang.String title)</PRE> <DL> <DD>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. <P> <DD><DL> <DT><B>Parameters:</B><DD><CODE>title</CODE> - description of the data.</DL> </DD> </DL> <HR> <A NAME="getDataFormToSend()"><!-- --></A><H3> getDataFormToSend</H3> <PRE> public <A HREF="../../../org/jivesoftware/smackx/packet/DataForm.html" title="class in org.jivesoftware.smackx.packet">DataForm</A> <B>getDataFormToSend</B>()</PRE> <DL> <DD>Returns a DataForm that serves to send this Form to the server. If the form is of type submit, it may contain fields with no value. These fields will be removed since they only exist to assist the user while editing/completing the form in a UI. <P> <DD><DL> <DT><B>Returns:</B><DD>the wrapped DataForm.</DL> </DD> </DL> <HR> <A NAME="createAnswerForm()"><!-- --></A><H3> createAnswerForm</H3> <PRE> public <A HREF="../../../org/jivesoftware/smackx/Form.html" title="class in org.jivesoftware.smackx">Form</A> <B>createAnswerForm</B>()</PRE> <DL> <DD>Returns a new Form to submit the completed values. The new Form will include all the fields of the original form except for the fields of type FIXED. Only the HIDDEN fields will include the same value of the original form. The other fields of the new form MUST be completed. If a field remains with no answer when sending the completed form, then it won't be included as part of the completed form.<p> The reason why the fields with variables are included in the new form is to provide a model for binding with any UI. This means that the UIs will use the original form (of type "form") to learn how to render the form, but the UIs will bind the fields to the form of type submit. <P> <DD><DL> <DT><B>Returns:</B><DD>a Form to submit the completed values.</DL> </DD> </DL> <!-- ========= END OF CLASS DATA ========= --> <HR> <!-- ======= START OF BOTTOM NAVBAR ====== --> <A NAME="navbar_bottom"><!-- --></A> <A HREF="#skip-navbar_bottom" title="Skip navigation links"></A> <TABLE BORDER="0" WIDTH="100%" CELLPADDING="1" CELLSPACING="0" SUMMARY=""> <TR> <TD COLSPAN=2 BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A NAME="navbar_bottom_firstrow"><!-- --></A> <TABLE BORDER="0" CELLPADDING="0" CELLSPACING="3" SUMMARY=""> <TR ALIGN="center" VALIGN="top"> <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="../../../overview-summary.html"><FONT CLASS="NavBarFont1"><B>Overview</B></FONT></A> </TD> <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="package-summary.html"><FONT CLASS="NavBarFont1"><B>Package</B></FONT></A> </TD> <TD BGCOLOR="#FFFFFF" CLASS="NavBarCell1Rev">  <FONT CLASS="NavBarFont1Rev"><B>Class</B></FONT> </TD> <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="package-tree.html"><FONT CLASS="NavBarFont1"><B>Tree</B></FONT></A> </TD> <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="../../../deprecated-list.html"><FONT CLASS="NavBarFont1"><B>Deprecated</B></FONT></A> </TD> <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="../../../index-all.html"><FONT CLASS="NavBarFont1"><B>Index</B></FONT></A> </TD> <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="../../../help-doc.html"><FONT CLASS="NavBarFont1"><B>Help</B></FONT></A> </TD> </TR> </TABLE> </TD> <TD ALIGN="right" VALIGN="top" ROWSPAN=3><EM> <b>Smack</b></EM> </TD> </TR> <TR> <TD BGCOLOR="white" CLASS="NavBarCell2"><FONT SIZE="-2">  <A HREF="../../../org/jivesoftware/smackx/DefaultMessageEventRequestListener.html" title="class in org.jivesoftware.smackx"><B>PREV CLASS</B></A>   <A HREF="../../../org/jivesoftware/smackx/FormField.html" title="class in org.jivesoftware.smackx"><B>NEXT CLASS</B></A></FONT></TD> <TD BGCOLOR="white" CLASS="NavBarCell2"><FONT SIZE="-2"> <A HREF="../../../index.html?org/jivesoftware/smackx/Form.html" target="_top"><B>FRAMES</B></A>    <A HREF="Form.html" target="_top"><B>NO FRAMES</B></A>    <SCRIPT type="text/javascript"> <!-- if(window==top) { document.writeln('<A HREF="../../../allclasses-noframe.html"><B>All Classes</B></A>'); } //--> </SCRIPT> <NOSCRIPT> <A HREF="../../../allclasses-noframe.html"><B>All Classes</B></A> </NOSCRIPT> </FONT></TD> </TR> <TR> <TD VALIGN="top" CLASS="NavBarCell3"><FONT SIZE="-2"> SUMMARY: NESTED | <A HREF="#field_summary">FIELD</A> | <A HREF="#constructor_summary">CONSTR</A> | <A HREF="#method_summary">METHOD</A></FONT></TD> <TD VALIGN="top" CLASS="NavBarCell3"><FONT SIZE="-2"> DETAIL: <A HREF="#field_detail">FIELD</A> | <A HREF="#constructor_detail">CONSTR</A> | <A HREF="#method_detail">METHOD</A></FONT></TD> </TR> </TABLE> <A NAME="skip-navbar_bottom"></A> <!-- ======== END OF BOTTOM NAVBAR ======= --> <HR> <i>Copyright © 2003-2007 Jive Software. </i> </BODY> </HTML>