Package org.jivesoftware.smackx.xdata

Class FormField

java.lang.Object

org.jivesoftware.smackx.xdata.FormField

All Implemented Interfaces:

Element, NamedElement, XmlElement, XmlLangElement

Direct Known Subclasses:

AbstractMultiFormField, JidMultiFormField, SingleValueFormField

public abstract class FormField
extends Object
implements XmlElement

Represents a field of a form. The field could be used to represent a question to complete, a completed question or a data returned from a search. The exact interpretation of the field depends on the context where the field is used.

Fields have a name, which is stored in the 'var' attribute of the field's XML representation. Field instances of all types, except of type "fixed" must have a name.

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static class	FormField.Builder<F extends FormField,B extends FormField.Builder<?,?>>
static class	FormField.Description
static final class	FormField.Option	Represents the available options of a ListSingleFormField and ListMultiFormField.
static final class	FormField.Required
static enum	FormField.Type	Form Field Types as defined in XEP-4 § 3.3.
static class	FormField.Value

Field Summary

Fields

Modifier and Type	Field	Description
static final String	ELEMENT
protected List<XmlElement>	extraXmlChildElements
static final String	FORM_TYPE	The constant String "FORM_TYPE".
static final String	NAMESPACE
static final QName	QNAME

Constructor Summary

Constructors

Modifier	Constructor	Description
protected	FormField(FormField.Builder<?,?> builder)

Method Summary

Modifier and Type	Method	Description
TextSingleFormField	asHiddenFormTypeFieldIfPossible()
static BooleanFormField.Builder	booleanBuilder(String fieldName)
static TextSingleFormField.Builder	builder(String fieldName)
static TextSingleFormField	buildHiddenFormType(String formType)
boolean	equals(Object obj)
static TextSingleFormField.Builder	fixedBuilder()
static TextSingleFormField.Builder	fixedBuilder(String fieldName)
String	getDescription()	Returns a description that provides extra clarification about the question.
String	getElementName()	Returns the root element name.
String	getFieldName()	Returns the field's name, also known as the variable name in case this is an filled out answer form.
String	getFirstValue()	Returns the first value of this form field or null.
Date	getFirstValueAsDate()	Parses the first value of this form field as XEP-0082 date/time format and returns a date instance or null.
FormFieldChildElement	getFormFieldChildElement(QName qname)
List<FormFieldChildElement>	getFormFieldChildElements()
List<FormFieldChildElement>	getFormFieldChildElements(QName qname)
String	getLabel()	Returns the label of the question which should give enough information to the user to fill out the form.
String	getNamespace()	Returns the root element XML namespace.
QName	getQName()
final List<CharSequence>	getRawValueCharSequences()
abstract List<FormField.Value>	getRawValues()
FormField.Type	getType()	Returns an indicative of the format for the data to answer.
List<? extends CharSequence>	getValues()	Returns a List of the default values of the question if the question is part of a form to fill out.
List<String>	getValuesAsString()	Returns the values a String.
int	hashCode()
boolean	hasValueSet()
static TextSingleFormField.Builder	hiddenBuilder(String fieldName)
<F extends FormField> F	ifPossibleAs(Class<F> formFieldClass)
<F extends FormField> F	ifPossibleAsOrThrow(Class<F> formFieldClass)
boolean	isRequired()	Returns true if the question must be answered in order to complete the questionnaire.
static JidMultiFormField.Builder	jidMultiBuilder(String fieldName)
static JidSingleFormField.Builder	jidSingleBuilder(String fieldName)
static ListMultiFormField.Builder	listMultiBuilder(String fieldName)
static ListSingleFormField.Builder	listSingleBuilder(String fieldName)
protected void	populateExtraXmlChildElements()	Populate extraXmlChildElements.
static TextMultiFormField.Builder	textMultiBuilder(String fieldName)
static TextSingleFormField.Builder	textPrivateBuilder(String fieldName)
static TextSingleFormField.Builder	textSingleBuilder(String fieldName)
final XmlStringBuilder	toXML(XmlEnvironment enclosingNamespace)
final XmlStringBuilder	toXML(XmlEnvironment enclosingNamespace, boolean includeType)

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface org.jivesoftware.smack.packet.Element

toXML, toXML

Methods inherited from interface org.jivesoftware.smack.packet.XmlElement

getLanguage

Field Details

ELEMENT

public static final String ELEMENT

See Also:

• Constant Field Values

NAMESPACE

public static final String NAMESPACE

See Also:

• Constant Field Values

QNAME

public static final QName QNAME

FORM_TYPE

public static final String FORM_TYPE

The constant String "FORM_TYPE".

See Also:

• Constant Field Values

extraXmlChildElements

protected transient List<XmlElement> extraXmlChildElements

Constructor Details

FormField

protected FormField(FormField.Builder<?,?> builder)

Method Details

getDescription

public String getDescription()

