Package org.jivesoftware.smackx.xdata

Class FormField

java.lang.Object

org.jivesoftware.smackx.xdata.FormField

All Implemented Interfaces:

Element, FullyQualifiedElement, NamedElement, XmlLangElement

Direct Known Subclasses:

AbstractMultiFormField, JidMultiFormField, SingleValueFormField

public abstract class FormField
extends java.lang.Object
implements FullyQualifiedElement

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 class	FormField.Option	Represents the available options of a ListSingleFormField and ListMultiFormField.
static class	FormField.Required
static class	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 java.lang.String	ELEMENT
protected java.util.List<FullyQualifiedElement>	extraXmlChildElements
static java.lang.String	FORM_TYPE	The constant String "FORM_TYPE".
static java.lang.String	NAMESPACE
static javax.xml.namespace.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(java.lang.String fieldName)
static TextSingleFormField.Builder	builder(java.lang.String fieldName)
static TextSingleFormField	buildHiddenFormType(java.lang.String formType)
boolean	equals(java.lang.Object obj)
static TextSingleFormField.Builder	fixedBuilder()
static TextSingleFormField.Builder	fixedBuilder(java.lang.String fieldName)
java.lang.String	getDescription()	Returns a description that provides extra clarification about the question.
java.lang.String	getElementName()	Returns the root element name.
java.lang.String	getFieldName()	Returns the field's name, also known as the variable name in case this is an filled out answer form.
java.lang.String	getFirstValue()	Returns the first value of this form field or null.
java.util.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(javax.xml.namespace.QName qname)
java.util.List<FormFieldChildElement>	getFormFieldChildElements()
java.util.List<FormFieldChildElement>	getFormFieldChildElements(javax.xml.namespace.QName qname)
java.lang.String	getLabel()	Returns the label of the question which should give enough information to the user to fill out the form.
java.lang.String	getNamespace()	Returns the root element XML namespace.
javax.xml.namespace.QName	getQName()
java.util.List<java.lang.CharSequence>	getRawValueCharSequences()
abstract java.util.List<FormField.Value>	getRawValues()
FormField.Type	getType()	Returns an indicative of the format for the data to answer.
java.util.List<? extends java.lang.CharSequence>	getValues()	Returns a List of the default values of the question if the question is part of a form to fill out.
java.util.List<java.lang.String>	getValuesAsString()	Returns the values a String.
java.lang.String	getVariable()	Deprecated. use getFieldName() instead.
int	hashCode()
boolean	hasValueSet()
static TextSingleFormField.Builder	hiddenBuilder(java.lang.String fieldName)
<F extends FormField> F	ifPossibleAs(java.lang.Class<F> formFieldClass)
<F extends FormField> F	ifPossibleAsOrThrow(java.lang.Class<F> formFieldClass)
boolean	isRequired()	Returns true if the question must be answered in order to complete the questionnaire.
static JidMultiFormField.Builder	jidMultiBuilder(java.lang.String fieldName)
static JidSingleFormField.Builder	jidSingleBuilder(java.lang.String fieldName)
static ListMultiFormField.Builder	listMultiBuilder(java.lang.String fieldName)
static ListSingleFormField.Builder	listSingleBuilder(java.lang.String fieldName)
protected void	populateExtraXmlChildElements()	Populate @{link extraXmlChildElements}.
static TextMultiFormField.Builder	textMultiBuilder(java.lang.String fieldName)
static TextSingleFormField.Builder	textPrivateBuilder(java.lang.String fieldName)
static TextSingleFormField.Builder	textSingleBuilder(java.lang.String fieldName)
XmlStringBuilder	toXML(XmlEnvironment enclosingNamespace)
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.FullyQualifiedElement

getLanguage

Field Detail

ELEMENT

public static final java.lang.String ELEMENT

See Also:

Constant Field Values

NAMESPACE

public static final java.lang.String NAMESPACE

See Also:

Constant Field Values

QNAME

