org.jivesoftware.smackx
Class Form

java.lang.Object
  org.jivesoftware.smackx.Form

public class Form
extends Object

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

• form -> Indicates a form to fill out.
• submit -> The form is filled out, and this is the data that is being returned from the form.
• cancel -> The form was cancelled. Tell the asker that piece of information.
• result -> Data results being returned from a search, or some other query.

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

Field Summary

static String	TYPE_CANCEL
static String	TYPE_FORM
static String	TYPE_RESULT
static String	TYPE_SUBMIT

Constructor Summary

Form(DataForm dataForm)
Creates a new Form that will wrap an existing DataForm.

Form(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(String variable) Returns the field of the form whose variable matches the specified variable.
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".
String	getInstructions() Returns the instructions that explain how to fill out the form and what the form is about.
String	getTitle() Returns the description of the data.
String	getType() Returns the meaning of the data within the context.
void	setAnswer(String variable, boolean value) Sets a new boolean value to a given form's field.
void	setAnswer(String variable, double value) Sets a new double value to a given form's field.
void	setAnswer(String variable, float value) Sets a new float value to a given form's field.
void	setAnswer(String variable, int value) Sets a new int value to a given form's field.
void	setAnswer(String variable, List<String> values) Sets a new values to a given form's field.
void	setAnswer(String variable, long value) Sets a new long value to a given form's field.
void	setAnswer(String variable, String value) Sets a new String value to a given form's field.
void	setDefaultAnswer(String variable) Sets the default value as the value of a given form's field.
void	setInstructions(String instructions) Sets instructions that explain how to fill out the form and what the form is about.
void	setTitle(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 String TYPE_FORM

See Also:

Constant Field Values

TYPE_SUBMIT

public static final String TYPE_SUBMIT

See Also:

Constant Field Values

TYPE_CANCEL

public static final String TYPE_CANCEL

See Also:

Constant Field Values

TYPE_RESULT

public static final String TYPE_RESULT

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(String type)

Creates a new Form of a given type from scratch.

Possible form types are:

• form -> Indicates a form to fill out.
• submit -> The form is filled out, and this is the data that is being returned from the form.
• cancel -> The form was cancelled. Tell the asker that piece of information.
• result -> Data results being returned from a search, or some other query.

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(String variable,
                      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:

IllegalStateException - if the form is not of type "submit".

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(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:

IllegalStateException - if the form is not of type "submit".

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(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:

IllegalStateException - if the form is not of type "submit".

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(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:

IllegalStateException - if the form is not of type "submit".

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(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:

IllegalStateException - if the form is not of type "submit".

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(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:

IllegalStateException - if the form is not of type "submit".

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(String variable,
                      List<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:

IllegalStateException - if the form is not of type "submit".

IllegalArgumentException - if the form does not include the specified variable.

setDefaultAnswer

public void setDefaultAnswer(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:

IllegalStateException - if the form is not of type "submit".

IllegalArgumentException - if the form does not include the specified variable.

getFields

public 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(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 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 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