Returns a description that provides extra clarification about the question. This information could be presented to the user either in tool-tip, help button, or as a section of text before the question.

If the question is of type FIXED then the description should remain empty.

Returns:

description that provides extra clarification about the question.

getLabel

public String getLabel()

Returns the label of the question which should give enough information to the user to fill out the form.

Returns:

label of the question.

isRequired

public boolean isRequired()

Returns true if the question must be answered in order to complete the questionnaire.

Returns:

true if the question must be answered in order to complete the questionnaire.

getType

public FormField.Type getType()

Returns an indicative of the format for the data to answer.

Returns:

format for the data to answer.

See Also:

• FormField.Type

getValues

public List<? extends CharSequence> getValues()

Returns a List of the default values of the question if the question is part of a form to fill out. Otherwise, returns a List of the answered values of the question.

Returns:

a List of the default values or answered values of the question.

getRawValues

public abstract List<FormField.Value> getRawValues()

getRawValueCharSequences

public final List<CharSequence> getRawValueCharSequences()

hasValueSet

public boolean hasValueSet()

getValuesAsString

public List<String> getValuesAsString()

Returns the values a String. Note that you should use getValues() whenever possible instead of this method.

Returns:

a list of Strings representing the values

Since:

4.3

See Also:

• getValues()

getFirstValue

public String getFirstValue()

Returns the first value of this form field or null.

Returns:

the first value or null

Since:

4.3

getFirstValueAsDate

public Date getFirstValueAsDate()
                         throws ParseException

Parses the first value of this form field as XEP-0082 date/time format and returns a date instance or null.

Returns:

a Date instance representing the date/time information of the first value of this field.

Throws:

ParseException - if parsing fails.

Since:

4.3.0

getFieldName

public String getFieldName()

Returns the field's name, also known as the variable name in case this is an filled out answer form.

According to XEP-4 § 3.2 the variable name (the 'var' attribute) "uniquely identifies the field in the context of the form" (if the field is not of type 'fixed', in which case the field "MAY possess a 'var' attribute")

Returns:

the field's name.

getFormFieldChildElement

public FormFieldChildElement getFormFieldChildElement(QName qname)

getFormFieldChildElements

public List<FormFieldChildElement> getFormFieldChildElements(QName qname)

getFormFieldChildElements

public List<FormFieldChildElement> getFormFieldChildElements()

getElementName

public String getElementName()

Description copied from interface: NamedElement

Returns the root element name.

Specified by:

getElementName in interface NamedElement

Returns:

the element name.

getNamespace

public String getNamespace()

Description copied from interface: XmlElement

Returns the root element XML namespace.

Specified by:

getNamespace in interface XmlElement

Returns:

the namespace.

getQName

public QName getQName()

Specified by:

getQName in interface XmlElement

populateExtraXmlChildElements

protected void populateExtraXmlChildElements()

Populate extraXmlChildElements. Note that this method may be overridden by subclasses.

toXML

public final XmlStringBuilder toXML(XmlEnvironment enclosingNamespace)

Specified by:

toXML in interface Element

toXML

public final XmlStringBuilder toXML(XmlEnvironment enclosingNamespace,
 boolean includeType)

equals

public boolean equals(Object obj)

Overrides:

equals in class Object

hashCode

public int hashCode()

Overrides:

hashCode in class Object

booleanBuilder

public static BooleanFormField.Builder booleanBuilder(String fieldName)

fixedBuilder

public static TextSingleFormField.Builder fixedBuilder()

fixedBuilder

public static TextSingleFormField.Builder fixedBuilder(String fieldName)

hiddenBuilder

public static TextSingleFormField.Builder hiddenBuilder(String fieldName)

jidMultiBuilder

public static JidMultiFormField.Builder jidMultiBuilder(String fieldName)

jidSingleBuilder

public static JidSingleFormField.Builder jidSingleBuilder(String fieldName)

listMultiBuilder

public static ListMultiFormField.Builder listMultiBuilder(String fieldName)

listSingleBuilder

public static ListSingleFormField.Builder listSingleBuilder(String fieldName)

textMultiBuilder

public static TextMultiFormField.Builder textMultiBuilder(String fieldName)

textPrivateBuilder

public static TextSingleFormField.Builder textPrivateBuilder(String fieldName)

textSingleBuilder

public static TextSingleFormField.Builder textSingleBuilder(String fieldName)

builder

public static TextSingleFormField.Builder builder(String fieldName)

buildHiddenFormType

public static TextSingleFormField buildHiddenFormType(String formType)

ifPossibleAs

public <F extends FormField> F ifPossibleAs(Class<F> formFieldClass)

ifPossibleAsOrThrow

public <F extends FormField> F ifPossibleAsOrThrow(Class<F> formFieldClass)

asHiddenFormTypeFieldIfPossible

public TextSingleFormField asHiddenFormTypeFieldIfPossible()