rocks.xmpp.extensions.data.model

Class DataForm

java.lang.Object

rocks.xmpp.extensions.data.model.DataForm

All Implemented Interfaces:

Comparable<DataForm>

public final class DataForm
extends Object
implements Comparable<DataForm>

The implementation of the <x/> element in the jabber:x:data namespace, which represents data forms.

This specification defines an XMPP protocol extension for data forms that can be used in workflows such as service configuration as well as for application-specific data description and reporting. The protocol includes lightweight semantics for forms processing (such as request, response, submit, and cancel), defines several common field types (boolean, list options with single or multiple choice, text with single line or multiple lines, single or multiple JabberIDs, hidden fields, etc.), provides extensibility for future data types, and can be embedded in a wide range of applications. The protocol is not intended to provide complete forms-processing functionality as is provided in the W3C XForms technology, but instead provides a basic subset of such functionality for use by XMPP entities.

This class is immutable.

See Also:

XEP-0004: Data Forms, XML Schema

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	DataForm.Builder<T extends DataForm.Builder<T>> An abstract builder to build simple data forms.
static class	DataForm.Field A data form field.
static class	DataForm.Item An item which can be understood as a table row.
static class	DataForm.Option Defines an option in a field of type DataForm.Field.Type.LIST_SINGLE or DataForm.Field.Type.LIST_MULTI.
static class	DataForm.Type The form type.

Field Summary

Fields

Modifier and Type	Field and Description
static String	FORM_TYPE The name of the hidden field, which determines the form type, "FORM_TYPE".
static String	NAMESPACE jabber:x:data

Constructor Summary

Constructors

Constructor and Description
DataForm(DataForm.Builder<? extends DataForm.Builder> builder)
DataForm(DataForm.Type type) Creates a data form.
DataForm(DataForm.Type type, Collection<DataForm.Field> fields) Creates a data form.
DataForm(DataForm.Type type, String title, Collection<DataForm.Field> fields, Collection<DataForm.Field> reportedFields, Collection<DataForm.Item> items, Collection<String> instructions, Collection<Page> pages)

Method Summary

Modifier and Type	Method and Description
int	compareTo(DataForm o) Compares this data form with another data form.
DataForm.Field	findField(String name) Finds a field by its name ('ver' attribute).
String	findValue(String var) Gets the value for a specific field.
boolean	findValueAsBoolean(String var) Finds the field and gets the value as boolean.
Instant	findValueAsInstant(String var) Finds the field and gets its value as instant.
Integer	findValueAsInteger(String var) Finds the field and gets its value as integer.
Jid	findValueAsJid(String var) Finds the field and gets the value as JID.
List<String>	findValues(String var) Gets the values for a specific field.
List<Jid>	findValuesAsJid(String var) Finds the field and gets its values as JID list.
List<DataForm.Field>	getFields() Gets the fields of the form.
String	getFormType() Gets the form type of this form, i.e. the value of the "FORM_TYPE" field.
List<String>	getInstructions() Gets the instructions of the form.
List<DataForm.Item>	getItems() Gets the items, which can be understood as "table rows" containing data (if any) that matches the request.
List<Page>	getPages() Gets the layout pages for this data form.
List<DataForm.Field>	getReportedFields() Gets the reported fields, which can be understood as "table headers" describing the data to follow.
String	getTitle() Gets the title of the form.
DataForm.Type	getType() Gets the type of the form.

Methods inherited from class java.lang.Object

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

Field Detail

NAMESPACE

public static final String NAMESPACE

jabber:x:data

See Also:

Constant Field Values

FORM_TYPE

public static final String FORM_TYPE

The name of the hidden field, which determines the form type, "FORM_TYPE".

See Also:

Constant Field Values

Constructor Detail

DataForm

public DataForm(DataForm.Type type)

Creates a data form.

Parameters:

type - The form type.

DataForm

