com.echomine.jabber.msg

Class DataXField

java.lang.Object

com.echomine.jabber.msg.DataXField

public class DataXField
extends java.lang.Object

Represents the field in the jabber:x:data schema. This field will contain the data to work properly with all the different types of fields as defined by JEP-0004. Note that this is the base class. Every field type extends from this class to provide the proper convenience methods to work with each individual type.

Since:

0.8a4

See Also:

DataXMessage, DataXOption

Field Summary

Fields

Modifier and Type	Field and Description
static java.lang.String	TYPE_BOOLEAN
static java.lang.String	TYPE_FIXED
static java.lang.String	TYPE_HIDDEN
static java.lang.String	TYPE_JID_MULTI
static java.lang.String	TYPE_JID_SINGLE
static java.lang.String	TYPE_LIST_MULTI
static java.lang.String	TYPE_LIST_SINGLE
static java.lang.String	TYPE_TEXT_MULTI
static java.lang.String	TYPE_TEXT_PRIVATE
static java.lang.String	TYPE_TEXT_SINGLE

Constructor Summary

Constructors

Constructor and Description
DataXField() default constructor to use for parsing incoming messages
DataXField(java.lang.String fieldType) constructor that requires only a field type.
DataXField(java.lang.String fieldType, java.lang.String variableName, java.lang.String label) constructs a field with the parameters.

Method Summary

Methods

