Package rocks.xmpp.extensions.data.model

Class 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

    • Method Detail

      • findValue

        public final String findValue​(String name)
        Gets the value for a specific field.
        Parameters:
        name - The field name.
        Returns:
        The value or null, if the field does not exist.

      • findValues

        public final List<String> findValues​(String name)
        Gets the values for a specific field.
        Parameters:
        name - The field name.
        Returns:
        The values.

      • findValueAsBoolean

        public final boolean findValueAsBoolean​(String name)
        Finds the field and gets the value as boolean.
        Parameters:
        name - The field name.
        Returns:
        The value as boolean.

      • findValueAsInteger

        public final Integer findValueAsInteger​(String name)
        Finds the field and gets its value as integer.
        Parameters:
        name - The field name.
        Returns:
        The value as integer or null, if the field could not be found.

      • findValueAsInstant

        public final Instant findValueAsInstant​(String name)
        Finds the field and gets its value as instant.
        Parameters:
        name - The field name.
        Returns:
        The value as date or null, if the field could not be found.

      • findValueAsJid

        public final Jid findValueAsJid​(String name)
        Finds the field and gets the value as JID.
        Parameters:
        name - The field name.
        Returns:
        The value as JID or null, if the field could not be found.

      • findValuesAsJid

        public final List<Jid> findValuesAsJid​(String name)
        Finds the field and gets its values as JID list. If the field could not be found, an empty list is returned.
        Parameters:
        name - 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.

      • hashCode

        public final int hashCode()
        Overrides:
        hashCode in class Object