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.

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 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) Deprecated.
DataForm(DataForm.Type type, String title, Collection<DataForm.Field> fields, Collection<DataForm.Field> reportedFields, Collection<DataForm.Item> items, Collection<String> instructions, Collection<Page> pages)
DataForm(DataForm.Type type, String title, String... instructions) Deprecated.

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.
Date	findValueAsDate(String var) Finds the field and gets its value as date.
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.
static boolean	parseBoolean(String value) Parses a value as boolean.
void	setTitle(String title) Deprecated. Use constructor.
void	setType(DataForm.Type type) Deprecated. Use constructor.

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

@Deprecated
public DataForm(DataForm.Type type,
                            String title)

Deprecated.

Creates a data form.

Parameters:

type - The form type.

title - The form title.

DataForm

@Deprecated
public DataForm(DataForm.Type type,
                            String title,
                            String... instructions)

Deprecated.

Creates a data form.

Parameters:

type - The form type.

title - The form title.

instructions - The instructions.

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

parseBoolean

public static boolean parseBoolean(String value)

Parses a value as boolean. Positive values as per XEP-0004 are "1" and "true".

Parameters:

value - The value.

Returns:

The parsed boolean value.

findValue

public 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 List<String> findValues(String var)

Gets the values for a specific field.

Parameters:

var - The field name.

Returns:

The values.

findValueAsBoolean

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

findValueAsDate

public Date findValueAsDate(String var)

Finds the field and gets its value as date.

Parameters:

var - The field name.

Returns:

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

findValueAsJid

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

setTitle

@Deprecated
public void setTitle(String title)

Deprecated. Use constructor.

Sets the title of the form.

Parameters:

title - The title.

See Also:

getTitle()

getFields

public List<DataForm.Field> getFields()

Gets the fields of the form.

Returns:

The fields.

getInstructions

public 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 DataForm.Type getType()

Gets the type of the form.

Returns:

The type.

setType

@Deprecated
public void setType(DataForm.Type type)

Deprecated. Use constructor.

Sets the form type.

Parameters:

type - The form type.

See Also:

getType()

getReportedFields

public 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 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 List<Page> getPages()

Gets the layout pages for this data form.

Returns:

The pages.

findField

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