public DataForm(DataForm.Type type,
                Collection<DataForm.Field> fields)

Creates a data form.

Parameters:

type - The form type.

fields - The fields.

DataForm

public DataForm(DataForm.Builder<? extends DataForm.Builder> builder)

DataForm

public DataForm(DataForm.Type type,
                String title,
                Collection<DataForm.Field> fields,
                Collection<DataForm.Field> reportedFields,
                Collection<DataForm.Item> items,
                Collection<String> instructions,
                Collection<Page> pages)

Method Detail

findValue

public final String findValue(String var)

Gets the value for a specific field.

Parameters:

var - The field name.

Returns:

The value or null, if the field does not exist.

findValues

public final List<String> findValues(String var)

Gets the values for a specific field.

Parameters:

var - The field name.

Returns:

The values.

findValueAsBoolean

public final boolean findValueAsBoolean(String var)

Finds the field and gets the value as boolean.

Parameters:

var - The field name.

Returns:

The value as boolean.

findValueAsInteger

public final Integer findValueAsInteger(String var)

Finds the field and gets its value as integer.

Parameters:

var - The field name.

Returns:

The value as integer or null, if the field could not be found.

findValueAsInstant

public final Instant findValueAsInstant(String var)

Finds the field and gets its value as instant.

Parameters:

var - The field name.

Returns:

The value as date or null, if the field could not be found.

findValueAsJid

public final Jid findValueAsJid(String var)

Finds the field and gets the value as JID.

Parameters:

var - The field name.

Returns:

The value as JID or null, if the field could not be found.

findValuesAsJid

public final List<Jid> findValuesAsJid(String var)

Finds the field and gets its values as JID list. If the field could not be found, an empty list is returned.

Parameters:

var - The field name.

Returns:

The values as JID list.

getFormType

public final String getFormType()

Gets the form type of this form, i.e. the value of the "FORM_TYPE" field.

Returns:

The form type or null, if there is no form type.

getTitle

public final String getTitle()

Gets the title of the form.

The OPTIONAL <title/> and <instructions/> elements enable the form-processing entity to label the form as a whole and specify natural-language instructions to be followed by the form-submitting entity. The XML character data for these elements SHOULD NOT contain newlines (the \n and \r characters), and any handling of newlines (e.g., presentation in a user interface) is unspecified herein; however, multiple instances of the <instructions/> element MAY be included.

Returns:

The title.

getFields

public final List<DataForm.Field> getFields()

Gets the fields of the form.

Returns:

The fields.

getInstructions

public final List<String> getInstructions()

Gets the instructions of the form.

The OPTIONAL <title/> and <instructions/> elements enable the form-processing entity to label the form as a whole and specify natural-language instructions to be followed by the form-submitting entity. The XML character data for these elements SHOULD NOT contain newlines (the \n and \r characters), and any handling of newlines (e.g., presentation in a user interface) is unspecified herein; however, multiple instances of the <instructions/> element MAY be included.

Returns:

The instructions.

getType

public final DataForm.Type getType()

Gets the type of the form.

Returns:

The type.

getReportedFields

public final List<DataForm.Field> getReportedFields()

Gets the reported fields, which can be understood as "table headers" describing the data to follow.

Returns:

The reported fields.

getItems

public final List<DataForm.Item> getItems()

Gets the items, which can be understood as "table rows" containing data (if any) that matches the request.

Returns:

The items.

getPages

public final List<Page> getPages()

Gets the layout pages for this data form.

Returns:

The pages.

findField

public final DataForm.Field findField(String name)

Finds a field by its name ('ver' attribute).

Parameters:

name - The name.

Returns:

The field or null if the field could be found.

compareTo

public final int compareTo(DataForm o)

Compares this data form with another data form. Data forms which have a "FORM_TYPE" field are are listed first in a collection.

Specified by:

compareTo in interface Comparable<DataForm>

Parameters:

o - The other data form.

Returns:

The comparison result.