public static final javax.xml.namespace.QName QNAME

FORM_TYPE

public static final java.lang.String FORM_TYPE

The constant String "FORM_TYPE".

See Also:

Constant Field Values

extraXmlChildElements

protected transient java.util.List<FullyQualifiedElement> extraXmlChildElements

Constructor Detail

FormField

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

Method Detail

getDescription

public java.lang.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 java.lang.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 java.util.List<? extends java.lang.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 java.util.List<FormField.Value> getRawValues()

getRawValueCharSequences

public final java.util.List<java.lang.CharSequence> getRawValueCharSequences()

hasValueSet

public boolean hasValueSet()

getValuesAsString

public java.util.List<java.lang.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 java.lang.String getFirstValue()

Returns the first value of this form field or null.

Returns:

the first value or null

Since:

4.3

getFirstValueAsDate

public java.util.Date getFirstValueAsDate()
                                   throws java.text.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:

java.text.ParseException - if parsing fails.

Since:

4.3.0

getVariable

@Deprecated
public java.lang.String getVariable()

Deprecated.

use getFieldName() instead.

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.

getFieldName

public java.lang.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(javax.xml.namespace.QName qname)

getFormFieldChildElements

public java.util.List<FormFieldChildElement> getFormFieldChildElements(javax.xml.namespace.QName qname)

getFormFieldChildElements

public java.util.List<FormFieldChildElement> getFormFieldChildElements()

getElementName

public java.lang.String getElementName()

Description copied from interface: NamedElement

Returns the root element name.

Specified by:

getElementName in interface NamedElement

Returns:

the element name.

getNamespace

public java.lang.String getNamespace()

Description copied from interface: FullyQualifiedElement

Returns the root element XML namespace.

Specified by:

getNamespace in interface FullyQualifiedElement

Returns:

the namespace.

getQName

public javax.xml.namespace.QName getQName()

Specified by:

getQName in interface FullyQualifiedElement

populateExtraXmlChildElements

protected void populateExtraXmlChildElements()

Populate @{link 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(java.lang.Object obj)

Overrides:

equals in class java.lang.Object

hashCode

public int hashCode()

Overrides:

hashCode in class java.lang.Object

booleanBuilder

public static BooleanFormField.Builder booleanBuilder(java.lang.String fieldName)

fixedBuilder

public static TextSingleFormField.Builder fixedBuilder()

fixedBuilder

public static TextSingleFormField.Builder fixedBuilder(java.lang.String fieldName)

hiddenBuilder

public static TextSingleFormField.Builder hiddenBuilder(java.lang.String fieldName)

jidMultiBuilder

public static JidMultiFormField.Builder jidMultiBuilder(java.lang.String fieldName)

jidSingleBuilder

public static JidSingleFormField.Builder jidSingleBuilder(java.lang.String fieldName)

listMultiBuilder

public static ListMultiFormField.Builder listMultiBuilder(java.lang.String fieldName)

listSingleBuilder

public static ListSingleFormField.Builder listSingleBuilder(java.lang.String fieldName)

textMultiBuilder

public static TextMultiFormField.Builder textMultiBuilder(java.lang.String fieldName)

textPrivateBuilder

public static TextSingleFormField.Builder textPrivateBuilder(java.lang.String fieldName)

textSingleBuilder

public static TextSingleFormField.Builder textSingleBuilder(java.lang.String fieldName)

builder

public static TextSingleFormField.Builder builder(java.lang.String fieldName)

buildHiddenFormType

public static TextSingleFormField buildHiddenFormType(java.lang.String formType)

ifPossibleAs

public <F extends FormField> F ifPossibleAs(java.lang.Class<F> formFieldClass)

ifPossibleAsOrThrow

public <F extends FormField> F ifPossibleAsOrThrow(java.lang.Class<F> formFieldClass)

asHiddenFormTypeFieldIfPossible

public TextSingleFormField asHiddenFormTypeFieldIfPossible()