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.

Author:

Christian Schudt

See Also:

XEP-0004: Data Forms, XML Schema

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
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.

Constructor Summary

Constructors

Constructor and Description
DataForm(DataForm.Type type) Creates a data form.
DataForm(DataForm.Type type, String title) Creates a data form.
DataForm(DataForm.Type type, String title, String... instructions) Creates a data form.

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).
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)
void	setFormType(String formType) Sets the form type of this data form.
void	setTitle(String title) Sets the title of the form.
void	setType(DataForm.Type type) Sets the form type.

Methods inherited from class java.lang.Object

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

Constructor Detail

DataForm

public DataForm(DataForm.Type type)

Creates a data form.

Parameters:

type - The form type.

DataForm

public DataForm(DataForm.Type type,
                String title)

Creates a data form.

Parameters:

type - The form type.

title - The form title.

DataForm

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

Creates a data form.

Parameters:

type - The form type.

title - The form title.

instructions - The instructions.

Method Detail

parseBoolean

public static boolean parseBoolean(String value)

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.

setFormType

public void setFormType(String formType)

Sets the form type of this data form.

Parameters:

formType - The 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

public void setTitle(String title)

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.

See Also:

setType(DataForm.Type)

setType

public void setType(DataForm.Type type)

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.

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.

getPages

public List<Page> getPages()

Gets the layout pages for this data form.

Returns:

The pages.