rocks.xmpp.extensions.data.model

Class DataForm.Field

java.lang.Object

rocks.xmpp.extensions.data.model.DataForm.Field

All Implemented Interfaces:

Comparable<DataForm.Field>

Enclosing class:

DataForm

public static final class DataForm.Field
extends Object
implements Comparable<DataForm.Field>

A data form field.

Usage

Creating a field

Since a field can have multiple different properties like type, value, label, description, required, options, etc. it uses the builder pattern to construct an (immutable) instance of a field. If the field type is omitted it's inferred from the value, as you see in the following examples.

 
 // <field type="boolean" var="test"><value>1</value></field>
 DataForm.Field field = DataForm.Field.builder()
     .var("test")
     .value(true)
     .build();

 // <field type="jid-single" var="test"><value>domain</value></field>
 DataForm.Field.builder()
     .var("test")
     .value(Jid.of("domain"))
     .build();
 
 

Creating a field with options

 
 // <field type="list-single" var="test"><option><value>option</value></option></field>
 DataForm.Field field = DataForm.Field.builder()
     .var("test")
     .type(DataForm.Field.Type.LIST_SINGLE)
     .options(Collections.singleton(new DataForm.Option("option")))
     .build();
 
 

Retrieving values from a field

 
 // Interprets the field value as integer, e.g. <value>123</value>
 Integer intValue = field.getValueAsInteger();

 // Interprets the field value as boolean, e.g. <value>1</value>
 boolean boolValue = field.getValueAsBoolean();
 
 

This class is immutable.

See Also:

3.2 The Field Element

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	DataForm.Field.Builder A builder class to build a data form field.
static class	DataForm.Field.Type Defines field types.

Method Summary

Modifier and Type	Method and Description
static DataForm.Field.Builder	builder() Creates the builder to build a data form field.
int	compareTo(DataForm.Field o)
String	getDescription() Gets a natural-language description of the field, intended for presentation in a user-agent (e.g., as a "tool-tip", help button, or explanatory text provided near the field).
String	getLabel() Gets the field label.
Media	getMedia() Gets the media element.
List<DataForm.Option>	getOptions() Gets the options if the field type is DataForm.Field.Type.LIST_SINGLE or DataForm.Field.Type.LIST_MULTI.
DataForm.Field.Type	getType() Gets the field type.
Validation	getValidation() Gets the validation for this field.
String	getValue() Gets the value of the field.
boolean	getValueAsBoolean() Gets the value as boolean.
Instant	getValueAsInstant() Returns the first value as date.
Integer	getValueAsInteger() Returns the first value as integer.
Jid	getValueAsJid() Returns the first value as JID, e.g. for the DataForm.Field.Type.JID_SINGLE field type.
List<String>	getValues() Gets the values of the field.
List<Jid>	getValuesAsJid() Returns a JID list for the DataForm.Field.Type.JID_MULTI field type.
String	getVar() Gets a unique identifier for the field in the context of the form.
boolean	isRequired() If the field as required in order for the form to be considered valid.
String	toString()

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

Method Detail

builder

public static DataForm.Field.Builder builder()

Creates the builder to build a data form field.

Returns:

The builder.

getType

public final DataForm.Field.Type getType()

Gets the field type.

Returns:

The field type.

getVar

public final String getVar()

Gets a unique identifier for the field in the context of the form.

Returns:

The var attribute.

getLabel

public final String getLabel()

Gets the field label.

Returns:

The label.

getOptions

public final List<DataForm.Option> getOptions()

Gets the options if the field type is DataForm.Field.Type.LIST_SINGLE or DataForm.Field.Type.LIST_MULTI.

Returns:

The options.

getValues

public final List<String> getValues()

Gets the values of the field. Fields of type DataForm.Field.Type.LIST_MULTI, DataForm.Field.Type.JID_MULTI or DataForm.Field.Type.TEXT_MULTI may contain multiple values.

Returns:

The values.

getValue

public final String getValue()

Gets the value of the field.

Returns:

The value.

getValueAsBoolean

public final boolean getValueAsBoolean()

Gets the value as boolean.

Returns:

The value as boolean.

getValueAsInteger

public final Integer getValueAsInteger()

Returns the first value as integer.

Returns:

The integer or null, if the values are empty.

getValueAsInstant

public final Instant getValueAsInstant()

Returns the first value as date.

Returns:

The date or null, if the values are empty.

getValuesAsJid

public final List<Jid> getValuesAsJid()

Returns a JID list for the DataForm.Field.Type.JID_MULTI field type.

Returns:

The JID list.

getValueAsJid

public final Jid getValueAsJid()

Returns the first value as JID, e.g. for the DataForm.Field.Type.JID_SINGLE field type.

Returns:

The JID or null, if the values are empty.

getMedia

public final Media getMedia()

Gets the media element.

Returns:

The media element.

getDescription

public final String getDescription()

Gets a natural-language description of the field, intended for presentation in a user-agent (e.g., as a "tool-tip", help button, or explanatory text provided near the field).

Returns:

The description.

getValidation

public final Validation getValidation()

Gets the validation for this field.

Returns:

The validation.

See Also:

XEP-0122: Data Forms Validation

isRequired

public final boolean isRequired()

If the field as required in order for the form to be considered valid.

Returns:

True, if the field is required.

compareTo

public final int compareTo(DataForm.Field o)

Specified by:

compareTo in interface Comparable<DataForm.Field>

toString

public final String toString()

Overrides:

toString in class Object