Modifier and Type	Method and Description
void	addJIDValue(JID jid) Adds a jid to the list of field values.
protected void	addOption(DataXOption option) An internal method that adds an option into the options list without doing any validation checks.
void	addTextValue(java.lang.String text) adds the text to the list of field values.
protected void	addValue(java.lang.String value) An internal method that simply adds the string value without doing any validation checks.
Element	encode() encodes the data in this field into an XML Element contained within the designated namespace
boolean	getBooleanValue() Retrieves the first value as a boolean value.
java.lang.String	getDescription()
java.lang.String	getFieldType() retrieves the field type (ie.
JID	getJIDValue() retrieves the first value as a JID object.
java.util.List	getJIDValues() retrieves all the values as a list of JID objects.
java.lang.String	getLabel()
java.util.List	getOptions() gets the options list.
java.lang.String	getStringValue() retrieves the first value as a String type.
java.util.List	getStringValues() retrieves the values sets in the field.
java.lang.String	getVariableName()
boolean	isRequired() whether this field is a required field for input.
void	parse(Element fieldElem) parses the data out of the XML DOM elements
void	setBooleanValue(boolean value) Adds a boolean value to the field.
void	setDescription(java.lang.String description) sets the description
void	setFieldType(java.lang.String fieldType) sets the field type for this field.
void	setJIDValue(JID jid) Adds a jid to the field.
void	setLabel(java.lang.String label) sets the label
void	setOptions(java.util.List ops) sets the list of options to display.
void	setRequired(boolean required) sets the required attribute for this field
void	setTextValue(java.lang.String text) sets the field value to the text specified.
protected void	setValues(java.util.List values) sets the values to a list of values you want added.
void	setVariableName(java.lang.String variableName) sets the variable name

Methods inherited from class java.lang.Object

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

Field Detail

TYPE_BOOLEAN

public static final java.lang.String TYPE_BOOLEAN

See Also:

Constant Field Values

TYPE_FIXED

public static final java.lang.String TYPE_FIXED

See Also:

Constant Field Values

TYPE_HIDDEN

public static final java.lang.String TYPE_HIDDEN

See Also:

Constant Field Values

TYPE_JID_MULTI

public static final java.lang.String TYPE_JID_MULTI

See Also:

Constant Field Values

TYPE_JID_SINGLE

public static final java.lang.String TYPE_JID_SINGLE

See Also:

Constant Field Values

TYPE_LIST_MULTI

public static final java.lang.String TYPE_LIST_MULTI

See Also:

Constant Field Values

TYPE_LIST_SINGLE

public static final java.lang.String TYPE_LIST_SINGLE

See Also:

Constant Field Values

TYPE_TEXT_MULTI

public static final java.lang.String TYPE_TEXT_MULTI

See Also:

Constant Field Values

TYPE_TEXT_PRIVATE

public static final java.lang.String TYPE_TEXT_PRIVATE

See Also:

Constant Field Values

TYPE_TEXT_SINGLE

public static final java.lang.String TYPE_TEXT_SINGLE

See Also:

Constant Field Values

Constructor Detail

DataXField

public DataXField()

default constructor to use for parsing incoming messages

DataXField

public DataXField(java.lang.String fieldType)

constructor that requires only a field type.

DataXField

public DataXField(java.lang.String fieldType,
          java.lang.String variableName,
          java.lang.String label)

constructs a field with the parameters. Only field type is required. The rest are optional and can be null if not used

Parameters:

fieldType - the field type

variableName - the variable name, or null if not used

label - the optional label name, or null if not used

Method Detail

isRequired

public boolean isRequired()

whether this field is a required field for input. Defaults to false

setRequired

public void setRequired(boolean required)

sets the required attribute for this field

getDescription

public java.lang.String getDescription()

Returns:

the description of the field, or empty string if none exists

setDescription

public void setDescription(java.lang.String description)

sets the description

getFieldType

public java.lang.String getFieldType()

retrieves the field type (ie. list-multi, list-single, boolean, text, hidden, etc). The return value can be null if the field type did not exist. The client should assume that the type is text-single if the return type is null.

setFieldType

public void setFieldType(java.lang.String fieldType)

sets the field type for this field. If the field type specified is not supported or if the field type is null, then text-single will be used as the fallback field type.

Throws:

java.lang.IllegalArgumentException - if the field type is not supported

getLabel

public java.lang.String getLabel()

Returns:

the label associated with this field, or null if none exists

setLabel

public void setLabel(java.lang.String label)

sets the label

getVariableName

public java.lang.String getVariableName()

Returns:

the variable name associated with this field, or null if none exists

setVariableName

public void setVariableName(java.lang.String variableName)

sets the variable name

setBooleanValue

public void setBooleanValue(boolean value)

Adds a boolean value to the field. This is used only when you are using the boolean type field. If the field type is set to anything other than boolean type, then this method will throw an IllegalArgumentException. If there are already other values set in this field, then all the values are removed before setting the boolean value.

Parameters:

value - the boolean value to add

Throws:

java.lang.IllegalArgumentException - when the field type is not a boolean type.

setJIDValue

public void setJIDValue(JID jid)

Adds a jid to the field. This method can only be used when the field type is jid-single. If the field type is set to anything other than the specified types, IllegalArgumentException will be thrown. If there are already other values set in this field, then all the values are removed and will effectively be replaced by the JID that is passed in the parameter.

Parameters:

jid - the JID to add

Throws:

java.lang.IllegalArgumentException - when the field type is not a jid-multi type

addJIDValue

public void addJIDValue(JID jid)

Adds a jid to the list of field values. This method can only be used when the field type is jid-multi. If the field type is set to anything other than the specified types, IllegalArgumentException will be thrown. If you have a jid-single type, then you should use the setJIDValue() method instead.

Parameters:

jid - the JID to add

Throws:

java.lang.IllegalArgumentException - when the field type is not a jid-multi type

addTextValue

public void addTextValue(java.lang.String text)

adds the text to the list of field values. This method can only be used when the field type is text-multi or fixed. If the field type is set to anything other than the specified types, IllegalArgumentException will be thrown. If you have a text-single type, then you should use the setTextValue() method instead.

Parameters:

text - the text to add

Throws:

java.lang.IllegalArgumentException - when the field type is not a text-multi type

setTextValue

public void setTextValue(java.lang.String text)

sets the field value to the text specified. This is used only when you are using text-single, text-private, or hidden type field. If the field type is set to anything other than the specified types, IllegalArgumentException will be thrown. If there are already other values set in this field, all the values will be removed and replaced by the new value.

Parameters:

text - the text to store, cannot be null

Throws:

java.lang.IllegalArgumentException - when the field type is not a text-single type

getStringValue

public java.lang.String getStringValue()

retrieves the first value as a String type. This method can be called for any field type. The returned type will be string. If there are multiple values associated with this field, the first value will be returned.

Returns:

the first value as String, or null if there are no values to retrieves

getBooleanValue

public boolean getBooleanValue()

Retrieves the first value as a boolean value. The accepted value is "1" for true and any other string for false ("0", "false", "true" will all return false). This method will work for any field types, but it is normally used to retrieve boolean types.

Returns:

the first value of boolean, or false if there are no values to retrieve

getJIDValue

public JID getJIDValue()
                throws ParseException

retrieves the first value as a JID object. This method will work for any field types, but it is normally used to retrieve JID types. If there is a problem parsing the JID, an exception will be thrown.

Returns:

the JID object or null if there is no value to retrieve

Throws:

ParseException - if there is any problem parsing JID out of a string

getJIDValues

public java.util.List getJIDValues()
                            throws ParseException

retrieves all the values as a list of JID objects. This method will work for any field types, but it is normally used to retrieve JID types. If there is a problem parsing ANY JIDs, an exception will be thrown.

Returns:

a list of JID objects, in the order that was received, or an empty list if no values exist

Throws:

ParseException - if there is any problem parsing ANY JID out of the list of values

addValue

protected void addValue(java.lang.String value)

An internal method that simply adds the string value without doing any validation checks. It is a convenience method called by all the other methods to add values to the list.

Parameters:

value - the text value to add

addOption

protected void addOption(DataXOption option)

An internal method that adds an option into the options list without doing any validation checks.

Parameters:

option - the option to add

getStringValues

public java.util.List getStringValues()

retrieves the values sets in the field. If there are no data, then empty list is returned. The return list of values are not modifiable (ie. it's read-only).

setValues

protected void setValues(java.util.List values)

sets the values to a list of values you want added. This method bypasses validation checks and thus will not check the internal values. This method will clone the data from the list you passed in and store it inside its own list. Passing in null will clear the values list. It is very unlikely you will be using this method unless you are dealing with unknown field types. Otherwise, you will use one of the setXXX() and addXXX() methods to manipulate the list. Currently, this method is not public. If you think you need it, then request that it be made public.

getOptions

public java.util.List getOptions()

gets the options list. If the values are null, then an empty list will be returned. The return list of values are not modifiable (ie. it's read-only).

setOptions

public void setOptions(java.util.List ops)

sets the list of options to display. This method is only usable when field type is list-single or list-multi. If the type is not one of those specified, IllegalArgumentException will be thrown. If there are options available before calling this method, the old values will be replaced by the new ones. This method will clone the data from the list you pass in and store it inside its own list.

Parameters:

ops - a list of DataXOption objects

Throws:

java.lang.IllegalArgumentException - if the field type is not the designated type

parse

public void parse(Element fieldElem)
           throws ParseException

parses the data out of the XML DOM elements

Throws:

ParseException

encode

public Element encode()
               throws ParseException

encodes the data in this field into an XML Element contained within the designated namespace

Throws:

ParseException